构建第一个HarmonyOS元服务

目录

一、创建元服务工程

1.首次构建

2.登录账号

3.完成授权

[4.APP ID](#4.APP ID)

5.刷新与选择

6.工程界面

7.完成与工程目录

二、生成元服务图标

1.进入图标配置页面

2.图片要求

3.图标配置

4.保存图标

三.构建元服务页面

1.构建元服务的第一个页面

2.增加第二个页面，增加返回到第一个页面功能

3.预览器查看

四.新建元服务卡片

1.在元服务中新建一张卡片

2.添加效果

3.卡片动画效果预览

4.进入元服务

五.用模拟器运行应用元服务

1.下载模拟器

2.运行模拟器

3.添加卡片到模拟器

---

一、创建元服务工程

1.首次构建

若首次打开DevEco Studio，请选择Create Project开始创建一个新工程。如果已经打开了一个工程，请在菜单栏选择File > New > Create Project来创建一个新工程。选择Atomic Service元服务开发，选择模板，单击Next进行下一步配置。当前元服务支持的模板类型：

Empty Ability，用于Phone、Tablet设备的模板，展示基础的Hello World功能。

CloudDevEmpty Ability，端云一体化开发通用模板。Embeddable Ability：用于开发支持被其他应用嵌入式运行的元服务的工程模板，如图2-8所示。

说明，元服务不支持native开发方式，无法选择native工程模板开发元服务。

2.登录账号

点击Sign In登录华为开发者账号进行开发，或选择访客模式体验。访客模式无需登录华为账号。

说明，访客模式仅用于体验元服务开发功能。如需将访客模式下开发的元服务工程或历史元服务工程在真机上运行并安装，需在AppScope > app.json5文件中补充当前开发者账号下已在AppGallery注册且真实存在的包名，如图2-9所示。

3.完成授权

在弹出的网页界面中点击允许，完成访问账号授权，如图2-10所示

4.APP ID

选择已登录账号下的APP ID。如您未在AppGallery中注册元服务应用，点击Register APP ID注册新的APP ID。

说明，仅元服务应用的APP ID将在当前界面展示。如需新建应用，应用类型请选择"元服务"，如图2-11所示。

5.刷新与选择

完成注册后，回到DevEco Studio界面，点击Refresh，刷新当前APP ID列表，选择新生成的APP ID，点击Next，如图2-12所示。

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

6.工程界面

进入配置工程界面，填写Project name，其他参数保持默认设置即可，图2-13所示。

7.完成与工程目录

单击Finish，工具会自动生成示例代码和相关资源，等待工程创建完成。元服务工程目录结构如下，如图2-14所示。

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

Entry，HarmonyOS工程模块，编译构建生成一个HAP。

src > main > ets，用于存放ArkTS源码。

src > main > ets > entryability，元服务的入口。

src > main > ets > pages，元服务包含的页面。

src > main > resources，用于存放元服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。src > main > module.json5：模块配置文件。主要包含HAP的配置信息、元服务在具体设备上的配置信息以及元服务的全局配置信息。build-profile.json5：当前的模块信息 、编译信息配置项，包括buildOption、targets配置等。

hvigorfile.ts，模块级编译构建任务脚本，开发者可以自定义相关任务和代码实现。

oh_modules，用于存放三方库依赖信息。

build-profile.json5，元服务级配置信息，包括签名signingConfigs、产品配置products等。

hvigorfile.ts，元服务级编译构建任务脚本。

二、生成元服务图标

DevEco Studio支持Image Asset功能，帮助开发者生成统一的元服务图标样式。DevEco Studio 5.0.3.800及以上版本支持使用元服务图标生成能力。

1.进入图标配置页面

在工程中选中模块或文件，右键单击New > Image Asset，进入图标配置页面，如图2-15所示。

2.图片要求

在Path中选择本地图片路径。图片尺寸及要求如图2-16

图标格式为.png、.jpeg、.jpg格式的静态图片资源；图标尺寸为1024 x 1024 px （正方形）；图标背景为不透明；质量要求为图标内容需清晰可辨，避免存在模糊、锯齿、拉伸等问题。遵循元服务图标设计规范。

3.图标配置

在预览界面可以配置图标颜色、名称、保存路径等。

Color是推荐使用的图标颜色。选择不同颜色，右边图标预览区域可查看相应的效果。

Name是生成的图标名称。

Res Directory是生成的512px*512px尺寸图标在工程中的保存位置。

Save to是生成的216px*216px尺寸图标需要指定本地文件夹的保存位置。后续在AppGallery Connect上架元服务时，需使用该图标，如图2-17所示。

4.保存图标

点击OK，保存配置并在相应模块目录src > main > resources > base > media路径下生成元服务图标。可在模块级module.json5中的icon字段中配置元服务图标。

三.构建元服务页面

下面我们将构建元服务的两个页面，并按预定的业务逻辑，实现页面间跳转。

1.构建元服务的第一个页面

1）使用文本组件

工程同步完成后，在"Project"窗口，单击"entry > src > main > ets > pages"，打开"Index.ets"文件，可以看到页面由Text组件组成。

针对本文中使用文本/按钮来实现页面跳转/返回的应用场景，页面均使用Row和Column组件来组建布局。对于更多复杂元素对齐的场景，可选择使用RelativeContainer组件进行布局。"Index.ets"文件的代码如下：

import { authentication } from '@kit.AccountKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { router } from '@kit.ArkUI';


@Entry
@Component
struct Index {
  @State message: string = 'Hello World';


  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        // 添加按钮，以响应用户点击
        Button() {
          Text('Next')
            .fontSize(30)
            .fontWeight(FontWeight.Bold)
        }
        .type(ButtonType.Capsule)
        .margin({
          top: 20
        })
        .backgroundColor('#0D9FFB')
        .width('40%')
        .height('5%')
        // 跳转按钮绑定onClick事件，点击时跳转到第二页
        .onClick(() => {
          router.pushUrl({ url: 'pages/Second' })
        })
      }
      .width('100%')
    }
    .height('100%')
  }


  aboutToAppear() {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
    this.loginWithHuaweiID();
  }


  /**
   * Sample code for using HUAWEI ID to log in to atomic service.
   * According to the Atomic Service Review Guide, when an atomic service has an account system,
   * the option to log in with a HUAWEI ID must be provided.
   * The following presets the atomic service to use the HUAWEI ID silent login function.
   * To enable the atomic service to log in successfully using the HUAWEI ID, please refer
   * to the HarmonyOS HUAWEI ID Access Guide to configure the client ID and fingerprint certificate.
   */
  private loginWithHuaweiID() {
    // Create a login request and set parameters
    let loginRequest = new authentication.HuaweiIDProvider().createLoginWithHuaweiIDRequest();
    // Whether to forcibly launch the HUAWEI ID login page when the user is not logged in with the HUAWEI ID
    loginRequest.forceLogin = false;
    // Execute login request
    let controller = new authentication.AuthenticationController();
    controller.executeRequest(loginRequest).then((data) => {
      let loginWithHuaweiIDResponse = data as authentication.LoginWithHuaweiIDResponse;
      let authCode = loginWithHuaweiIDResponse.data?.authorizationCode;
      // Send authCode to the backend in exchange for unionID, session


    }).catch((error: BusinessError) => {
      hilog.error(0x0000, 'testTag', 'error: %{public}s', JSON.stringify(error));
      if (error.code == authentication.AuthenticationErrorCode.ACCOUNT_NOT_LOGGED_IN) {
        // HUAWEI ID is not logged in, it is recommended to jump to the login guide page


      }
    });
  }
}

2.增加第二个页面，增加返回到第一个页面功能

在第二个页面中，返回按钮绑定onClick事件，点击按钮时返回到第一页。"Second.ets"文件的代码如下：

import { router } from '@kit.ArkUI'


@Entry
@Component
struct Second {
  @State message: string = 'Hi there'


  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Button() {
          Text('Back')
            .fontSize(25)
            .fontWeight(FontWeight.Bold)
        }
        .type(ButtonType.Capsule)
        .margin({
          top: 20
        })
        .backgroundColor('#0D9FFB')
        .width('40%')
        .height('5%')
        // 返回按钮绑定onClick事件，点击按钮时返回到第一页
        .onClick(() => {
          router.back()
        })
      }
      .width('100%')
    }
    .height('100%')
  }

3.预览器查看

四.新建元服务卡片

1.在元服务中新建一张卡片

在"Project"窗口，在"entry"模块目录右键选择"New > Service Widget > Dynamic Widget"，进入卡片模板选择界面，如图2-21所示。

选择"Hello World"卡片模板，点击"Next"，进入卡片配置页面，如图2-22所示。

Service widget name，卡片的名称，在同一个应用/服务中，卡片名称不能重复，且只能包含大小写字母、数字和下划线。

Display name，卡片预览面板上显示的卡片名称。仅API 11 及以上Stage工程支持配置该字段。

Description，卡片的描述信息。

Language，界面开发语言，可选择创建ArkTS/JS卡片。

说明：元服务只支持ArkTS卡片，不支持JS卡片。Support dimension是选择卡片的规格。部分卡片支持同时设置多种规格。首次创建服务卡片时，将默认生成一个EntryCard目录，用于存放卡片快照。Default dimension是在下拉框中可选择默认的卡片。Ability name是选择一个挂靠服务卡片的Form Ability，或者创建一个新的Form Ability。Module name是卡片所属的模块。

卡片配置信息保持默认设置即可，点击"Finish"完成元服务默认卡片的新建。

2.添加效果

在默认卡片的UI页面中添加按钮，并为按钮添加动画效果。

删除"WidgetCard.ets"文件中默认生成的卡片代码，新增代码如下：

@Entry
@Component
struct WidgetCard {
  @State x: number = 1
  @State y: number = 1


  build() {
    Column() {
      Button('Click to enlarge')
        .onClick(() => {
          this.x = 1.1
          this.y = 1.1
        })
        .scale({ x: this.x, y: this.y })
        .animation({
          curve: Curve.EaseOut,
          playMode: PlayMode.AlternateReverse,
          duration: 200,
          onFinish: () => {
            this.x = 1
            this.y = 1
          }
        })
    }
    .padding('10vp')
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

3.卡片动画效果预览

打开WidgetCard.ets文件，单击预览器中的 按钮进行刷新。效果如图2-23所示。

4.进入元服务

实现点击卡片跳转到首页，从而进入元服务。在卡片中增加如下示例代码，实现点击卡片空白处即可进入元服务，代码如下：

@Entry
@Component
struct WidgetCard {
  @State x: number = 1
  @State y: number = 1


  build() {
    Column() {
      Button('Click to enlarge')
        .onClick(() => {
          this.x = 1.1
          this.y = 1.1
        })
        .scale({ x: this.x, y: this.y })
        .animation({
          curve: Curve.EaseOut,
          playMode: PlayMode.AlternateReverse,
          duration: 200,
          onFinish: () => {
            this.x = 1
            this.y = 1
          }
        })
    }
    .padding('10vp')
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .onClick(() => {
      postCardAction(this, {
        "action": 'router',
        "abilityName": 'EntryAbility',
        "params": {
          "message": 'router test'
        }
      });
    })
  }
}

当需要替换元服务卡片的快照图片时，将"EntryCard > entry > base > snapshot > widget-2x2.png"替换成自定义的卡片快照效果如图2-24所示。

五.用模拟器运行应用元服务

1.下载模拟器

2.运行模拟器

3.添加卡片到模拟器

可以通过Ctrl+鼠标再上滑操作即能进入桌面菜单，选择卡片，就能找到刚才创建的元服务的服务卡片了。

预览点击进不了首页，模拟器可以。