鸿蒙原子化服务开发实战：构建免安装的轻量应用

一、章节概述

✅ 学习目标

掌握鸿蒙原子化服务的核心概念与特性
熟练完成原子化服务的配置与开发流程
实现不同尺寸的服务卡片与交互逻辑
掌握原子化服务的测试、调试与发布
构建符合鸿蒙生态的免安装轻量应用

💡 重点内容

原子化服务核心特性、DevEco 服务卡片配置、ArkTS 卡片开发、服务生命周期管理

⚠️ 前置基础

已掌握鸿蒙 ArkTS 开发、应用签名、页面交互、分布式能力等核心技术

二、原子化服务核心概念🔧

2.1 什么是原子化服务？

鸿蒙原子化服务是一种免安装、跨设备、服务直达的新型应用形态，无需用户下载安装即可使用核心功能，是鸿蒙生态的核心竞争力之一。

2.2 与传统应用的区别

维度	传统应用	原子化服务
📦 安装方式	需要下载安装到设备	免安装，即点即用
🔌 运行形态	独立应用进程	以卡片/服务形式嵌入系统环境
📱 跨设备能力	需手动安装到各设备	自动适配多设备，无需重复安装
⏱️ 启动速度	冷启动/热启动（>1秒）	毫秒级启动

2.3 核心特性与应用场景

核心特性	应用场景
✅ 服务直达	天气查询、快捷支付、日程提醒
🖼️ 多尺寸卡片	桌面小卡片、智慧屏大卡片
🔄 实时数据同步	股票行情、物流跟踪
🔗 跨设备流转	手机→平板→智慧屏服务迁移

三、原子化服务开发实战⌨️

3.1 功能需求

开发一个「快捷待办」原子化服务，包含：

小/中/大三种尺寸的桌面卡片
点击卡片直接添加/完成待办
实时同步待办状态
支持跨设备流转

3.2 环境准备

DevEco Studio：3.1.0.501+
SDK版本：API 9+
设备支持：鸿蒙系统3.0+的手机/平板/智慧屏

3.3 配置原子化服务

3.3.1 修改config.json

在entry/config.json中配置原子化服务相关参数：

json 复制代码

"module": {
  "name": "entry",
  "type": "feature",
  "srcPath": "./src/main/ets",
  "description": "快捷待办原子化服务",
  "mainAbility": "MainAbility",
  "deviceTypes": ["phone", "tablet", "tv"],
  "deliveryWithInstall": false,  // 关闭随应用安装
  "installFree": true,           // 开启免安装
  "abilities": [
    {
      "name": "MainAbility",
      "type": "service",         // 服务类型
      "visible": true,
      "skills": [
        {
          "entities": ["entity.system.home"],
          "actions": ["action.system.home"]
        }
      ],
      "extensionAbilities": [    // 配置卡片扩展
        {
          "name": "TodoCardExtensionAbility",
          "type": "card",
          "visible": true,
          "metaData": {
            "customizeData": [
              {
                "name": "ohos.extension.card",
                "value": "config:./resources/base/profile/card_config.json"
              }
            ]
          }
        }
      ]
    }
  ]
}

3.3.2 配置卡片尺寸

在entry/src/main/resources/base/profile/card_config.json中定义卡片尺寸：

json 复制代码

{
  "card": [
    {
      "name": "todo_small",
      "description": "小尺寸待办卡片",
      "type": "1x2",  // 1行2列
      "snapshot": false,
      "updateEnabled": true,
      "formVisibleNotify": true,
      "metaData": {
        "customizeData": []
      }
    },
    {
      "name": "todo_medium",
      "description": "中尺寸待办卡片",
      "type": "2x2",  // 2行2列
      "snapshot": false,
      "updateEnabled": true,
      "formVisibleNotify": true,
      "metaData": {
        "customizeData": []
      }
    },
    {
      "name": "todo_large",
      "description": "大尺寸待办卡片",
      "type": "2x4",  // 2行4列
      "snapshot": false,
      "updateEnabled": true,
      "formVisibleNotify": true,
      "metaData": {
        "customizeData": []
      }
    }
  ]
}

3.4 开发服务卡片UI

3.4.1 小尺寸卡片（TodoSmallCard.ets）

ets 复制代码

// entry/src/main/ets/extensionability/card/TodoSmallCard.ets
import formBindingData from '@ohos.app.form.formBindingData';
import formProvider from '@ohos.app.form.formProvider';

@Component
export default struct TodoSmallCard {
  @State todoCount: number = 0;
  @State completedCount: number = 0;
  
  // 卡片初始化
  aboutToAppear() {
    this.loadTodoCount();
  }
  
  // 加载待办数量
  async loadTodoCount() {
    // 从分布式存储获取数据
    const kvUtil = DistributedKVUtil.getInstance();
    const todos = await kvUtil.getAllTodoItems();
    this.todoCount = todos.length;
    this.completedCount = todos.filter(item => item.completed).length;
  }
  
  // 点击卡片事件
  async onCardClick() {
    // 打开原子化服务主页面
    const context = getContext(this) as common.UIAbilityContext;
    await context.startAbility({
      bundleName: context.bundleName,
      abilityName: 'TodoEditAbility'
    });
  }
  
  build() {
    Column({ space: 12 }) {
      Text('快捷待办')
        .fontSize(16)
        .fontWeight(FontWeight.Bold);
      
      Row({ space: 24 }) {
        Text(`待办: ${this.todoCount}`)
          .fontSize(14);
        
        Text(`已完成: ${this.completedCount}`)
          .fontSize(14)
          .fontColor('#007DFF');
      }
      
      Button('添加待办')
        .width('80%')
        .height(36)
        .backgroundColor('#007DFF')
        .fontColor(Color.White)
        .onClick(() => this.onCardClick());
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor(Color.White);
  }
}

3.4.2 中尺寸卡片（TodoMediumCard.ets）

ets 复制代码

// entry/src/main/ets/extensionability/card/TodoMediumCard.ets
@Component
export default struct TodoMediumCard {
  @State todoList: TodoItem[] = [];
  
  aboutToAppear() {
    this.loadTodoList();
  }
  
  async loadTodoList() {
    const kvUtil = DistributedKVUtil.getInstance();
    const todos = await kvUtil.getAllTodoItems();
    // 只显示前3条待办
    this.todoList = todos.slice(0, 3);
  }
  
  async onTodoClick(item: TodoItem) {
    // 切换待办状态
    const kvUtil = DistributedKVUtil.getInstance();
    await kvUtil.updateTodoStatus(item.id, !item.completed);
    // 更新卡片
    this.refreshCard();
  }
  
  async refreshCard() {
    // 更新卡片数据
    const formData = formBindingData.createFormBindingData({
      todoList: this.todoList
    });
    
    // 获取当前卡片Id
    const context = getContext(this) as ExtensionContext;
    const formId = context.formInfo.formId;
    // 刷新卡片
    await formProvider.updateForm(formId, formData);
  }
  
  build() {
    Column({ space: 16 }) {
      Text('我的待办')
        .fontSize(18)
        .fontWeight(FontWeight.Bold);
      
      List({ space: 10 }) {
        ForEach(this.todoList, item => {
          ListItem() {
            Row({ space: 12 }) {
              Checkbox()
                .checked(item.completed)
                .onChange(() => this.onTodoClick(item));
              
              Text(item.content)
                .fontSize(14)
                .maxLines(1)
                .overflow(TextOverflow.Ellipsis)
                .textDecoration({
                  type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None
                });
            }
            .width('100%')
          }
        }, item => item.id);
      }
      
      Button('查看全部')
        .width('80%')
        .height(36)
        .backgroundColor('#007DFF')
        .fontColor(Color.White)
        .onClick(() => {
          const context = getContext(this) as common.UIAbilityContext;
          context.startAbility({
            bundleName: context.bundleName,
            abilityName: 'TodoListAbility'
          });
        });
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor(Color.White);
  }
}

3.5 实现服务逻辑

3.5.1 卡片扩展能力

ets 复制代码

// entry/src/main/ets/extensionability/card/TodoCardExtensionAbility.ts
import Base from '@ohos.app.form.formExtensionAbility';
import formBindingData from '@ohos.app.form.formBindingData';
import DistributedKVUtil from '../../../utils/DistributedKV';

export default class TodoCardExtensionAbility extends Base {
  // 卡片请求更新
  onUpdate(formId: string) {
    // 加载最新数据
    DistributedKVUtil.getInstance().getAllTodoItems().then(todos => {
      // 构建卡片数据
      const formData = formBindingData.createFormBindingData({
        todoCount: todos.length,
        completedCount: todos.filter(item => item.completed).length,
        todoList: todos.slice(0, 3)
      });
      
      // 更新卡片
      this.updateForm(formId, formData);
    });
  }
  
  // 卡片删除
  onUninstall(formId: string) {
    console.log('卡片已删除:', formId);
  }
  
  // 卡片点击
  onClick(formId: string, message: string) {
    console.log('卡片点击:', message);
  }
}

四、测试与调试📊

4.1 卡片预览

打开DevEco Studio，点击Previewer面板
选择Card模式，选择对应尺寸的卡片
实时预览卡片UI与交互效果

4.2 设备调试

连接鸿蒙设备，点击Run →Run 'entry'
在设备桌面上，长按空白处→点击添加卡片
找到「快捷待办」卡片，添加到桌面
测试卡片的点击、刷新、状态更新功能

五、常见问题与解决方案⚠️

5.1 卡片添加失败

问题：设备桌面上找不到原子化服务卡片
解决方案：

检查config.json中installFree是否设置为true
确认设备系统版本为鸿蒙3.0+
确保卡片尺寸配置正确

5.2 卡片数据不更新

问题：修改待办后，卡片数据长时间不刷新
解决方案：

检查card_config.json中updateEnabled是否设置为true
调用formProvider.updateForm()手动刷新卡片
确保分布式数据同步正常

5.3 点击事件无效

问题：点击卡片无响应
解决方案：

检查CardExtensionAbility的onClick方法是否正确实现
确保context.startAbility()的参数配置正确
检查应用权限是否齐全

六、总结与拓展✅

6.1 本章总结

通过本章学习，我们掌握了：

鸿蒙原子化服务的核心概念与特性
原子化服务的配置与卡片开发流程
不同尺寸卡片的UI开发与交互实现
卡片扩展能力的生命周期管理

6.2 拓展练习

开发大尺寸待办卡片，支持更多功能
实现卡片的定时刷新功能
支持卡片的跨设备流转
开发音乐播放、天气查询等原子化服务

6.3 进阶学习方向

原子化服务的性能优化
卡片的个性化配置
原子化服务与分布式能力的结合
原子化服务的上架与运营

原子化服务是鸿蒙生态的未来趋势，掌握原子化服务开发将帮助你构建更具竞争力的轻量应用。通过不断实践与创新，你将在鸿蒙生态开发中占据领先地位！