【鸿蒙】OpenHarmony服务卡片的用法详解_鸿蒙 service widget import declaration can't support

卡片概述

卡片是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。

卡片展示

卡片常用于嵌入到其他应用（当前仅支持系统应用，例如 Launcher）中作为其界面的一部分显示，并支持拉起页面，发送消息等基础的交互功能。

卡片的基本概念：

卡片提供方：提供卡片显示内容原子化服务，控制卡片的显示内容、控件布局以及控件点击事件。

包含以下模块：

• 卡片服务：由卡片提供方开发者实现，开发者实现 onCreate、onUpdate 和 onDestroy 处理创建卡片、更新卡片以及销毁卡片等请求，提供相应的卡片服务。
• 卡片实例管理模块：由卡片提供方开发者实现，负责对卡片管理服务分配的卡片实例进行持久化管理。
• 通信适配层：由 OpenHarmony SDK 提供，负责与卡片管理服务通信，用于将卡片的更新数据主动推送到卡片管理服务。

卡片使用方：显示卡片内容的宿主应用，负责显示卡片，控制卡片在宿主中展示的位置。

卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。

包含以下模块：

• 周期性刷新：在卡片添加后，根据卡片的刷新策略启动定时任务周期性触发卡片的刷新。
• 卡片缓存管理：在卡片添加到卡片管理服务后，对卡片的视图信息进行缓存，以便下次获取卡片时可以直接返回缓存数据，降低时延。
• 卡片生命周期管理：对于卡片切换到后台或者被遮挡时，暂停卡片的刷新；以及卡片的升级/卸载场景下对卡片数据的更新和清理。
• 卡片使用方对象管理：对卡片使用方的 RPC 对象进行管理，用于使用方请求进行校验以及对卡片更新后的回调处理。
• 通信适配层：负责与卡片使用方和提供方进行 RPC 通信。

卡片使用方和提供方不要求常驻运行，在需要添加/删除/请求更新卡片时，卡片管理服务会拉起卡片提供方获取卡片信息。

开发者仅需作为卡片提供方进行卡片内容的开发，卡片使用方和卡片管理服务由系统自动处理。

场景介绍

基于****FA 模型的卡片提供方开发，主要涉及如下功能逻辑：

• 开发卡片生命周期回调函数 LifecycleForm

• 创建卡片数据 FormBindingData 对象

• 通过 FormProvider 更新卡片

• 开发卡片页面
  基于****Stage 模型的卡片提供方开发，主要涉及如下功能逻辑：

• 卡片生命周期回调函数 FormExtension 开发

• 创建卡片数据 FormBindingData 对象

• 通过 FormProvider 更新卡片

• 卡片页面开发

卡片开发指导

卡片提供方创建卡片

1.打开 DevEco 3.0.0.993 新建一个项目
2.选择一个 module 创建卡片，每个 module 最多创建 16 张卡片，此处以 entry 为例。
选中 entry 文件夹，右键 New–>Extension Ability -->Service Widget

• FA 模型项目
  
• Stage 模型项目
  

3.任选一种卡片模板。OpenHarmony 目前支持以下三种卡片模板：
HelloWorld : 支持低代码开发的 HelloWorld 卡片。 Image With Information : 图文卡片。图文卡片模板主要在于展现图片和一定数量文本的搭配，在这种布局下，图片和文本属于同等重要的信息。在不同尺寸下，图片大小和文本数量会发生一定变化，用于凸显关键信息。 Immersive Information : 沉浸式卡片。 沉浸式卡片的装饰性较强，能够较好的提升卡片品质感并起到装饰桌面的作用，合理的去布局信息与背景图片之间的空间比例，可以提升用户的个性化使用体验。

4.设置卡片信息。

Service widget name：卡片的名称，卡片名称不能重复，且只能包含数字、字母和下划线。

Description：卡片的描述信息。

Enable Super Visual：是否选择低代码方式开发。

Language：界面开发语言，目前只支持 js。

Support dimensions：选择卡片的规格。部分卡片支持同时设置多种规格。 Ability name：选择一个挂靠服务卡片的 Page Ability，或者创建一个新的 Page Ability。 Module name：卡片所属的模块。

5.点击 Finish，完成卡片的创建之后，会生成如下文件。

• FA 模型项目

• Stage 模型项目
  

6.安装应用到设备上，在设备的桌面上长按应用图标，等待出现服务卡片字样，点击后选择需要的卡片尺寸，添加到屏幕。

卡片页面文件说明

JS 卡片页面通过 hml+css+json 开发

• index.hml 文件：
  卡片的显示页面，卡片上显示的数据及事件均在 index.json 中定义，在 FormAbility.ts 中修改和处理。
  index.hml 中标签为 OpenHarmony 专用，目前支持 div、list、list-item、swiper、stack、image、text、span、progress、button（定制：chart 、clock、calendar）。hml 文件中可使用类似 vue 的模板语法，支持{{}},if,show,for 等。
  代码示例：

<div class="container">
      <stack >
          <div class="container-inner" onclick="routerPage" >
              <!-- $t('strings.temperature') 是从string.json资源文件中读取值--> 
              <!-- temperature 是获取index.json文件的data中定义的变量 --> 
              <text class="title" show="true">{{ $t('strings.temperature') }}{{temperature}} ℃</text>
              <text class="title" onclick="onUpdateEvent">{{ $t('strings.time') }} {{time}}</text>
          </div>
      </stack>
  </div>
1
2
3
4
5
6
7
8
9
10

​

• index.css 文件：
  存放 index.hml 页面中使用的 css 样式。
  代码示例：

.container {
    flex-direction: column;
    justify-content: center;
    align-items: center;
}
1
2
3
4
5

​

• index.json 文件：
  存放卡片页面 index.hml 中的变量及事件。
  内部字段结构说明：
  data：存放的是 index.hml 中使用到的变量
  代码示例：

"data": {
    "temperature": "0",
    "time": "00:00:00"
}
1
2
3
4

​

• actions: 存放的是 index.hml 中使用的事件，有两种类型：router 和 message。
  router 类型事件：用于卡片提供方进行跳转，需相应配置 abilityName 属性用于存放目标 Ability 名称。
  message 类型事件：用于卡片与卡片提供方进行交互，会触发卡片生命周期中的 onEvent 方法。
  代码示例：

"actions": {
    "routerPage": {
        "action": "router",
        "abilityName": "ohos.samples.FormApplication.MainAbility",
        "params": {
            "message": "add detail"
        }
    },
    "onUpdateEvent": {
        "action": "message",
        "params": {
            "name" : "onUpdateEvent",
            "message": "add detail"
        }
    },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

​

卡片配置文件

Stage 模型下的卡片配置文件

module.json5
卡片需要在应用配置文件 module.json5 中的 extensionAbilities 标签下，配置 ExtensionAbility 相关信息。

内部字段结构说明：

对于 FormExtensionAbility 来说，需要填写 metadata 元信息标签，其中键名称为固定字符串"ohos.extension.form"，资源为卡片的具体配置信息的索引。

示例：

"extensionAbilities": [
    {
        "name": "FormAbility",
        "srcEntrance": "./ets/FormAbility/FormAbility.ts",
        "label": "$string:form_FormAbility_label",
        "description": "$string:form_FormAbility_desc",
        "type": "form",
        "metadata": [
            {
                "name": "ohos.extension.form",
                "resource": "$profile:form_config",
            },
        ],
    },
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

​
form_config.json

卡片的具体配置信息。在上述 FormExtensionAbility 的元信息中，指定了的卡片具体配置信息的资源索引，如使用 $profile:form_config 指定开发视图的 resources/base/profile/ 目录下的 form_config.json 作为卡片 profile 配置文件。

内部字段结构说明：

示例：

{
  "forms": [
    {
      "name": "widget",
      "description": "This is a service widget.",
      "src": "./js/widget/pages/index/index",
      "formConfigAbility": "ability://ohos.samples.FormApplication.MainAbility",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "11:32",
      "updateDuration" : 1,
      "defaultDimension": "2*4",
      "supportDimensions": ["2*4", "4*4"]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

​

FA 模型下的卡片配置文件

FA 模型的卡片只需在项目的配置文件 config.json 中进行配置，分为 js 模块和 ability 模块两个部分。

• js 模块，用于对应卡片的 js 相关资源，内部字段结构说明：

配置示例如下：

"js": [{
    "name": "widget",
    "pages": ["pages/index/index"],
    "window": {
        "designWidth": 720,
        "autoDesignWidth": true
    },
    "type": "form"
}]
1
2
3
4
5
6
7
8
9

​

• abilities 模块，用于对应卡片的 LifecycleForm，内部字段结构说明：| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
  | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------- |
  | name | 表示卡片名，即在 onCreate 方法中根据 want.parameters[“ohos.extra.param.key.form_name”]可取到的值。字符串最大长度为 127 字节。 | 字符串 | 否 |
  | description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为 255 字节。 | 字符串 | 可缺省，缺省为空。 |
  | isDefault | 表示该卡片是否为默认卡片，每个 Ability 有且只有一个默认卡片。 true：默认卡片。 false：非默认卡片。 | 布尔值 | 否 |
  | type | 表示卡片的类型。取值范围如下： JS：JS 卡片。 | 字符串 | 否 |
  | colorMode | 表示卡片的主题样式，取值范围如下： auto：自适应。 dark：深色主题。 light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 |
  | supportDimensions | 表示卡片支持的外观规格，取值范围： 1 * 2：表示 1 行 2 列的二宫格。 2 * 2：表示 2 行 2 列的四宫格。 2 * 4：表示 2 行 4 列的八宫格。 4 * 4：表示 4 行 4 列的十六宫格。 | 字符串数组 | 否 |
  | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片 supportDimensions 配置的列表中。 | 字符串 | 否 |
  | updateEnabled | 表示卡片是否支持周期性刷新，取值范围： true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。 false：表示不支持周期性刷新。 | 布尔类型 | 否 |
  | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用 24 小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 |
  | updateDuration | 表示卡片定时刷新的更新周期，单位为 30 分钟，取值为自然数。 当取值为 0 时，表示该参数不生效。 当取值为正整数 N 时，表示刷新周期为 30*N 分钟。 | 数值 | 可缺省，缺省值为“0”。 |
  | formConfigAbility | 表示卡片的配置跳转链接，采用 URI 格式。 | 字符串 | 可缺省，缺省值为空。 |
  | formVisibleNotify | 标识是否允许卡片使用卡片可见性通知。 | 字符串 | 可缺省，缺省值为空。 |
  | jsComponentName | 表示 JS 卡片的 Component 名称。字符串最大长度为 127 字节。 | 字符串 | 否 |
  | metaData | 表示卡片的自定义信息，包含 customizeData 数组标签。 | 对象 | 可缺省，缺省值为空。 |
  | customizeData | 表示自定义的卡片信息。 | 对象数组 | 可缺省，缺省值为空。 |
  | formsEnabled | 标识 Ability 是否支持卡片（forms）功能。该标签仅适用于 page 类型的 Ability。 true：支持卡片能力。 false：不支持卡片能力。 | 布尔值 | 可缺省，缺省值为“false”。 |

配置示例如下：

"abilities": [{
    "name": "FormAbility",
    "description": "This is a FormAbility",
    "formsEnabled": true,
    "icon": "$media:icon",
    "label": "$string:form_FormAbility_label",
    "srcPath": "FormAbility",
    "type": "service",
    "srcLanguage": "ets",
    "formsEnabled": true,
    "forms": [{
        "colorMode": "auto",
        "defaultDimension": "2*2",
        "description": "This is a service widget.",
        "formVisibleNotify": true,
        "isDefault": true,
        "jsComponentName": "widget",
        "name": "widget",
        "scheduledUpdateTime": "10:30",
        "supportDimensions": ["2*2"],
        "type": "JS",
        "updateDuration": 1,
        "updateEnabled": true
    }]
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

​

页面拉起功能

为卡片配置跳转类型的事件 routerEvent，实现点击卡片拉起卡片应用。

跳转事件通过拉起本应用的 Ability 来打开应用，跳转事件中配置的参数 params 会被包含在 Ability 的 onCreate 生命周期函数的 want 参数中。

实现步骤如下：

1.在 index.hml 页面添加点击事件 routerEvent。

<div class="container-inner" onclick="routerEvent"></div>
1

​
2.在 index.json 中的 actions 标签下定义 routerEvent 事件
action 字段填 router，表明是跳转事件 abilityName 填写要跳转的 Ability 名

"actions": {
    "routerEvent": {
        "action": "router",
        "abilityName": "ohos.samples.FormApplication.MainAbility",
        "params": {
        	"message": "add detail"
        }
    },
}
1
2
3
4
5
6
7
8
9

数据交互功能

卡片提供了动态刷新卡片数据的能力。

例如，在 index.hml 页面中展示两个数据：temperature 和 time

  <text class="title" >{{ $t('strings.temperature') }}{{temperature}} ℃</text>
    <text class="title" onclick="messageEvent">{{ $t('strings.time') }} {{time}}</text>

1
2
3

数据 temperature 和 time 已在 index.json 中定义：

{
    "data": {
        "temperature": "0",
        "time": "00:00:00"
    }
}
1
2
3
4
5
6

​
可以通过以下方式来实现卡片的数据交互。

手动刷新数据

通过调用 message 类型的事件触发卡片生命周期函数 onEvent，在 onEvent 函数中可以获取到当前卡片实例的 Id 及传入的事件信息。

在 onEvent 函数中根据事件名来进行不同的操作，当传入的是更新数据的事件名时，调用 formProvider 接口的 updateForm 方法来更新卡片数据。

1.在 index.hml 文件中创建按钮，绑定 onUpdateEvent 事件

<button class="button" type="capsule" onclick="onUpdateEvent" >手动更新</button>
1

​
2.在 index.json 文件中声明 onUpdateEvent 事件，action 类型为 message

{
    "data": {
        "temperature": "0",
        "time": "00:00:00"
    },
    "actions":{
        "onUpdateEvent": {
            "action": "message",
            "params": {
                "name" : "onUpdateEvent",
                "message": "add detail"
            }
        }
    }
}
​
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

3.在 FormAbility.ts 中的 onEvent 方法中，获取事件名 onUpdateEvent，然后进行卡片数据更新操作。

import formBindingData from '@ohos.application.formBindingData';
import formProvider from '@ohos.application.formProvider';

var timer: number = 0

//卡片页面数据刷新函数
async function updateFormData(formId: string) {
    let obj = {
        "temperature": getTemperature(formId, formInfo.updateCount).toString(),
        "time": getTime()
    }
    let formData = formBindingData.createFormBindingData(obj)
    formProvider.updateForm(formId, formData).catch(err => {
        Logger.error("updateOne err : " + JSON.stringify(err))
    })
}

onEvent(formId, message) {
    console.log("FormAbility onEvent, formId = " + formId + ", message:" + JSON.stringify(message));
    let jsonParams = JSON.parse(message)
        //获取事件名
    let eventName = jsonParams.params.name
    switch (eventName) {
        case "onUpdateEvent":
            updateFormData(formId);
            break;
        default:
            console.log("(onEvent) formId :" + formId + " message : " + message)
            break;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

​

定点刷新数据

在卡片配置文件中可以配置 scheduledUpdateTime 属性来实现卡片定点刷新数据，

scheduledUpdateTime 表示卡片的定点刷新的时刻，采用 24 小时制，精确到分钟。

时间到达 scheduledUpdateTime 参数设置的时刻时，会触发卡片生命周期的 onUpdate 方法，在 onUpdate 方法中执行卡片数据更新操作。

代码示例：

Stage 模型在 form_config.json 文件中配置 scheduledUpdateTime 属性:

{
    "forms": [
        {
            //...
            "scheduledUpdateTime": "11:32",
            "updateDuration" : 0,
            //...
        }
    ]
}
1
2
3
4
5
6
7
8
9
10

​
FA 模型在 config.json 文件中配置 scheduledUpdateTime 属性：

{
    "forms": [
        {
            //...
            "scheduledUpdateTime": "11:32",
            "updateDuration" : 0,
            //...
        }
    ]
}
1
2
3
4
5
6
7
8
9
10

​
FormAbility.ts 中的 onUpdate 生命周期函数：

onUpdate(formId) {
    console.log("FormAbility onUpdate, formId:" + formId);
    //卡片数据更新方法
    updateFormData(formId);
}
​
1
2
3
4
5
6

定时刷新数据

方式一：通过配置文件，配置定时刷新数据

在卡片配置文件 form_config.json 中可以配置来实现卡片定时刷新数据，

updateDuration 属性表示卡片定时刷新的更新周期，单位为 30 分钟，取值为自然数（正整数或 0）。

当取值为 0 时，表示该参数不生效。

当取值为正整数 N 时，表示刷新周期为 30×N 分钟，每隔 30×N 分钟会触发卡片生命周期的 onUpdate 方法，在 onUpdate 方法中执行卡片数据更新操作。

当取值为正整数 N 时，定点刷新数据不生效。

示例：

Stage 模型在 form_config.json 文件中配置 updateDuration 属性:

{
    "forms": [
        {
            ...
            "updateDuration" : 1,
            ...
        }
    ]
}
​
1
2
3
4
5
6
7
8
9
10

FA 模型在 config.json 文件中配置 updateDuration 属性：

{
    "forms": [
        {
            ...
            "updateDuration" : 1,
            ...
        }
    ]
}
​
1
2
3
4
5
6
7
8
9
10

FormAbility.ts 中的 onUpdate 生命周期函数：

onUpdate(formId) {
    console.log("FormAbility onUpdate, formId: " + formId);
    //卡片数据更新方法
    updateFormData(formId);
}
​
1
2
3
4
5
6

方式二：通过 FormProvider 接口，设置过多少分钟刷新一次。

最少设置为过 5 分钟刷新一次

import formProvider from '@ohos.application.formProvider';
formProvider.setFormNextRefreshTime(formId,5,err => {
	Logger.error("setFormNextRefreshTime err : " + JSON.stringify(err))
})
1
2
3
4

​

卡片信息持久化

因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理。因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片 ID 进行持久化管理，以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据，且需要适配 onDestroy 卡片销毁通知接口，在其中实现卡片实例数据的删除。

卡片根据业务数据是否需要持久化分为以下两类：

• 常态卡片：卡片使用方会持久化的卡片；
• 临时卡片：卡片使用方不会持久化的卡片；
  卡片管理服务创建卡片时会调用卡片提供方的卡片生命周期函数 onCreate，在 onCreate 的入参 want 中会包含 ohos.extra.param.key.form_temporary 字段，该字段表明当前新建的卡片是临时卡片还是常态卡片，当前默认创建的是常态卡片。

临时卡片的数据具有非持久化的特殊性，某些场景比如卡片服务框架死亡重启，此时临时卡片数据在卡片管理服务中已经删除，且对应的卡片 ID 不会通知到提供方，所以卡片提供方需要自己负责清理长时间未删除的临时卡片数据。同时对应的卡片使用方可能会将之前请求的临时卡片转换为常态卡片。如果转换成功，卡片提供方也需要对对应的临时卡片 ID 进行处理，把卡片提供方记录的临时卡片数据转换为常态卡片数据，防止提供方在清理长时间未删除的临时卡片时，把已经转换为常态卡片的临时卡片信息删除，导致卡片信息丢失。

如果需要将临时卡片转化为常态卡片，可参考轻量级数据存储，将卡片示例的业务数据进行存储调用。

import dataStorage from '@ohos.data.storage';
const DATA_STORAGE_PATH = "/data/storage/el2/base/haps/form_store";
async function storeFormInfo(formId: string, formName: string, tempFlag: boolean) {
    let formInfo = {
        "formName": formName,
        "tempFlag": tempFlag,
        "updateCount": 0
    };
    try {
        const storage = await dataStorage.getStorage(DATA_STORAGE_PATH);
        // put form info
        await storage.put(formId, JSON.stringify(formInfo));
        Logger.log("storeFormInfo, put form info successfully, formId: " + formId);
        await storage.flush();
    } catch (err) {
        Logger.error("failed to storeFormInfo, err: " + JSON.stringify(err));
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

持久化存储后如图：

框架只是提供了临时卡片这种机制，具体的使用场景根据不同的使用方来确定，使用方根据自己的业务场景可以选择使用或者不使用临时卡片的机制。建议咨询对应使用方（比如桌面、服务中心等等）来确认使用临时卡片的场景。

接口说明

卡片提供方

Stage 模型中卡片提供方涉及如下四个接口：FormExtension、FormExtensionContext、FormProvider、FormBindingData。

FA 模型中卡片提供方涉及如下四个接口：LifecycleForm、FormExtensionContext、FormProvider、FormBindingData。

LifecycleForm （FA）

该接口提供了卡片生命周期函数。

在卡片提供方应用中的 FormAbility.ts 文件中继承 FormExtension 并实现这些卡片的生命周期函数。

FormExtension（Stage）

该接口提供了卡片生命周期函数。

在卡片提供方应用中的 FormAbility.ts 文件中继承 FormExtension 并实现这些卡片的生命周期函数。

FormExtension 类还拥有成员 context ，为 FormExtensionContext 类。

FormExtensionContext

卡片上下文环境类

FormProvider

卡片提供方，可以更新卡片信息、设置卡片下一次刷新时间。

FormBindingData

卡片绑定数据，与卡片页面的变量绑定。

卡片管理服务

卡片管理服务主要提供如下两个接口：@ohos.application.formHost.d.ts、@ohos.application.formInfo。

FormHost

在 API8 以前该接口是 @ohos.ability.formManager.d.ts

该接口提供了卡片使用方相关接口的能力，包括删除、释放、请求更新卡片，发送通知到指定卡片，获取卡片信息、状态等。

系统能力：SystemCapability.Ability.Form

权限：ohos.permission.REQUIRE_FORM、ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

FormInfo

卡片信息

系统能力：SystemCapability.Ability.Form

FormType

枚举，支持的卡片类型。

系统能力：SystemCapability.Ability.Form

SystemCapability.Ability.Form

ColorMode
枚举，卡片支持的颜色模式。

系统能力：SystemCapability.Ability.Form

SystemCapability.Ability.Form

FormStateInfo
卡片状态信息。

系统能力：SystemCapability.Ability.Form

SystemCapability.Ability.Form

FormState
枚举，卡片状态。

系统能力：SystemCapability.Ability.Form

SystemCapability.Ability.Form

FormParam
枚举，卡片参数。
系统能力：SystemCapability.Ability.Form
SystemCapability.Ability.Form

卡片使用方

卡片服务方主要负责卡片的展示，通过 FormComponent 组件来展示卡片信息。

FormComponent

interface FormComponentInterface {
    (value: {
        id: number; 		//卡片id
        name: string; 		//卡片名称
        bundle: string; 	//卡片提供方的bundle名
        ability: string; 	//卡片提供方的ability名
        module: string; 	//卡片提供方的module名
        dimension ? : FormDimension; 		//卡片支持的尺寸
        temporary ? : boolean; 				//当前卡片实例是否是临时卡片
    }): FormComponentAttribute;
}

declare class FormComponentAttribute extends CommonMethod < FormComponentAttribute > {
    //设置卡片的宽高大小
    size(value: { width: number;height: number }): FormComponentAttribute;

    //获取卡片的moduleName
    moduleName(value: string): FormComponentAttribute;

    //获取卡片的尺寸
    dimension(value: FormDimension): FormComponentAttribute;

    //卡片是否允许更新
    allowUpdate(value: boolean): FormComponentAttribute;

    //卡片是否可见
    visibility(value: Visibility): FormComponentAttribute;

    //当卡片的信息获取完善后，会触发此方法，返回卡片id
    onAcquired(callback: (info: { id: number }) => void): FormComponentAttribute;

    //加载卡片报错时调用
    onError(callback: (info: { errcode: number;msg: string }) => void): FormComponentAttribute;

    //卡片重定向时调用
    onRouter(callback: (info: any) => void): FormComponentAttribute;

    //卸载卡片时调用
    onUninstall(callback: (info: { id: number }) => void): FormComponentAttribute;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

​
代码示例：

FormComponent({
    id: formItem.cardId,
    name: formItem.cardName,
    bundle: formItem.bundleName,
    ability: formItem.abilityName,
    module: formItem.moduleName,
    dimension: dimensionItem,
})
.clip(new Rect({
    width: this.mFormComponentWidth[dimensionItem - 1],
    height: this.mFormComponentHeight[dimensionItem - 1],
    radius: 24
}))
.size({
    width: this.mFormComponentWidth[dimensionItem - 1],
    height: this.mFormComponentHeight[dimensionItem - 1]
})
.allowUpdate(this.allowUpdate)
.visibility(Visibility.Visible)
.onAcquired((form) => {
    Log.showInfo(TAG, `Form : ${JSON.stringify(form)}`);
    Log.showInfo(TAG, `FormComponent card id is: ${form.id}`);
    this.mFormIdList.push(form.id);
})
.onError((error) => {
    Log.showInfo(TAG, `FormComponent error msg: ${error.msg}`);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

为了能让大家更好的学习鸿蒙 (OpenHarmony) 开发技术，这边特意整理了《鸿蒙 (OpenHarmony)开发学习手册》，希望对大家有所帮助：

《鸿蒙（Harmony OS）开发学习手册》

入门必看：https://docs.qq.com/doc/DUk51cHZJaUpmSlhH
1.应用开发导读（ArKTS）
2.……

HarmonyOS概念：https://docs.qq.com/doc/DUk51cHZJaUpmSlhH
1.系统定义
2.技术框架
3.技术特性
4.系统安全

快速入门：https://docs.qq.com/doc/DUk51cHZJaUpmSlhH
1.基本概念
2.构建第一个ArkTS应用
3.……

开发基础知识：https://docs.qq.com/doc/DUk51cHZJaUpmSlhH
1.应用基础知识
2.配置文件
3.应用数据管理
4.应用安全管理
5.应用隐私保护
6.三方应用调用管控机制
7.资源分类与访问
8.学习ArkTS
9…

基于ArkTS 开发：https://docs.qq.com/doc/DUk51cHZJaUpmSlhH
1.Ability开发
2.UI开发
3.公共事件与通知
4.窗口管理
5.媒体
6.安全
7.网络与链接
8.电话服务
9.数据管理
10.后台任务(Background Task)管理
11.设备管理
12.设备使用信息统计
13.DFX
14.国际化开发
15.折叠屏系列
16………