HarmonyOS开发：元服务概述——鸿蒙服务卡片生态

📌 核心要点：元服务是鸿蒙生态的"轻量化服务载体"，通过服务卡片实现免安装、即用即走的体验，FormAbility是它的核心驱动引擎。

背景与动机

你有没有想过一个问题：用户想查个天气，非得先去应用市场搜App、下载、安装、注册、登录，然后才能看到温度？这一套流程走下来，黄花菜都凉了。

鸿蒙的设计理念就是冲着这个痛点来的——服务找人，而不是人找服务。

元服务（Ability Form）就是这么个东西。它把服务的核心功能浓缩成一张"卡片"，直接钉在桌面上、服务中心里，用户长按桌面空白处就能添加，不用装App，不用打开App，信息一目了然。天气卡片直接显示温度，日程卡片直接显示今天的会议，外卖卡片直接显示配送进度。

这玩意儿为什么重要？

第一，入口变了。传统App靠图标点进去，元服务靠卡片直接展示。用户不需要"进入"你的应用，你的服务已经在他眼前了。

第二，门槛低了。免安装意味着转化率飙升。你做一个小工具，用户试一下的成本几乎为零。

第三，生态卡位。鸿蒙的服务中心、智慧推荐这些入口，优先推荐的就是元服务。不做元服务，你就少了半个鸿蒙生态的曝光。

那FormAbility又是什么？简单说，它是元服务的"心脏"——所有卡片的创建、更新、销毁，都由FormAbility驱动。你写一个FormAbility，就能管理一整套服务卡片。

核心原理

元服务 vs 传统App

先搞清楚元服务和传统App到底有什么区别，不然后面写代码都是懵的。

看到没？元服务是"寄生"在宿主进程里的。卡片本身不跑独立进程，它的UI渲染由系统负责，数据由FormAbility提供。这个架构设计决定了卡片的性能开销极低，但也意味着你不能在卡片里做太重的事情。

FormAbility生命周期

FormAbility的生命周期比UIAbility简单得多，一共就几个关键回调：

flowchart TD
    A[系统请求创建卡片] --> B[onAddForm]
    B --> C[返回FormBindingData]
    C --> D[卡片渲染显示]
    D --> E{用户操作}
    E -->|更新数据| F[onUpdateForm]
    F --> G[返回新的FormBindingData]
    G --> D
    E -->|删除卡片| H[onRemoveForm]
    H --> I[清理资源]
    E -->|点击卡片| J[router/message事件]
    J --> K[跳转UIAbility或处理消息]
    
    classDef startEnd fill:#4CAF50,stroke:#2E7D32,color:#fff
    classDef process fill:#2196F3,stroke:#1565C0,color:#fff
    classDef decision fill:#FF9800,stroke:#E65100,color:#fff
    classDef event fill:#9C27B0,stroke:#6A1B9A,color:#fff
    
    class A,I startEnd
    class B,C,D,F,G,K process
    class E decision
    class H,J event

核心回调就三个：

• onAddForm：用户添加卡片时触发，你必须返回初始数据
• onUpdateForm：卡片需要更新时触发，返回新数据
• onRemoveForm：用户删除卡片时触发，做清理工作

还有一个onFormEvent，处理卡片发送的message事件，后面讲交互的时候会细说。

服务卡片生态架构

一张卡片从"代码"变成"用户桌面上的东西"，中间经历了什么？

flowchart LR
    subgraph 开发者侧
        A[FormAbility代码] --> B[卡片布局文件]
        B --> C[form_config.json配置]
    end
    
    subgraph 系统侧
        D[FormManagerService] --> E[卡片渲染引擎]
        E --> F[桌面/服务中心]
    end
    
    subgraph 用户侧
        F --> G[添加卡片]
        G --> H[查看/交互]
    end
    
    C --> D
    A --> D
    
    classDef dev fill:#E3F2FD,stroke:#1565C0,color:#0D47A1
    classDef sys fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef user fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    
    class A,B,C dev
    class D,E,F sys
    class G,H user

关键点：卡片UI的渲染不是你的FormAbility做的，是系统的卡片渲染引擎负责。FormAbility只负责"喂数据"。这种分离架构的好处是——即使你的FormAbility挂了，卡片照样显示最后的数据，不会白屏。

静态卡片 vs 动态卡片

这是新手最容易混淆的概念。

静态卡片：布局和数据在编译时就确定了，运行时通过FormBindingData更新数据。卡片UI用ArkTS写，但渲染由系统完成。更新频率受系统管控，最低1小时一次。

动态卡片：卡片UI由你的UIAbility进程渲染，实时性更强，支持更复杂的交互。本质上是一个"迷你Activity"，但运行在卡片沙箱里。

选哪个？90%的场景用静态卡片就够了。只有当你需要实时刷新（比如股票行情、运动轨迹）或者复杂交互（比如音乐播放控制）时，才考虑动态卡片。

代码实战

基础用法：创建第一个FormAbility

先来个最简单的FormAbility，感受一下基本结构：

// FormAbility.ets
import { formBindingData, FormExtensionAbility, formInfo, formProvider } from '@kit.AbilityKit'
import { hilog } from '@kit.PerformanceAnalysisKit'

// 卡片信息存储，key是卡片ID
const formInfoMap: Map<string, formInfo.FormInfo> = new Map()

export default class FormAbility extends FormExtensionAbility {
  
  // 用户添加卡片时触发
  onAddForm(want: Want): formBindingData.FormBindingData {
    hilog.info(0x0000, 'FormAbility', 'onAddForm called')
    
    // 卡片ID
    const formId = want.parameters?.['ohos.extra.param.key.form_identity'] as string
    
    // 存储卡片信息
    formInfoMap.set(formId, {
      formId: formId,
      formName: 'widget',
      bundleName: 'com.example.mywidget',
      abilityName: 'FormAbility'
    })
    
    // 返回初始数据——这是卡片显示的内容
    const formData = {
      title: '我的第一张卡片',
      content: 'Hello HarmonyOS!',
      updateTime: this.formatTime(new Date())
    }
    
    return formBindingData.createFormBindingData(formData)
  }
  
  // 系统请求更新卡片时触发
  onUpdateForm(formId: string): formBindingData.FormBindingData {
    hilog.info(0x0000, 'FormAbility', `onUpdateForm: ${formId}`)
    
    // 返回更新后的数据
    const formData = {
      title: '我的第一张卡片',
      content: '数据已更新',
      updateTime: this.formatTime(new Date())
    }
    
    return formBindingData.createFormBindingData(formData)
  }
  
  // 用户删除卡片时触发
  onRemoveForm(formId: string): void {
    hilog.info(0x0000, 'FormAbility', `onRemoveForm: ${formId}`)
    // 清理该卡片相关的资源
    formInfoMap.delete(formId)
  }
  
  // 格式化时间
  private formatTime(date: Date): string {
    const hours = date.getHours().toString().padStart(2, '0')
    const minutes = date.getMinutes().toString().padStart(2, '0')
    return `${hours}:${minutes}`
  }
}

看到没？核心逻辑就三步：创建时返回数据、更新时返回新数据、删除时清理资源。FormBindingData就是卡片的"数据包"，你塞什么数据进去，卡片就显示什么。

进阶用法：多卡片管理与配置

实际项目中，你的元服务可能提供多种卡片。比如天气应用，有"当前天气"卡片和"未来三天"卡片。怎么区分？靠form_config.json配置。

先看配置文件：

// src/main/resources/base/profile/form_config.json
{
  "forms": [
    {
      "name": "currentWeather",
      "displayName": "当前天气",
      "description": "显示当前城市天气信息",
      "src": "./ets/widget/pages/CurrentWeatherCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 1,
      "defaultDimension": "2*2",
      "supportDimensions": ["2*2", "4*4"]
    },
    {
      "name": "forecastWeather",
      "displayName": "三天预报",
      "description": "显示未来三天天气趋势",
      "src": "./ets/widget/pages/ForecastCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "colorMode": "auto",
      "isDefault": false,
      "updateEnabled": true,
      "scheduledUpdateTime": "07:00",
      "updateDuration": 0,
      "defaultDimension": "4*4",
      "supportDimensions": ["4*4"]
    }
  ]
}

然后在FormAbility里根据卡片名称返回不同数据：

// 多卡片FormAbility
export default class WeatherFormAbility extends FormExtensionAbility {
  
  onAddForm(want: Want): formBindingData.FormBindingData {
    const formId = want.parameters?.['ohos.extra.param.key.form_identity'] as string
    const formName = want.parameters?.['ohos.extra.param.key.form_name'] as string
    
    hilog.info(0x0000, 'WeatherForm', `添加卡片: ${formName}, ID: ${formId}`)
    
    // 根据卡片名称返回不同数据
    switch (formName) {
      case 'currentWeather':
        return this.getCurrentWeatherData(formId)
      case 'forecastWeather':
        return this.getForecastData(formId)
      default:
        return formBindingData.createFormBindingData({ error: '未知卡片类型' })
    }
  }
  
  // 当前天气卡片数据
  private getCurrentWeatherData(formId: string): formBindingData.FormBindingData {
    const weatherData = this.fetchWeatherFromCache('北京')
    return formBindingData.createFormBindingData({
      city: weatherData.city,
      temperature: weatherData.temperature,
      weather: weatherData.weather,
      icon: weatherData.icon,
      updateTime: this.formatTime(new Date())
    })
  }
  
  // 三天预报卡片数据
  private getForecastData(formId: string): formBindingData.FormBindingData {
    const forecastList = this.fetchForecastFromCache('北京')
    return formBindingData.createFormBindingData({
      city: '北京',
      days: forecastList.map((day, index) => ({
        date: day.date,
        weather: day.weather,
        high: day.high,
        low: day.low
      }))
    })
  }
  
  onUpdateForm(formId: string): formBindingData.FormBindingData {
    // 根据存储的卡片信息判断类型，返回对应更新数据
    const info = this.getFormInfo(formId)
    if (info) {
      return this.onAddForm(info.want)
    }
    return formBindingData.createFormBindingData({})
  }
  
  onRemoveForm(formId: string): void {
    this.removeFormInfo(formId)
    hilog.info(0x0000, 'WeatherForm', `卡片已删除: ${formId}`)
  }
  
  // 从缓存获取天气数据（避免频繁网络请求）
  private fetchWeatherFromCache(city: string): WeatherInfo {
    // 实际项目中从本地数据库或内存缓存读取
    return {
      city: city,
      temperature: '26°C',
      weather: '晴',
      icon: 'sunny',
      updateTime: new Date().toISOString()
    }
  }
  
  private fetchForecastFromCache(city: string): ForecastDay[] {
    return [
      { date: '今天', weather: '晴', high: '28°', low: '18°' },
      { date: '明天', weather: '多云', high: '25°', low: '16°' },
      { date: '后天', weather: '小雨', high: '22°', low: '14°' }
    ]
  }
  
  private formatTime(date: Date): string {
    return `${date.getHours().toString().padStart(2, '0')}:${date.getMinutes().toString().padStart(2, '0')}`
  }
}

关键点：formName是从form_config.json里配置的name字段来的，系统添加卡片时会把卡片名称通过Want传给你。你根据这个名称决定返回什么数据。

完整示例：带Module配置的元服务项目

光有FormAbility还不够，你还得在module.json5里声明它，不然系统根本不知道你提供了卡片服务。

// module.json5 关键配置
{
  "module": {
    "name": "entry",
    "type": "entry",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background"
      }
    ],
    "extensionAbilities": [
      {
        "name": "FormAbility",
        "srcEntry": "./ets/formability/FormAbility.ets",
        "description": "$string:FormAbility_desc",
        "icon": "$media:icon",
        "label": "$string:FormAbility_label",
        "type": "form",
        "metadata": [
          {
            "name": "ohos.extension.form",
            "resource": "$profile:form_config"
          }
        ]
      }
    ],
    "installationFree": true  // 关键！声明免安装
  }
}

注意 installationFree: true 这行——这是元服务的标志。没有它，你的应用就不是免安装的元服务，而是普通App。

完整的卡片页面文件：

// ./ets/widget/pages/CurrentWeatherCard.ets
@Entry
@Component
struct CurrentWeatherCard {
  // 卡片数据，由FormBindingData注入
  @State city: string = ''
  @State temperature: string = ''
  @State weather: string = ''
  @State icon: string = ''
  @State updateTime: string = ''

  build() {
    Column() {
      // 城市名
      Text(this.city)
        .fontSize(16)
        .fontColor('#333333')
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 8 })
      
      // 温度
      Row() {
        Text(this.temperature)
          .fontSize(36)
          .fontColor('#FF6B35')
          .fontWeight(FontWeight.Bold)
        
        Text(this.weather)
          .fontSize(14)
          .fontColor('#666666')
          .margin({ left: 12, top: 16 })
      }
      .alignItems(VerticalAlign.Top)
      
      // 更新时间
      Text(`更新于 ${this.updateTime}`)
        .fontSize(10)
        .fontColor('#999999')
        .margin({ top: 8 })
    }
    .width('100%')
    .height('100%')
    .padding(12)
    .backgroundColor('#FFFFFF')
    .borderRadius(16)
  }
}

卡片页面的写法和普通ArkTS页面几乎一样，但有几个限制：不能用@Link、不能有自定义组件嵌套过深、不支持所有手势。这些限制后面踩坑部分细说。

踩坑与注意事项

坑1：卡片数据大小限制

FormBindingData不是你想塞多少就塞多少的。系统对卡片数据有大小限制，静态卡片的数据不能超过1KB，动态卡片不能超过4KB。

你可能会说：1KB？开什么玩笑？我一张卡片的JSON数据都不止1KB了。

这就是为什么你要精心设计数据结构。别把整个对象图都塞进去，只传卡片需要显示的字段：

// ❌ 错误：数据量太大
const badData = {
  user: {
    id: 12345,
    name: '张三',
    avatar: 'https://very-long-url.com/avatar.png',
    email: 'zhangsan@example.com',
    // ... 还有一堆字段
  },
  orders: [
    { id: 1, items: [...], total: 99.9 },
    { id: 2, items: [...], total: 199.9 }
  ]
}

// ✅ 正确：只传卡片需要的数据
const goodData = {
  userName: '张三',
  pendingOrders: 2,
  totalAmount: '¥299.8'
}

坑2：卡片更新不是你想更新就能更新

静态卡片的更新频率由系统管控。你在form_config.json里配了scheduledUpdateTime: "10:30"，意思是"最早10:30可以更新"，不是"10:30一定会更新"。系统会根据电量、网络、用户使用习惯等因素决定是否真的触发更新。

如果你想主动推送更新呢？可以用formProvider.updateForm()：

import { formProvider, formBindingData } from '@kit.AbilityKit'

// 在UIAbility中主动更新卡片
function updateCardData(formId: string): void {
  const newData = {
    title: '新消息',
    content: '你有3条未读消息',
    updateTime: new Date().toLocaleTimeString()
  }
  
  const bindingData = formBindingData.createFormBindingData(newData)
  formProvider.updateForm(formId, bindingData)
    .then(() => {
      hilog.info(0x0000, 'CardUpdate', '卡片更新成功')
    })
    .catch((err: Error) => {
      hilog.error(0x0000, 'CardUpdate', `卡片更新失败: ${err.message}`)
    })
}

但注意，频繁调用updateForm会被系统限流。官方建议更新间隔不低于5分钟。

坑3：FormAbility运行在独立上下文

FormAbility的context和UIAbility的context是隔离的。你不能在FormAbility里直接访问UIAbility的Preferences、数据库等数据。

怎么办？两种方案：

1. 通过DataShare共享数据：UIAbility写数据到DataShare，FormAbility读
2. 通过分布式数据同步：使用AppStorage或PersistentStorage

// 在UIAbility中存储数据
import { preferences } from '@kit.ArkData'

export default class EntryAbility extends UIAbility {
  async onCreate(want, launchParam) {
    // 存储数据到Preferences
    const prefs = await preferences.getPreferences(this.context, 'weather_data')
    await prefs.put('current_temp', '26°C')
    await prefs.flush()
  }
}

// 在FormAbility中读取——直接用Preferences？不行！
// FormAbility的context和UIAbility不同，Preferences实例不共享
// 正确做法：使用分布式键值存储或DataShare

坑4：卡片不支持所有ArkTS组件

静态卡片只支持有限的组件列表：Text、Image、Column、Row、Flex、List、ListItem、Grid、GridItem、Stack、Progress。像Canvas、Web、Video这些组件，卡片里一律不能用。

动态卡片支持范围更广，但也不是全部。写卡片UI之前，先查一下官方文档的"卡片支持的组件"列表，别写完了才发现不支持。

HarmonyOS 6适配说明

HarmonyOS 6对元服务做了几项重要更新，如果你是从5.0迁移过来的，注意以下几点：

1. 卡片沙箱增强：6.0对卡片的沙箱隔离更加严格，FormAbility访问文件系统的路径有变化。之前能通过context.filesDir访问的路径，6.0可能需要用context.cacheDir替代。

2. 动态卡片渲染架构升级：6.0的动态卡片渲染引擎从"独立渲染"改为"共享渲染"，内存占用降低约30%。但这也意味着你的动态卡片代码需要适配新的渲染模式，特别是使用了自定义绘制的情况。

3. form_config.json新增字段：6.0新增了isDynamic字段，显式声明卡片类型。5.0是通过uiSyntax字段隐式判断的，6.0建议显式声明：

{
  "forms": [{
    "name": "myCard",
    "isDynamic": false,  // 6.0新增，显式声明静态卡片
    "src": "./ets/widget/pages/MyCard.ets",
    "uiSyntax": "arkts"
  }]
}

4. 更新频率策略调整：6.0对静态卡片的更新频率管控更灵活，支持"智能更新"模式。系统会根据用户查看卡片的频率动态调整更新间隔——用户经常看的卡片更新更频繁，不常看的更新更少。你不需要改代码，但需要理解这个行为变化。

5. 服务中心接入新规范：6.0的服务中心对元服务的质量审核更严格，卡片必须支持至少2种尺寸，且4x4尺寸下不能出现大面积空白。

总结

元服务不是什么花架子，它是鸿蒙生态的核心入口形态。理解它，你才能理解鸿蒙"服务找人"的设计哲学。

回顾一下核心要点：

• 元服务通过服务卡片提供免安装、即用即走的体验
• FormAbility是元服务的核心，管理卡片的创建、更新、销毁
• 静态卡片适合信息展示，动态卡片适合实时交互
• 卡片数据有大小限制，更新频率受系统管控
• FormAbility和UIAbility的上下文是隔离的，数据共享需要特殊处理

下一篇，我们开始动手写静态卡片，从BasicCard的实现细节聊起。