【FAQ】HarmonyOS SDK 闭源开放能力 — Form Kit

1.问题描述：

主 app 进入后台，此时切换系统菜单暗黑模式按钮，卡片如何监听系统 colorMode ，此时卡片如何做暗黑模式切换？

解决方案：

适配方案依靠资源目录，当系统对应的设置项发生变化后（如系统语言、深浅色模式等），应用会自动加载对应资源目录下的资源文件。系统为深色模式预留了 dark 目录，该目录在应用创建时默认不存在，在进行深色模式适配时，需要开发者在 src/main/resources 中手动创建出 dark 目录，将深色模式所需的资源放置到该目录下。对于浅色模式所需的资源，可以放入默认存在的 src/main/resources/base 目录下。具体步骤为：

1. 在 src/main/resources/base/element/color.json 文件中定义页面元素在浅色模式下的颜色值。

    {
      "color": [
        {
          "name": "text_color",
          "value": "#000000"
        }
      ]
    }

2. 在 src/main/resources/dark/element/color.json 文件中定义页面元素在浅色模式下的颜色值。

    {
      "color": [
        {
          "name": "text_color",
          "value": "#FFFFFF"
        }
      ]
    }

3. 在代码中引用自定义的颜色资源值，使用 $r 加载自定义颜色资源，系统将自动在应用深浅色变化时，加载对应限定词目录下的资源文件，从而改变页面元素的颜色完成深浅色适配。

    @Entry
    @Component
    struct Card {
      build() {
        Row() {
          Text('hello')
            .fontColor($r('app.color.text_color'))
        }
        .width('100%')
        .height('100%')
      }
    }

2.问题描述：

FormExtensionAbility 生命周期中提供了 onConfigurationUpdate 生命周期回调，该生命周期回调在系统深浅色模式发生变化时是否会触发？

解决方案：

因系统规格设计，当系统配置项变更时，仅系统应用拉活应用服务卡片对应的 EntryFormAbility 并触发相应的 onConfigurationUpdate 回调函数。

三方应用仅当 FormExtensionAbility 存活时才会触发 onConfigurationUpdate 回调。

3.问题描述：

通过 mediaquery.matchMediaSync 接口可以设置媒体查询的查询条件，是否可以通过 mediaquery.matchMediaSync('(dark-mode: true)')直接在卡片页面注册系统深浅色监听回调？

解决方案：

由于卡片规格限制，虽然该接口支持在 ArkTS 卡片页面中使用，但是无法监听获取查询结果。

4.问题描述：

是否可以使用 PersistentStorage 和 AppStorage 在应用和卡片之间进行状态数据共享？

解决方案：

卡片和应用的主进程不是一个进程，而 AppStorage 是和进程绑定的，仅支持应用的主线程内多个 UIAbility 实例间的 UI 状态数据共享，所以卡片和应用主进程之间无法使用 PersistentStorage 和 AppStorage 进行状态数据共享。

5.问题描述：

跨进程经常需要数据共享如服务卡片和其主应用，但在主应用更新首选项数据后，在服务卡片中用取到的值错误的场景。

解决方案：

不同进程的内存不共享，同一进程中 getPreferences 只有首次会从持久化中取，所以要跨进程读取最新的持久化数据时，需先通过 preferences.removePreferencesFromCache 接口将 Preferences 实例移出缓存中的实例之后，再次 getPreferences 将会重新读取持久化文件，生成新的 Preferences 实例。

以主应用中更新首选项中的 data，在服务卡片中通过首选项取 data 为例。

在主应用中更新 data，并通知服务卡片更新。

preferences.getPreferences(this.context, 'myPreference', (err: BusinessError, pf: preferences.Preferences) => {
    if (err) {
        console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
        return;
    }
    pf.put("formData", data);
    pf.flush();
    formProvider.updateForm(curFormId, formMsg);
    console.info("Succeeded in getting preferences.");
})

卡片中收到更新事件如 onFormEvent 方法回调时，需要先通过 removePreferencesFromCache 清缓存的 Preferences 实例再重新取 Preferences 实例。

async function getCache() {
    await preferences.removePreferencesFromCache(context, 'myPreference');
    const pf = await preferences.getPreferences(context, 'myPreference');
    const data = await pf.get('formData', 'fault');
    console.info("cache data: " + data);
}