1. 项目概述：从“卡片”到“服务”的思维跃迁

上一篇文章我们聊透了HarmonyOS原子化服务的基础概念、开发环境搭建以及第一个“Hello World”卡片的创建。如果你已经跟着做了一遍，现在应该已经能感受到，原子化服务开发的核心，其实是一种全新的交互与分发思维。它不再是传统意义上需要下载、安装、占据大量存储空间的“App”，而是一个个轻巧、即用即走的“服务卡片”。今天这篇“下篇”，我们将深入腹地，探讨如何让这张静态的卡片“活”起来，具备真正的服务能力。这包括数据动态更新、复杂交互响应、跨设备流转以及最终的测试与上架。我会结合我实际开发中的踩坑经验，把官方文档里那些一笔带过的细节给你掰开揉碎了讲明白。

很多人觉得原子化服务就是做个UI卡片，其实远不止于此。它的精髓在于“服务”二字。想象一下，你做了一个航班动态卡片，用户无需打开任何App，在桌面就能看到航班号、登机口、延误状态，并且这个信息是实时从航空公司服务器拉取的；或者你做了一个智能家居控制卡片，用户轻轻一点就能开关客厅的灯，这个指令需要毫秒级地发送到云端再下达到设备。这背后涉及到的网络请求、数据绑定、事件处理、权限声明，才是原子化服务开发真正的挑战和魅力所在。所以，这篇教程的目标，是带你从一个“卡片制作师”升级为“服务架构师”。

2. 核心架构解析：FA模型与Stage模型的抉择

在HarmonyOS应用开发中，你会遇到两个核心模型：FA（Feature Ability）模型和Stage模型。对于新手来说，这可能是第一个让人困惑的岔路口。简单来说，FA模型是HarmonyOS早期推出的模型，概念上更接近传统的Android开发，上手相对容易。而Stage模型是HarmonyOS 3.0（API 9）及以后版本主推的新模型，它引入了更清晰的UI生命周期管理（UIAbility、WindowStage等概念），旨在提供更好的性能和多设备协同能力。

注意 ：对于全新的原子化服务项目，我强烈建议你直接选择Stage模型。虽然学习曲线稍陡，但这是未来的方向，官方的新特性和优化都会优先向Stage模型倾斜。FA模型更多是为了兼容存量应用。本教程后续的所有代码示例和讲解，都将基于Stage模型展开，这能确保你的项目具备更长的技术生命周期。

那么，在Stage模型下，一个原子化服务项目的基本结构是怎样的呢？当你用DevEco Studio创建一个Empty Ability项目（选择Stage模型）后，你会看到类似如下的目录树：

MyAtomicService/
├── entry/          # 主模块
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/                 # 业务逻辑代码
│   │   │   │   ├── entryability/
│   │   │   │   │   └── EntryAbility.ts  # 应用/服务入口能力
│   │   │   │   ├── pages/
│   │   │   │   │   └── index.ets    # 卡片的UI页面
│   │   │   │   └── model/           # 数据模型层（可自建）
│   │   │   ├── resources/           # 资源文件（图片、字符串等）
│   │   │   └── module.json5         # 模块配置文件（重中之重！）
│   │   └── ohosTest/                # 测试代码
│   └── build-profile.json5
├── build-profile.json5
└── hvigorfile.ts

这里你需要重点关注两个文件： EntryAbility.ts 和 module.json5 。 EntryAbility 是你的服务启动的入口，但原子化服务卡片很多时候是“无入口”运行的，卡片本身就是一个UI组件。 module.json5 则是你服务的“身份证”和“说明书”，里面定义了你的服务类型、卡片信息、权限申请等，任何配置错误都可能导致服务无法正常显示或运行。

3. 动态卡片开发：让数据“动”起来

一个只会显示固定文字的卡片是缺乏生命力的。原子化服务的核心价值在于信息的实时性。HarmonyOS提供了强大的数据管理机制来实现动态更新，主要依靠 @State 、 @Prop 、 @Link 等装饰器以及AppStorage。

3.1 状态管理与数据绑定

让我们改造上一篇文章那个简单的 index.ets ，实现一个点击按钮增加数字的计数器卡片。

// index.ets
@Entry
@Component
struct Index {
  // 使用@State装饰器，表示这个数据是组件的内部状态，变化会触发UI刷新
  @State count: number = 0

  build() {
    Column({ space: 20 }) {
      // 文本内容绑定到count状态变量
      Text(`当前计数：${this.count}`)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)

      Button('点我加1')
        .width(120)
        .height(40)
        .backgroundColor('#007DFF')
        .onClick(() => {
          // 点击事件中改变状态，UI会自动更新
          this.count++
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

这段代码运行后，你会得到一个卡片，每次点击按钮，数字都会增加。 @State 装饰器是关键，它建立了数据和UI之间的响应式关系。这里有个 实操心得 ：对于只在单个页面内使用的简单状态，用 @State 就足够了。但如果你的数据需要在多个UIAbility或者多个卡片之间共享，你就需要考虑使用AppStorage（应用全局的“仓库”）或者LocalStorage（页面内的“仓库”）。

3.2 网络请求与数据更新

真正的服务卡片需要从外部获取数据。HarmonyOS使用 @ohos.net.http 模块进行网络请求。由于原子化服务对包大小和性能有严格要求，务必注意请求的频次和数据量。

假设我们要做一个显示今日天气的卡片，我们需要：

  1. 申请网络权限 ：在 module.json5 文件中添加权限声明。

    {
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

  2. 编写数据获取函数 ：通常我们会封装一个专门的数据管理类。

    // 假设在 src/main/ets/model/WeatherModel.ts
import http from '@ohos.net.http';
import { WeatherData } from './WeatherData'; // 自定义的数据类型

export class WeatherModel {
  private static readonly API_URL = 'https://api.weather.example.com/current'; // 替换为真实API

  static async fetchWeather(city: string): Promise<WeatherData> {
    let httpRequest = http.createHttp();
    try {
      let response = await httpRequest.request(
        `${this.API_URL}?city=${encodeURIComponent(city)}`,
        {
          method: http.RequestMethod.GET,
          connectTimeout: 60000,
          readTimeout: 60000,
        }
      );
      if (response.responseCode === 200) {
        let result = JSON.parse(response.result.toString());
        // 将API返回的数据解析成我们定义的WeatherData对象
        return {
          city: result.city,
          temperature: result.temp,
          condition: result.condition,
          updateTime: new Date().toLocaleTimeString()
        };
      } else {
        throw new Error(`HTTP Error: ${response.responseCode}`);
      }
    } catch (error) {
      console.error('Fetch weather failed:', error);
      throw error;
    } finally {
      httpRequest.destroy();
    }
  }
}

  3. 在卡片UI中集成并定时更新 ：

    // index.ets
import { WeatherModel } from '../model/WeatherModel';
import { WeatherData } from '../model/WeatherData';

@Entry
@Component
struct WeatherCard {
  // 使用@State管理天气数据
  @State weatherData: WeatherData = { city: '北京', temperature: '--', condition: '加载中...', updateTime: '' };

  // 生命周期函数：卡片显示时加载数据
  aboutToAppear() {
    this.loadWeather();
    // 设置每30分钟自动更新一次（根据服务场景调整）
    setInterval(() => {
      this.loadWeather();
    }, 30 * 60 * 1000);
  }

  private loadWeather() {
    WeatherModel.fetchWeather(this.weatherData.city).then(data => {
      this.weatherData = data;
    }).catch(err => {
      console.error('加载天气失败:', err);
      this.weatherData.condition = '网络异常';
    });
  }

  build() {
    Column({ space: 15 }) {
      Text(this.weatherData.city)
        .fontSize(24)
        .fontColor('#333333')
      Text(`${this.weatherData.temperature}°C`)
        .fontSize(48)
        .fontWeight(FontWeight.Bold)
        .fontColor('#007DFF')
      Text(this.weatherData.condition)
        .fontSize(18)
        .fontColor('#666666')
      Text(`更新于: ${this.weatherData.updateTime}`)
        .fontSize(12)
        .fontColor('#999999')
    }
    .padding(20)
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

踩坑提示 ：网络请求一定要做好错误处理（try-catch）和加载状态显示。原子化服务卡片可能在网络环境不佳的场景下使用，如果请求失败没有任何提示，用户体验会非常差。此外，频繁的网络请求会消耗用户电量，务必根据信息的重要程度合理设置更新间隔。对于实时性要求不高的信息（如新闻摘要），可以考虑使用后台定时任务+本地缓存的方式。

4. 复杂交互与事件处理

卡片不仅仅是展示，更需要交互。HarmonyOS为卡片组件提供了丰富的事件，如 onClick （点击）、 onTouch （触摸）、 onSwipe （滑动）等。更高级的交互，比如在卡片上展示一个可操作的列表，则需要使用 List 、 Swiper 等容器组件配合事件。

4.1 实现一个待办事项卡片

这个卡片可以展示几条最近的待办，点击某项可以标记完成，右上角有个“+”按钮可以快速添加（这里假设点击后跳转到服务的完整应用界面）。

// TodoItem.ts - 定义数据类型
export class TodoItem {
  id: number = 0;
  title: string = '';
  completed: boolean = false;
}

// TodoCard.ets
import { TodoItem } from './TodoItem';

@Entry
@Component
struct TodoCard {
  // 待办列表数据
  @State todoList: TodoItem[] = [
    { id: 1, title: '阅读HarmonyOS官方文档', completed: false },
    { id: 2, title: '完成原子化服务Demo', completed: true },
    { id: 3, title: '撰写项目周报', completed: false },
  ];

  build() {
    Column() {
      // 标题栏
      Row({ space: 10 }) {
        Text('今日待办')
          .fontSize(22)
          .fontWeight(FontWeight.Medium)
          .layoutWeight(1) // 占据剩余空间
        // 添加按钮，点击后触发`addTodo`方法（这里简化处理）
        Image($r('app.media.ic_add')) // 需要准备一个加号图标资源
          .width(24)
          .height(24)
          .onClick(() => {
            // 实际开发中，这里可以触发一个弹窗或跳转
            console.log('跳转到添加待办页面');
            // 例如：router.pushUrl({ url: 'pages/AddTodoPage' });
          })
      }
      .width('100%')
      .padding({ left: 20, right: 20, top: 15 })

      // 待办列表
      List({ space: 10 }) {
        ForEach(this.todoList, (item: TodoItem) => {
          ListItem() {
            Row({ space: 15 }) {
              // 完成状态复选框
              Image(item.completed ? $r('app.media.ic_checked') : $r('app.media.ic_unchecked'))
                .width(20)
                .height(20)
                .onClick(() => {
                  // 点击切换完成状态
                  this.toggleTodo(item.id);
                })
              Text(item.title)
                .fontSize(18)
                .fontColor(item.completed ? '#999999' : '#333333')
                .decoration({ type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
                .layoutWeight(1)
                .onClick(() => {
                  // 点击文本也可以切换状态（提供更大点击区域）
                  this.toggleTodo(item.id);
                })
            }
            .width('100%')
            .padding(15)
            .backgroundColor('#FFFFFF')
            .borderRadius(12)
          }
        }, (item: TodoItem) => item.id.toString())
      }
      .width('100%')
      .layoutWeight(1)
      .padding(15)
      .listDirection(Axis.Vertical)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F8F9FA')
  }

  // 切换待办项状态的方法
  private toggleTodo(id: number) {
    const index = this.todoList.findIndex(item => item.id === id);
    if (index !== -1) {
      // 注意：直接修改数组元素不会触发UI更新。需要创建一个新数组。
      this.todoList[index].completed = !this.todoList[index].completed;
      // 使用扩展运算符创建新数组引用，驱动UI刷新
      this.todoList = [...this.todoList];
    }
  }
}

这个例子涵盖了 List 和 ForEach 的用法、条件渲染（根据 completed 显示不同图标和文字样式）、组件事件处理以及 最重要的——状态数组的更新技巧 。直接修改数组元素（ this.todoList[index].completed = true ）在ArkUI中不会触发页面刷新，必须给 @State 装饰的变量赋予一个全新的数组引用（ this.todoList = [...this.todoList] ），这是新手常踩的一个坑。

4.2 卡片配置与更新能力

用户可能希望自定义卡片内容，比如在天气卡片里切换城市。这需要通过卡片的“配置能力”来实现。你需要在 module.json5 中为卡片配置 supportDimensions 和 updateEnabled 等属性，并实现一个配置页面。

在 module.json5 的 abilities 下的 forms 字段中，可以配置：

"forms": [{
  "name": "widget",
  "description": "这是一个天气卡片",
  "src": "./ets/widget/pages/WidgetCard.ets",
  "uiSyntax": "arkts",
  "window": { "designWidth": 720 },
  "colorMode": "auto",
  "isDefault": true,
  "updateEnabled": true, // 启用周期性更新
  "scheduledUpdateTime": "10:30", // 每日更新时间
  "updateDuration": 1, // 更新周期，单位为天
  "defaultDimension": "2*2",
  "supportDimensions": ["2*2", "2*4"] // 支持的卡片尺寸
}]

然后，你需要实现一个配置页面（例如 WidgetConfig.ets ），当用户长按卡片选择“服务卡片”->“配置”时，会跳转到这个页面。在这个页面中，用户可以设置城市、温度单位等。配置信息可以通过 formProvider.setFormNextRefreshTime 或 formProvider.updateForm 来触发卡片的即时更新。

5. 跨设备流转：原子化服务的“高光时刻”

原子化服务最酷的特性之一就是跨设备无缝流转。用户可以将手机上的服务卡片，一键分享到平板、智慧屏甚至车机上，服务状态（比如正在播放的音乐、阅读的文章进度）可以实时同步。

实现跨设备流转，核心是使用HarmonyOS的分布式数据管理能力，主要是 DistributedDataObject 或 DistributedDataKit 。

5.1 使用DistributedDataObject同步简单状态

假设我们有一个“协同绘画”的简单卡片，在一个设备上画一笔，其他设备上能实时看到。

  1. 申请分布式数据权限 ：

    // module.json5
"requestPermissions": [
  {
    "name": "ohos.permission.DISTRIBUTED_DATASYNC"
  }
]

  2. 创建和同步分布式数据对象 ：

    import distributedObject from '@ohos.data.distributedDataObject';

@Entry
@Component
struct CollaborativeCanvas {
  // 创建一个分布式数据对象，key是其在网络中的唯一标识
  private distObject: distributedObject.DataObject = distributedObject.createDataObject({
    local: { // 本地对象
      lastDrawX: 0,
      lastDrawY: 0,
      color: '#FF0000'
    }
  });

  aboutToAppear() {
    // 监听远端数据变化
    this.distObject.on('change', (sessionId, fields) => {
      console.log(`数据被设备${sessionId}改变，变更字段：${fields}`);
      // 这里可以触发UI重绘，根据新的lastDrawX, lastDrawY和color画点
      this.redrawCanvas();
    });
  }

  // 当用户在本设备绘画时，更新分布式对象
  handleCanvasTouch(event: TouchEvent) {
    const touch = event.touches[0];
    this.distObject.lastDrawX = touch.x;
    this.distObject.lastDrawY = touch.y;
    // 修改后，需要调用save保存并同步到组网内的其他设备
    this.distObject.save('myCollaborativeCanvas').then(() => {
      console.log('数据已保存并同步');
    }).catch((err) => {
      console.error('数据同步失败:', err);
    });
  }

  aboutToDisappear() {
    this.distObject.off('change');
    this.distObject.revokeSave(); // 撤销保存，停止同步
  }

  build() {
    // ... 构建画布UI，并将onTouch事件绑定到handleCanvasTouch
  }
}

重要经验 ：跨设备流转对网络稳定性要求高。在实际开发中，一定要处理好网络断连、设备离线等异常情况。数据同步的延迟和冲突（两个设备同时修改同一个数据）也是需要设计策略来解决的复杂问题，对于关键状态，可能需要引入版本号或操作日志。初次尝试，建议从同步简单的状态（如开关状态、选中项）开始。

6. 真机调试、测试与上架发布

开发完成后，你肯定迫不及待想看看它在真实手机上的样子。

6.1 真机调试

  1. 准备设备 ：你需要一台搭载HarmonyOS 3.0或以上版本的华为/荣耀手机，并开启“开发者模式”和“USB调试”。
  2. 签名配置 ：HarmonyOS应用必须签名后才能安装到真机。在DevEco Studio中，选择 File > Project Structure > Project > Signing Configs ，配置你的调试证书（Automatically generate signature会自动生成，适合调试）。
  3. 运行 ：用USB连接手机，在DevEco Studio顶部选择你的设备，点击运行按钮。你的原子化服务就会安装到手机上。

调试技巧 ：

  • 日志查看 ：使用 hdc shell hilog 命令查看设备日志，或者使用DevEco Studio的“Log”窗口。
  • 卡片调试 ：在手机桌面长按，进入“服务卡片”模式，找到你的卡片并添加到桌面。如果卡片没有出现，请检查 module.json5 中 forms 的配置是否正确，特别是 src 路径和 name 。
  • 远程模拟器 ：如果没有真机，可以使用华为提供的远程模拟器，但网络流畅度会影响体验，且部分真机特有的传感器功能无法测试。

6.2 全面测试清单

在提交上架前，请务必完成以下测试：

测试类别 测试项 说明与技巧
功能测试 卡片正常显示 在不同尺寸（2x2, 2x4等）下UI是否正常布局，无元素被裁剪。
动态数据更新 网络请求是否成功，数据是否正确绑定和显示，加载/错误状态是否友好。
交互响应 所有按钮、列表项点击事件是否正常触发，反馈是否及时。
配置功能 卡片的配置页面是否可用，配置能否生效并更新卡片。
跨设备流转 在多设备组网下，数据同步是否正常，流转过程是否流畅。
性能测试 冷启动速度 首次添加到桌面或长时间未使用后打开，卡片渲染速度。
内存占用 在手机“开发者选项-内存”中观察服务进程的内存使用，避免内存泄漏。
耗电量 后台定时更新或网络请求是否导致异常耗电。
包体积 检查最终 .hap 文件大小，原子化服务应力求轻量。
兼容性测试 多设备型号 在不同屏幕尺寸、分辨率的华为/荣耀设备上测试显示效果。
多系统版本 在HarmonyOS 3.0, 4.0等主要版本上测试核心功能。
稳定性测试 长时间运行 将卡片添加到桌面，保持设备运行24小时以上，观察是否崩溃或卡死。
网络切换 在Wi-Fi、4G/5G、无网络环境下切换，测试卡片的重连和降级处理。
快速操作 对卡片进行快速、连续的点击或滑动操作，测试是否会出现无响应。

6.3 上架华为应用市场

测试无误后，就可以准备上架了。

  1. 生成发布证书 ：在 AppGallery Connect 网站，为你的应用创建项目，并生成正式的发布证书。这个证书与调试证书不同，用于应用市场签名。
  2. 构建Release HAP ：在DevEco Studio中，选择 Build > Build Haps(s)/APP(s) > Build Release Hap(s) ，使用你的发布证书进行签名。
  3. 提交审核 ：登录AppGallery Connect，上传签名的HAP文件，填写应用信息、服务卡片介绍、截图等。 特别注意 ：原子化服务的描述要突出其“免安装”、“即用即走”、“卡片化交互”的核心优势。
  4. 关注审核反馈 ：华为审核团队可能会对权限使用合理性、隐私政策、内容合规性等提出要求，及时响应修改。

上架避坑指南 ：

  • 隐私政策 ：只要你的应用（服务）收集了任何用户数据（即使用户不可见，如设备标识符用于统计分析），就必须在应用内提供可访问的隐私政策链接。这是审核红线。
  • 权限最小化 ：只申请你服务必须的权限，并在 module.json5 和隐私声明中清晰解释每一项权限的用途。过度申请权限是常见的被拒原因。
  • 卡片预览图 ：提供高清、美观的卡片预览图，这能极大提升用户在应用市场的点击率。
  • 多语言支持 ：如果你的服务面向全球，考虑添加多语言资源，这能帮助你覆盖更广的市场。

走到这一步，恭喜你，你已经完成了一个完整、可用的HarmonyOS原子化服务从0到1的开发和发布全流程。回顾一下，我们从理解概念开始，搭建环境、创建静态卡片，然后深入动态数据绑定、复杂交互、跨设备流转，最后完成测试和上架。每一个环节都充满了细节和挑战，但正是这些细节，决定了你的服务是“玩具”还是真正能解决用户痛点的“产品”。原子化服务生态还在快速发展中，现在正是深入学习和实践的最佳时机。希望这篇教程能成为你探索之路的一块坚实垫脚石。如果在实践中遇到任何具体问题，最好的老师永远是官方文档、社区论坛和你自己的调试器。动手去试，踩坑，然后爬出来，这是成长最快的方式。

# 原子化服务
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS NEXT AI 智能生活助手：Provider 扩展机制

avatar HarmonyOS开发者社区
cover

给同事发了个鸿蒙APP，结果安装失败了？这份避坑指南请收好

avatar HarmonyOS开发者社区
cover

什么样的台灯最护眼耐用？耐用型学习护眼灯推荐，兼顾舒适与长久使用

avatar HarmonyOS开发者社区