鸿蒙原子化服务与元服务卡片开发指南

原子化服务与元服务卡片开发

内容承接与核心价值

本文承接页面路由与组件跳转知识，为后续电商购物车全栈项目铺垫原子化服务和元服务卡片的核心技术。

学习目标：

• 掌握原子化服务的定义与架构；
• 实现商品搜索与购物车两个核心业务场景的原子化服务；
• 理解元服务卡片的原理与实现方式；
• 开发商品推荐与购物车数量两个元服务卡片；
• 优化元服务卡片的用户体验（动态更新、手势操作）。

学习重点：

• 原子化服务的开发流程；
• 元服务卡片的分类与使用场景；
• 元服务卡片的开发与部署；
• 元服务卡片的动态更新与数据同步。

一、原子化服务基础

1.1 原子化服务定义

原子化服务是 HarmonyOS Next 推出的一种全新的应用形态，具有以下特点：

• 轻量化：无需安装，即点即用；
• 免安装：通过华为应用市场、负一屏、桌面卡片等入口直接访问；
• 场景化：针对特定业务场景设计，提供单一功能；
• 跨设备：支持在超级终端上运行，如手机、平板、智慧屏、手表等。

1.2 原子化服务架构

原子化服务采用单 Ability 架构，由以下部分组成：

• Ability：负责处理业务逻辑；
• 页面：负责展示用户界面；
• 元服务卡片：负责快速访问核心功能；
• 数据管理：负责数据存储与同步。

二、原子化服务实战

2.1 实战目标

基于 MyFirstHarmonyApp 项目架构，实现以下功能：

• 商品搜索原子化服务：无需安装，直接搜索商品；
• 购物车原子化服务：无需安装，直接查看购物车商品；
• 商品推荐元服务卡片：在桌面展示推荐商品；
• 购物车数量元服务卡片：在桌面展示购物车商品数量。

2.2 项目结构调整

在 entry/src/main/ets 目录下创建以下文件夹：

• atomic：存放原子化服务相关代码；
• widgets：存放元服务卡片相关代码。

2.3 原子化服务实现

1. 商品搜索原子化服务

entry/src/main/ets/atomic/SearchAbility.ets

import hilog from '@ohos.hilog';
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import type AbilityConstant from '@ohos.ability.abilityConstant';
import type Want from '@ohos.app.ability.Want';
import BaseAbility from '../entryability/BaseAbility';

export default class SearchAbility extends BaseAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onCreate');
  }

  onDestroy(): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onWindowStageCreate');
    windowStage.loadContent('pages/SearchPage', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'SEARCH_ABILITY', 'Failed to load content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
      hilog.info(0x0000, 'SEARCH_ABILITY', 'Succeeded in loading content. Data: %{public}s', JSON.stringify(data) ?? '');
    });
  }

  onWindowStageDestroy(): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onForeground');
  }

  onBackground(): void {
    hilog.info(0x0000, 'SEARCH_ABILITY', '%{public}s', 'SearchAbility onBackground');
  }
}

entry/src/main/ets/entryability/BaseAbility.ets

import hilog from '@ohos.hilog';
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import type AbilityConstant from '@ohos.ability.abilityConstant';
import type Want from '@ohos.app.ability.Want';
import UIAbility from '@ohos.app.ability.UIAbility';
import type Window from '@ohos.window';

export default class BaseAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onCreate');
  }

  onDestroy(): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onDestroy');
  }

  onWindowStageCreate(windowStage: Window.WindowStage): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onWindowStageCreate');
  }

  onWindowStageDestroy(): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onForeground');
  }

  onBackground(): void {
    hilog.info(0x0000, 'BASE_ABILITY', '%{public}s', 'BaseAbility onBackground');
  }
}

2.4 元服务卡片实现

1. 商品推荐元服务卡片

entry/src/main/ets/widgets/ProductRecommendWidget.ets

import { GoodsModel } from '../models/HomeModel';
import { goodsData } from '../models/HomeData';
import { RouterUtils } from '../utils/RouterUtils';

@Entry
@Component
struct ProductRecommendWidget {
  @State goodsList: Array<GoodsModel> = goodsData.slice(0, 3);

  build() {
    Grid() {
      ForEach(this.goodsList, (item: GoodsModel) => {
        GridItem() {
          Column({ space: 8 }) {
            Image(item.imageUrl).width('100%').height(120).objectFit(ImageFit.Cover).borderRadius(8);
            Text(item.name).fontSize(14).fontWeight(FontWeight.Bold).textColor('#000000').maxLines(2).ellipsis({ overflow: TextOverflow.Ellipsis });
            Text(`¥${item.price}`).fontSize(16).fontWeight(FontWeight.Bold).textColor('#FF0000');
          }.width('100%').height('auto').padding(8).backgroundColor('#FFFFFF').borderRadius(12).onClick(() => {
            RouterUtils.push('pages/ProductDetailPage', { id: item.id });
          });
        }.width('33.33%').height('auto');
      }, (item: GoodsModel) => item.id.toString());
    }.columnsTemplate('1fr 1fr 1fr').columnsGap(8).rowsGap(8).width('100%').height('auto').padding(8);
  }
}

2. 购物车数量元服务卡片

entry/src/main/ets/widgets/CartCountWidget.ets

import { GlobalStateManager } from '../utils/GlobalState';
import { RouterUtils } from '../utils/RouterUtils';

@Entry
@Component
struct CartCountWidget {
  @State cartCount: number = GlobalStateManager.getInstance().getState().cartCount;

  build() {
    Row({ space: 16 }) {
      Image($r('app.media.cart')).width(24).height(24).objectFit(ImageFit.Contain);
      Text(`购物车：${this.cartCount}`).fontSize(14).textColor('#000000');
      if (this.cartCount > 0) {
        Text(`${this.cartCount}`).fontSize(12).textColor('#FFFFFF').backgroundColor('#FF0000').width(20).height(20).textAlign(TextAlign.Center).borderRadius(10);
      }
    }.width('100%').height('auto').padding(16).backgroundColor('#FFFFFF').borderRadius(12).onClick(() => {
      RouterUtils.push('pages/CartPage');
    });
  }

  aboutToAppear() {
    AppStorage.watch('globalState', () => {
      this.cartCount = GlobalStateManager.getInstance().getState().cartCount;
    });
  }
}

三、项目配置与部署

3.1 配置文件修改

1. module.json5 修改

在 entry/src/main/module.json5 中添加原子化服务与元服务卡片配置：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ],
        "orientation": "portrait"
      },
      {
        "name": "SearchAbility",
        "srcEntry": "./ets/atomic/SearchAbility.ets",
        "description": "$string:SearchAbility_desc",
        "icon": "$media:icon",
        "label": "$string:SearchAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ],
        "orientation": "portrait"
      },
      {
        "name": "CartAbility",
        "srcEntry": "./ets/atomic/CartAbility.ets",
        "description": "$string:CartAbility_desc",
        "icon": "$media:icon",
        "label": "$string:CartAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ],
        "orientation": "portrait"
      }
    ],
    "widgets": [
      {
        "name": "ProductRecommendWidget",
        "srcEntry": "./ets/widgets/ProductRecommendWidget.ets",
        "description": "$string:ProductRecommendWidget_desc",
        "icon": "$media:icon",
        "label": "$string:ProductRecommendWidget_label",
        "type": "Home",
        "scheduledUpdateTime": "08:00",
        "updateDuration": 3600
      },
      {
        "name": "CartCountWidget",
        "srcEntry": "./ets/widgets/CartCountWidget.ets",
        "description": "$string:CartCountWidget_desc",
        "icon": "$media:icon",
        "label": "$string:CartCountWidget_label",
        "type": "Home",
        "scheduledUpdateTime": "08:00",
        "updateDuration": 3600
      }
    ],
    "pages": ["pages/Index", "pages/SearchPage", "pages/ProductDetailPage", "pages/CartPage", "pages/OrderPage", "pages/PaymentPage", "pages/LoginPage", "pages/MyPage"]
  }
}

2. strings.json 修改

在 entry/src/main/resources/base/element/string.json 中添加原子化服务与元服务卡片的描述信息：

{
  "string": [
    { "name": "EntryAbility_label", "value": "MyFirstHarmonyApp" },
    { "name": "EntryAbility_desc", "value": "我的第一个鸿蒙应用" },
    { "name": "SearchAbility_label", "value": "商品搜索" },
    { "name": "SearchAbility_desc", "value": "商品搜索原子化服务" },
    { "name": "CartAbility_label", "value": "购物车" },
    { "name": "CartAbility_desc", "value": "购物车原子化服务" },
    { "name": "ProductRecommendWidget_label", "value": "商品推荐" },
    { "name": "ProductRecommendWidget_desc", "value": "商品推荐元服务卡片" },
    { "name": "CartCountWidget_label", "value": "购物车数量" },
    { "name": "CartCountWidget_desc", "value": "购物车数量元服务卡片" }
  ]
}

3.2 项目部署

1. 编译项目

在 DevEco Studio 中点击 Build → Build HAP，编译项目。

2. 部署到设备

将编译后的 HAP 文件部署到鸿蒙设备上。

3. 测试原子化服务

• 在华为应用市场搜索「商品搜索」或「购物车」，点击进入原子化服务；
• 在负一屏添加「商品推荐」或「购物车数量」元服务卡片。