# ArkTS锁屏卡片

从API version 18开始，Form Kit提供在设备锁屏界面上显示卡片的能力，用以展示重要信息或快捷操作，旨在让用户无需解锁即可获取关键资讯或执行常用功能。锁屏卡片常用于展示天气、时钟等内容，并支持用户个性化定制。

本文介绍了锁屏卡片的使用步骤、约束限制，并给出开发指导。

## 亮点/特征

* 应用信息浅层触达，不解锁即可查看，通过浅层信息持续获得用户关注，吸引用户复访。

* 应用快捷功能一键直达，提供更便捷的访问路径，提升操作效率。

## 使用步骤

锁屏卡片除了在锁屏界面显示卡片，还支持添加、删除、移动卡片，具体操作步骤如下。

1. 进入锁屏编辑态：在设备锁屏界面双手捏合手势进入锁屏编辑态，出现4个卡片添加位。 锁屏卡片只支持1*1、1*2尺寸的卡片，1*1尺寸卡片对应1个卡片添加位，1*2对应2个卡片添加位。

2. 进入锁屏卡片管理页面：点击卡片添加位会弹出锁屏卡片管理页面。

3. 添加卡片：在锁屏卡片管理页面选择任一卡片，例如运动健康和时钟，卡片就会添加到锁屏上。

4. 删除卡片：在锁屏编辑态，点击卡片右上角的减号即可删除卡片。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/35/v3/lBL5XjM3S6SF5tF6OtYuiA/zh-cn_image_0000002749332944.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=6570DEE04B968A0A5BDDFAB2404C1BAB486C23DD32B63A105B0FE9701D2EBE35)

## 约束和限制

* 设备限制：仅手机、平板设备支持使用。

* 界面限制：

1. 锁屏卡片只支持 1*1、1*2尺寸的卡片。

2. 锁屏卡片不推荐展示涉及用户的隐私敏感数据，具体界面约束请参考[卡片内容设计](https://developer.huawei.com/consumer/cn/doc/design-guides/system-features-service-widget-0000002087671904#section248mcpsimp)。

## 开发步骤

卡片创建完成后，需要完成锁屏卡片配置，并接入锁屏卡片开放能力，其他开发流程与普通卡片一致，具体步骤参考如下。

### 锁屏卡片配置

在form_config.json配置文件中，锁屏卡片必须配置renderingMode和supportDimensions字段。其中renderingMode字段仅支持配置为"singleColor"或者"autoColor"，supportDimensions字段取值中必须包含"1*1"或"1*2"，具体参考[配置文件字段说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-ui-widget-configuration#配置文件字段说明)。renderingMode字段在API version 18版本后，配置方法有变动。

```ts
// 在API version 18及以上的版本，renderingMode的配置方法如下
// entry/src/main/resources/base/profile/form_config.json
{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_display_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "isDynamic": true,
      "isDefault": true,
      "updateEnabled": false,
      "scheduledUpdateTime": "10:30",
      "renderingMode": "autoColor",
      "updateDuration": 1,
      "defaultDimension": "1*2",
      "supportDimensions": [
        "1*2",
        "2*2"
      ]
    }
  ]
}
```

```ts
// 在API version 18之前的版本，renderingMode的配置方法如下。value值"0"表示"autoColor"，value值"1"代表"fullColor"，value值"2"代表"singleColor"
// entry/src/main/resources/base/profile/form_config.json
{
  "forms": [
    {
      "name": "widget",
      "displayName": "$string:widget_display_name",
      "description": "$string:widget_desc",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "isDynamic": true,
      "isDefault": true,
      "updateEnabled": false,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "1*2",
      "supportDimensions": [
        "1*2",
        "2*2"
      ],
      "metadata": [
        {
          "name": "renderingMode",
          "value": "2"
        }
      ]
    }
  ]
}
```

### 锁屏卡片开放能力申请

因为锁屏卡片会展示在设备的锁屏界面，出于数据隐私安全考虑，需要开发者申请上架开放能力。

因此在应用调试或发布时，必须使用[手动签名](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing-manual)，并在手动签名[申请Profile](https://developer.huawei.com/consumer/cn/doc/app/agc-help-debug-profile-0000002248181278)过程中[创建HarmonyOS应用](https://developer.huawei.com/consumer/cn/doc/app/agc-help-create-app-0000002247955506)，创建应用时参考如下指导为应用接入开放能力。

1. 在"开放能力接入"页面，点击锁屏卡片对应的申请按钮。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1b/v3/2d8EVYWJTFGCbDoCKe_xbQ/zh-cn_image_0000002749492828.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=8B00D1F906A0A216703C51FBEAFBD167223D805F8677522851330AEA89569A3A)
2. 在"新建业务申请"窗口填写申请信息，然后点击"提交"。申请原因：必填，不超过256个字符。上传附件：选填，仅可上传1个附件，大小不超过500MB。支持文本、表格、图片、视频、压缩包格式。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/43/v3/zhO9rOlyQb2HPgVsnTI_WA/zh-cn_image_0000002779091887.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=F142316F26D6D09CD93954542AE34901BABC992FF83AAF461A66DF9EE78708B4)
3. 返回"开放能力接入"页面，原"申请"按钮变为"申请中"，1-3个工作日反馈申请结果。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/34/v3/UzgfGxvbQoSlmA79yjtPhA/zh-cn_image_0000002778932029.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=FC97CB2A19D55ED81E8768985668E9ACCB208773972399E8F72204BE6866437D)
4. 申请审批通过后，互动中心会发送通知给您，同时"申请中"按钮会变为置灰显示的"申请"。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d9/v3/5Tm5Hld3QEGRi6qJ2eCkbA/zh-cn_image_0000002749332946.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=4D1D2DAF457E417027C70BDCC06F4A618D4E028DC4376CA5EF126E1FF46A3E67)
5. 能力申请通过后，勾选锁屏卡片的能力开关，点击右上角"保存"。至此，您的应用已成功接入开放能力。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2/v3/hSqBYFgGT6itnXk5hKyqTQ/zh-cn_image_0000002749492830.png?HW-CC-KV=V1&HW-CC-Date=20260929T121655Z&HW-CC-Expire=31536000000&HW-CC-Sign=BEACFF89940478D0178287B9A3C95E49E95CC3F286FBCFBF486C5D3410EFEF52)