【ArkUI进阶练中学】第13课：元服务与卡片开发

本节目标

理解元服务的核心特征与适用场景，掌握元服务与传统应用的核心差异
掌握元服务工程的创建流程，能够正确配置BundleName与工程模板
掌握元服务的分包策略与体积约束，能够将功能模块合理拆分为HSP分包
掌握ArkTS卡片的开发流程，能够创建动态卡片并实现数据刷新与交互处理
掌握元服务与应用之间的代码复用设计模式，能够实现开发态与运行态的双向复用
掌握元服务卡片的多设备协同设计方法，能够实现卡片与元服务之间的数据共享
能够独立完成一个元服务的开发、调试与上架准备

一、元服务概述

1.1 什么是元服务

元服务是HarmonyOS提供的一种轻量应用程序形态，具备免安装、即用即走、账号相随等特征。元服务可独立上架、分发、运行，独立实现业务闭环，可大幅提升信息与服务的获取效率。

从应用程序入口看，传统应用和元服务均可选择服务卡片作为入口。用户点击卡片或图标后，无需显式安装即可使用元服务。元服务包含页面、卡片、图标三个部分，分别对应UI开发、服务卡片开发和图标生成。

1.2 元服务与传统应用的核心差异

安装方式：传统应用需要手动下载安装，元服务免安装，即用即走。

包大小限制：传统应用包大小无限制，元服务单个包文件不能超过2MB，所有包文件总和不能超过10MB。

API范围：传统应用可使用全量API，元服务只能使用"元服务API集"。

分发入口：传统应用通过应用市场分发，元服务通过负一屏、服务中心等系统分发入口触达用户。

能力载体：元服务跟随华为账号，用户在不同设备上使用同一账号即可访问相同的元服务数据。

1.3 元服务的适用场景

元服务适合轻量化、高频、即时的服务场景，如快递跟踪、天气查询、打车、外卖点单、日程提醒等。不适合功能复杂、需要大量本地计算或存储的重度应用。

二、元服务工程创建

2.1 前置准备

创建元服务工程前，需要先完成以下准备：注册华为开发者账号并在AppGallery Connect创建元服务应用；获取APP ID；搭建开发环境（DevEco Studio）。

2.2 创建工程

在DevEco Studio中，选择Atomic Service（元服务） 开发，选择模板后点击Next进行配置。当前元服务支持的模板类型包括：Empty Ability（用于Phone、Tablet设备的基础模板）、CloudDev Empty Ability（端云一体化开发模板）、Embeddable Ability（用于开发支持被其他应用嵌入式运行的元服务）。

注意：元服务不支持Native开发方式，无法选择Native工程模板开发元服务。

2.3 BundleName命名规范

元服务的BundleName采用固定前缀和APP ID组合 的方式命名，格式为com.atomicservice.[APP ID]。BundleName为自动生成，开发者无法手动修改，不符合命名规范的包名无法在APP ID下拉列表中展示。

2.4 工程目录结构

元服务工程的目录结构与标准应用工程基本一致，核心目录包括：

AppScope > app.json5：元服务的全局配置信息。

entry ：HarmonyOS工程模块，编译构建生成一个HAP。包含src/main/ets（ArkTS源码）、entryability（元服务入口）、pages（元服务页面）、resources（资源文件）、module.json5（模块配置文件）、build-profile.json5（模块级编译配置）、hvigorfile.ts（模块级构建脚本）。

三、元服务分包策略

3.1 分包的必要性

元服务为了实现快速启动效果，对HAP和HSP文件大小做了限制，同时优化了元服务启动机制。元服务的这种多模块开发方式称为"分包"。通过分包页面路由跳转时，系统将动态加载分包，加载完成后启动对应页面。这样，启动元服务时只需下载和安装首包，即可立即启动元服务，大大缩短元服务启动时间。

3.2 分包规则与约束

首包：将EntryHAP作为首包，包含元服务首次启动时会打开的页面（即首页）代码和资源。

分包：将其他包含功能页的模块以及HSP动态共享模块作为分包，包含功能页和元服务页的代码和资源。

体积约束：单个包文件（加上其依赖的所有共享包）大小不能超过2MB，超过限制DevEco Studio会打包失败。同一个元服务下所有包文件（加上其依赖的所有共享包）的大小总和不能超过10MB，超过限制会上架应用市场失败。如因业务需要，可向平台申请总包大小放宽至20MB。

模块类型约束 ：元服务仅支持单个Ability ，分包模块类型需要使用shared（HSP）。元服务不支持feature类型模块。

3.3 分包配置

首包entry模块的module.json5配置：

json5 复制代码

{
  "module": {
    "name": "entry",
    "type": "entry",
    "pages": "$profile:main_pages",
    // ...
  }
}

分包library模块的module.json5配置：

json5 复制代码

{
  "module": {
    "name": "library",
    "type": "shared",
    // ...
  }
}

3.4 分包加载与路由跳转

当跳转的目标NavDestination在不同的HSP分包，且未被主包依赖时，首次运行元服务只会下载安装主包。需要使用NavPushPathHelper先下载安装相应HSP分包，再将指定的NavDestination页面信息入栈，使Navigation支持动态加载HSP分包后再跳转。

3.5 分包瘦身实践

将非首屏Tab的业务模块拆到HSP，并从entry模块的oh-package.json5的dependencies中移除对HSP的静态依赖，使HSP体积不计入首包2MB限制。

四、ArkTS卡片开发

4.1 卡片类型

ArkTS卡片分为动态卡片 和静态卡片 两种。在form_config.json配置文件中，通过isDynamic参数控制：置空或赋值为"true"则为动态卡片，赋值为"false"则为静态卡片。静态卡片和动态卡片切换之后用户交互实现也需要修改。

4.2 创建卡片

在DevEco Studio中，选中entry目录单击右键，选择New → Service Widget → Dynamic Widget （或Static Widget），在选择开发语言类型时选择ArkTS选项，选择期望的卡片尺寸后点击Finish即可完成卡片创建。

创建完成后，工程中会新增以下卡片相关文件：

EntryFormAbility.ets：卡片生命周期管理文件，提供卡片创建、销毁、刷新等生命周期回调。

WidgetCard.ets：卡片页面文件，定义卡片的UI布局。

form_config.json：卡片配置文件，定义卡片的外观规格、刷新策略等。

4.3 卡片数据刷新

卡片数据刷新有两种方式：

被动刷新（定时刷新） ：在onUpdateForm生命周期中获取最新数据并推送。结合定时刷新（updateDuration配置）和主动推送使用。正确做法是将更新逻辑迁移到FormExtensionAbility.onUpdateForm中，在onUpdateForm中获取最新数据，然后调用formProvider.updateForm(formId, formInfo)推送数据。

主动刷新 ：卡片提供方应用运行过程中，如果识别到有要更新卡片数据的诉求，可以主动通过formProvider提供的updateForm接口更新卡片。

从API 20开始，如果卡片刷新的数据通过共享内存更新，刷新数据总大小不超过10MB，刷新图片数量不超过20张。

4.4 卡片数据共享

当卡片需要从元服务获取信息，或元服务需要响应卡片的操作时，可以采用共享存储数据的方式实现。例如，在打车场景中，用户可以在卡片上执行拨打电话的操作，此时卡片侧显示的司机手机号就是从元服务中获取的数据。

五、应用与元服务协同设计

5.1 开发态可复用设计

在开发阶段将元服务的代码复用到应用，在应用内快速实现和元服务相同的功能。应用和元服务分别打包上架，在运行态用户可以通过元服务体验功能，也可以通过应用来体验相同的功能。应用和元服务包体都包含了这一部分的功能代码，通过自身的功能入口分别对用户提供相同的服务。

注意：应用和元服务之间共享的模块代码只能使用元服务API集。

5.2 运行态可复用设计

在开发阶段，应用不需要实现和元服务相同的功能，也不需要将元服务的功能代码复用到应用中。只需要在应用的界面中增加运行元服务的功能入口，通过系统提供的嵌入式运行元服务的能力，将元服务的功能页面嵌入到应用中完成对元服务的功能复用。

5.3 多团队协作建议

应用和元服务由不同的团队开发时，建议应用和元服务通过不同的工程开发，并实现代码复用。比较稳妥的结构是：App和元服务作为两个独立壳，共享一个common HAR（源码HAR或产物HAR）。

5.4 多设备协同与状态共享

元服务通过分布式能力 + 原子化服务模型 ，让服务可以在多设备间自然流转。分布式层负责数据传输与设备间调用，通过分布式数据接口distributed.put()，可以在多个设备上共享同一份数据状态。

卡片支持个性化定制，可固定在桌面任意位置，并能在手机、平板、手表等设备间便捷分享。卡片能在手机、手表、平板等设备间分享流转，一点即开，无需下载，这依托于HarmonyOS的分布式技术。

5.5 组合卡片

组合卡片指多个卡片协同工作，实现主控+信息面板联动的效果。组合卡片的联动逻辑涉及中转页面和异步状态同步，卡片尺寸适配需要同时考虑多种布局，同时需要关注安全与隐私合规（权限配置和隐私政策撰写）。

六、多元化习题

习题 1（判断题）

题目：元服务的BundleName可以由开发者手动指定，与普通应用没有区别。

答案：错误

解读：元服务的BundleName采用固定前缀和APP ID组合的方式命名，格式为com.atomicservice.[APP ID]，BundleName为自动生成，开发者无法手动修改，不符合命名规范的包名无法在APP ID下拉列表中展示。

习题 2（单选题）

题目：以下关于元服务分包的说法，正确的是（）

A. 元服务支持feature类型模块作为分包

B. 元服务单个包文件大小不能超过5MB

C. 元服务分包模块类型需要使用shared（HSP）

D. 元服务所有包文件总和不能超过20MB

答案：C

解读：元服务仅支持单个Ability，分包模块类型需要使用shared（HSP），元服务不支持feature类型模块。单个包文件（加上其依赖的所有共享包）大小不能超过2MB，所有包文件总和不能超过10MB（如因业务需要可申请放宽至20MB）。

习题 3（多选题）

题目：关于应用与元服务的代码复用，以下说法正确的有（多选）：

A. 开发态可复用设计是在开发阶段将元服务的代码复用到应用

B. 运行态可复用设计需要将元服务的功能代码复用到应用中

C. 应用和元服务之间共享的模块代码只能使用元服务API集

D. 运行态可复用设计通过系统提供的嵌入式运行元服务的能力实现复用

答案：A、C、D

解读：开发态可复用设计是在开发阶段将元服务的代码复用到应用，选项A正确。运行态可复用设计不需要将元服务的功能代码复用到应用中，只需要在应用的界面中增加运行元服务的功能入口，选项B错误。应用和元服务之间共享的模块代码只能使用元服务API集，选项C正确。运行态可复用设计通过系统提供的嵌入式运行元服务的能力，将元服务的功能页面嵌入到应用中完成功能复用，选项D正确。

习题 4（代码填空题）

题目：请补全以下form_config.json配置，将卡片设置为动态卡片。

json 复制代码

{
  "forms": [
    {
      "name": "widget",
      "description": "示例卡片",
      "src": "./ets/widget/pages/WidgetCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "______________": "true",
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1
    }
  ]
}

答案：isDynamic

解读：isDynamic参数控制卡片类型，置空或赋值为"true"则为动态卡片，赋值为"false"则为静态卡片。

习题 5（代码改错题）

题目：以下卡片更新代码存在刷新不生效的问题，请指出问题并修正。

typescript 复制代码

// 在元服务页面中直接调用 updateForm
import { formProvider } from '@kit.FormKit';

function refreshCard(formId: string, data: object): void {
  const formInfo: formProvider.FormInfo = {
    formId: formId,
    data: data
  };
  formProvider.updateForm(formId, formInfo);
}

答案：卡片更新逻辑应该迁移到FormExtensionAbility.onUpdateForm中，结合定时刷新（被动刷新）和主动推送使用。正确做法是在onUpdateForm中获取最新数据，然后调用formProvider.updateForm(formId, formInfo)推送数据。

typescript 复制代码

// EntryFormAbility.ets
export default class EntryFormAbility extends FormExtensionAbility {
  onUpdateForm(formId: string): void {
    // 获取最新数据
    const latestData = this.getLatestData();
    const formInfo: formProvider.FormInfo = {
      formId: formId,
      data: latestData
    };
    formProvider.updateForm(formId, formInfo);
  }
}

习题 6（简答题）

题目：简述元服务的分包策略，以及分包如何帮助元服务实现快速启动。

答案：元服务的分包策略为：将EntryHAP作为首包，包含元服务首次启动时会打开的页面（即首页）代码和资源。将其他包含功能页的模块以及HSP动态共享模块作为分包，包含功能页和元服务页的代码和资源。分包帮助元服务实现快速启动的原理是：启动元服务时，只需下载和安装首包，即可立即启动元服务，大大缩短元服务启动时间。当用户需要访问分包页面时，系统动态加载分包，加载完成后启动对应页面。同时，元服务对包大小有严格限制：单个包文件不能超过2MB，所有包文件总和不能超过10MB，这进一步保证了元服务的轻量化特性。

习题 7（简答题）

题目：简述应用与元服务之间的两种代码复用设计模式，以及各自的适用场景。

答案：两种代码复用设计模式包括：开发态可复用设计，在开发阶段将元服务的代码复用到应用，在应用内快速实现和元服务相同的功能。应用和元服务分别打包上架，运行态用户可以通过元服务体验功能，也可以通过应用来体验相同的功能。适用于需要在应用和元服务中实现相同功能的场景。运行态可复用设计，在开发阶段应用不需要实现和元服务相同的功能，只需要在应用的界面中增加运行元服务的功能入口，通过系统提供的嵌入式运行元服务的能力，将元服务的功能页面嵌入到应用中完成对元服务的功能复用。适用于应用只需要集成元服务能力、不需要重复实现相同功能的场景。

七、本节知识点总结

元服务核心特征

元服务是HarmonyOS的轻量应用程序形态，具备免安装、即用即走、账号相随等特征。包含页面、卡片、图标三个部分，仅能使用元服务API集。BundleName采用固定前缀和APP ID组合方式命名。

分包策略与体积约束

EntryHAP作为首包，其他模块作为分包。单个包文件不能超过2MB，所有包文件总和不能超过10MB（可申请放宽至20MB）。分包模块类型必须使用shared（HSP），不支持feature类型模块。

ArkTS卡片开发

卡片分为动态卡片和静态卡片，通过isDynamic参数控制。卡片相关文件包括EntryFormAbility.ets、WidgetCard.ets和form_config.json。卡片数据刷新通过formProvider.updateForm接口实现。

卡片与元服务数据共享

当卡片需要从元服务获取信息或响应操作时，采用共享存储数据的方式实现。打车场景中卡片显示的司机手机号就是从元服务中获取的数据。

应用与元服务协同设计

开发态可复用设计将元服务代码复用到应用，运行态可复用设计通过嵌入式运行元服务的方式实现功能复用。多团队协作时建议App和元服务作为两个独立壳，共享common HAR。

多设备协同

元服务通过分布式能力实现多设备间自然流转，卡片可在手机、平板、手表等设备间分享流转。组合卡片实现多卡片协同，主控+信息面板联动。

下节预告

第14课将进入ArkUI的AI能力深度集成的学习，涵盖端侧大模型部署、意图框架与智能体开发、以及AI驱动的动态UI生成。