卡片添加

支持长按应用图标或者负一屏的卡片添加按钮添加

卡片数据定时更新

一、配置刷新策略
在 form_config.json文件中完成以下配置：1

{
  "forms": [
    {
      "name": "widget",
      "updateEnabled": true,        // 启用自动刷新
      "updateDuration": 2,          // 定时刷新（单位：30分钟，此处为每小时一次）
      "scheduledUpdateTime": "10:30"// 定点刷新（每天10:30触发）
    }
  ]
}

定时刷新：updateDuration设置为非零值，表示每 N*30 分钟刷新一次（如 2表示 1 小时）[⁷][¹⁴]。
定点刷新：设置 scheduledUpdateTime为特定时间（需将 updateDuration设为 0）[⁷][¹³]。
二、实现刷新逻辑在 EntryFormAbility.ets中实现 onUpdateForm生命周期回调：

onUpdateForm(formId: string) {
  // 获取最新数据（如网络请求、本地存储等）
  let newData = {
    'title': '更新标题',
    'content': '更新内容'
  };
  // 创建绑定数据
  let formData = formBindingData.createFormBindingData(newData);
  // 推送数据更新
  formProvider.updateForm(formId, formData).catch((error) => {
    console.error('更新失败:', error);
  });
}

此方法会在定时/定点刷新触发时自动执行[⁴][⁹]。

三、进阶控制

动态设定下次刷新时间
通过 setFormNextRefreshTime指定下一次刷新间隔（最短 5 分钟）：

   formProvider.setFormNextRefreshTime(formId, 5, (err) => {
     if (err) {
       console.error('设置失败:', err);
     }
   });

[²][⁷]

状态感知刷新
结合 postCardAction实现不同状态下的差异化刷新（如不同城市天气）：

   // 卡片UI中触发事件
   postCardAction({
     action: 'updateCity',
     city: '北京'
   });

四、注意事项

优先级规则
定时刷新（updateDuration）优先级高于定点刷新（scheduledUpdateTime），二者共存时仅定时生效[⁷][¹³]。
可见性约束
定点刷新仅在卡片可见时触发，不可见时记录动作，待可见后统一刷新[¹³]。
功耗优化
应用市场可动态配置刷新周期，取开发者配置与应用市场配置的较长周期[¹⁴]。
最小间隔
定时刷新最短间隔为 30 分钟，动态设置下次刷新最短间隔为 5 分钟[⁷][¹⁴]。

卡片内组件事件

卡片内支持的操作有下面三种,比如点击某个按钮之后触发某个操作
router 跳转至前台UIAbility 页面直达 通过params参数传递
call 后台运行UIAbility 后台任务执行 调用指定方法
message 通知FormExtension 卡片内容动态更新 消息字符串或JSON

卡片移除

手动操作进行移除

卡片功能控制器

声明 FormExtensionAbility
在 module.json5中配置 EntryFormAbility的元数据，指向卡片配置文件：

   "extensionAbilities": [{
     "name": "EntryFormAbility",
     "srcEntry": "./ets/entryformability/EntryFormAbility.ets",
     "type": "form",
     "metadata": [{
       "name": "ohos.extension.form",
       "resource": "$profile:form_config"
     }]
   }]

FormExtensionAbility
通过实现以下回调函数管理卡片的状态：

onAddForm：卡片创建时触发，用于初始化数据（如从本地数据库读取状态、加载本地图片等）[23]。
onFormEvent：卡片事件响应（如用户点击操作）[]。
onUpdateForm：卡片主动或周期性刷新时调用[]。
onRemoveForm：卡片销毁时触发[]。

page里面更新卡片数据

在鸿蒙应用页面（Page）中更新卡片数据需要通过formProvider.updateForm()接口实现，关键在于获取卡片实例ID（formId）和正确使用数据绑定。以下是具体实现步骤及代码示例：

一、前置条件

1. 卡片配置：在form_config.json中启用更新功能¹

      {
        "forms": [
          {
            "name": "widget",
            "updateEnabled": true, // 启用自动更新
            "scheduledUpdateTime": "10:30", // 定点刷新时间（可选）
            "updateDuration": 2 // 定时刷新间隔（小时，0表示关闭）
          }
        ]
      }
   

二、核心实现步骤

1. 存储卡片formId

在卡片被添加到桌面时（onAddForm生命周期），保存formId到AppStorage：

   // UIAbility中
   import { FormInfo, formProvider } from '@kit.FormKit';
   import { AppStorage } from '@kit.ArkData';
   
   onAddForm(want: Want) {
     let formId: string = want.parameters['ohos.extra.param.key.form_identity'] as string;
     AppStorage.setOrCreate('formId', formId); // 存储到应用全局存储
   }

2. 页面中更新卡片数据

在Page页面中获取formId并调用更新接口：

   import { formProvider, formBindingData } from '@kit.FormKit';
   import { AppStorage } from '@kit.ArkData';
   
   @Entry
   @Component
   struct SettingsPage {
     @StorageLink('formId') formId: string = ''; // 从AppStorage获取formId
   
     // 点击按钮触发更新
     updateCard() {
       if (!this.formId) return;
       
       let newData = {
         'title': '最新数据',
         'temperature': '26℃',
         'time': new Date().toLocaleTimeString()
       };
       
       let bindingData = formBindingData.createFormBindingData(newData);
       
       formProvider.updateForm(this.formId, bindingData)
         .then(() => console.info('更新成功'))
         .catch(err => console.error('更新失败', err));
     }
   
     build() {
       Column() {
         Button('更新卡片数据')
           .onClick(() => this.updateCard())
       }
     }
   }

三、注意事项

1. 数据绑定一致性：卡片布局文件中需使用与newData对象相同的键名（如title、temperature）
2. formId有效性：若用户删除卡片后未更新存储的formId，需做容错处理
3. 线程限制：updateForm()需在主线程调用，异步操作需使用async/await
4. 数据大小限制：extraData字段需遵守系统约束（通常不超过2KB）²

四、高级场景

若需要网络请求后更新：

   async fetchDataAndUpdate() {
     try {
       let response = await http.get('https://api.example.com/data');
       let bindingData = formBindingData.createFormBindingData(response.data);
       await formProvider.updateForm(this.formId, bindingData);
     } catch (error) {
       console.error('更新失败', error);
     }
   }

建议在FormExtensionAbility中进行网络请求，通过onUpdateForm触发更新

page里面点击长按按钮添加卡片,不支持普通开发者使用