鸿蒙应用开发之元服务开发及注意事项

什么是元服务

元服务是HarmonyOS提供的一种轻量应用程序形态，具备免安装，即用即走，账号相随等特征。元服务可独立上架、分发、运行，独立实现业务闭环，可大幅提升信息与服务的获取效率。

元服务与传统应用的对比请见下表。

从应用程序入口看，下图展示了元服务与传统应用、服务卡片之间的关系。对于传统应用和元服务，均可选择服务卡片作为入口。

元服务在开发态和运行态的基本视图如下图所示。

元服务开发流程

元服务的开发流程如下图所示

元服务开发主要包括以下环节。

• 开发前
  • 创建元服务项目前，需要注册华为开发者帐号并在AppGallery Connect创建您的元服务；
  • 然后搭建开发环境，通过DevEco Studio创建元服务工程。
• 开发中
  • 元服务包含页面、卡片、图标三个部分，请分别参考UI开发、服务卡片开发、生成元服务图标。
  • DevEco Studio提供元服务图片生成工具，开发者可以通过上传指定尺寸和格式的图片，快速生成元服务图标。同时，DevEco Studio提供真机调试能力，开发者可快速通过真机运行调试查看运行效果。
• 打包
  • 可通过DevEco Studio快速打包生成发布版本，使用此版本，可以用于开放式测试或提交上架审核。
• 测试
  • 在正式发布元服务前，您可以发布一个开放式测试版本，邀请部分用户提前体验新版本，并收集用户的反馈，以便提前发现问题进行改进，从而保证全网版本的质量，提升用户体验。
• 上架
  • 当元服务经过全面测试，确保版本没有问题，即可发布正式版本。

开发第一个元服务

开发准备

在编写元服务代码之前必须先在 AppGallery Connect 创建元服务应用。具体步骤如下

1. 先登录 App Gallery Connect 创建项目

创建项目时需要填写项目名称，点击“创建并继续”。

2. 给项目添加应用。

3. 一个项目下可以创建多个应用（指的是同一个的不同变体，比如Android应用、HarmonyOS应用、IOS应用等）。

4. 每一个HarmonyOS应用或者元服务都对应一个唯一的APP ID。先去APP ID页面创建应用，并填写应用类型、应用名称、应用分类。

5. 选择应用所属的项目。如果是从项目中添加应用会自动关联此项目，如下图所示。

6. 如果应用需要开放能力，可以选择打开对应的服务开关，如华为账号服务、定位服务、推送服务等。 如果不需要这些开放能力则不必选择。

7. 在APP ID页面看到所有的应用/元服务的APP ID列表

到此元服务开发准备就做完了。接下来，进入DevEco Studio进行元服务的代码开发。

通过DevEco Studio创建元服务工程

1. 选择 New Project 创建新工程

生成元服务图标

元服务图标与应用图标有明显区别，它继承了 HarmonyOS 的设计语言体系，内部圆形表示完整独立，外圈装饰线表示可分可合可流转的特点。

为便于开发者快速生成统一的元服务图标样式，DevEco Studio提供元服务图片生成工具，开发者可以通过上传指定尺寸和格式的图片，快速生成元服务图标。

图标设计规范

开发者在元服务图标生成工具中上传的方形图资源需满足以下要求：

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

开发者在设计图标资源时，需确保主体元素占比适中，避免出现主体元素占比过大，导致图标内容显示不完整；或出现主体元素占比过小，图标展示不够饱满均衡的问题。图标主体元素在图片尺寸中的建议占比为77%。

上传的资源图背景需确保为不透明背景，且资源图尺寸需满足要求。避免出现因尺寸或背景问题导致图标中心圆填充不完全的情况。（注：生成的元服务图标需确保图标中心圆为填充完全的正圆，不可出现其他形态）

请勿使用可能误导用户的文字或图形元素，例如图标中包含新事件标记红点、HOT等元素，误导用户。

元服务图标外圈线请勿使用纯白或纯黑，以避免在纯白/纯黑页面背景上无法清晰辨识其轮廓形态。当中心圆背景为纯白/纯黑时，需给中心圆增加描边，以确保图标中心圆轮廓清晰可见。

若同一开发者名下有多个元服务，建议在图标中增加业务名称标签以区分不同业务。应避免出现多个元服务使用同一元服务图标的情况。

生成元服务图标

为便于开发者快速生成统一的元服务图标样式，DevEco Studio提供元服务图片生成工具，开发者可以通过上传指定尺寸和格式的图片，快速生成元服务图标。

1. 在工程中选中模块或文件，右键单击New > Image Asset，进入图标配置页面，选择满足要求的方形图片。

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

:::info

• Color：推荐使用的图标颜色。选择不同颜色，右边图标预览区域可查看相应的效果。
• Name：生成的图标名称。
• Res Directory：生成的512px*512px尺寸图标在工程中的保存位置。
• Save to：生成的216px*216px尺寸图标需要指定本地文件夹的保存位置。后续在AppGallery Connect上架元服务时，需使用该图标。

:::

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

构建元服务页面

为了快速了解元服务工程目录的构成，并熟悉元服务开发流程，我们将构建一个简单的元服务，包括2个简单页面。

第一个页面

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(()=>{
          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 a 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

      }
    });
  }
}

第二个页面

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(() => {
          router.back()
        })
      }
      .width('100%')
    }
    .height('100%')
  }
}

服务卡片开发

在元服务中新建一张卡片

1. 在“Project”窗口，在“entry”模块目录右键选择“New > Service Widget > Dynamic Widget”，进入卡片模板选择界面，如下图所示：

2. 选择“Hello World”卡片模板，点击“Next”，进入卡片配置页面：

:::info

• 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：卡片所属的模块。

:::

3. 删除“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)
  }
}

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'
        }
      });
    })
  }
}

5. 当需要替换元服务卡片的快照图片时，将“EntryCard > entry > base > snapshot > widget-2x2.png”替换成自定义的卡片快照效果图片：

使用真机运行元服务

1. 将真机与电脑连接。具体指导及要求，请参见运行应用/服务。
2. 选择File > Project Structure… > Project > SigningConfigs界面，勾选“Support HarmonyOS”和“Automatically generate signature”，单击界面提示的“Sign In”，使用华为账号登录。等待自动签名完成后，单击“OK”即可。

:::info
说明

在自动签名的过程中，会校验APP ID和包名的合法性。如出现报错，请及时修改。访客模式无法使用自动签名功能

:::

3. 在编辑窗口右上角的工具栏，单击按钮运行。效果如下图所示：

4. 将元服务的卡片添加到桌面，以便访问元服务。

:::info

• 在桌面上双指捏合，进入桌面的编辑模式。
• 点击底部的“服务卡片”。
• 在卡片添加页面，选择要添加到桌面的卡片，点击“添加到桌面”，完成卡片添加。
• 完成卡片添加后，可以在真机上测试元服务卡片的动效，也可点击卡片空白区域测试拉起元服务页面的功能。

:::

5. 拉起元服务页面进行测试。可以使用Ability助手拉起元服务页面。

hdc shell aa start -a EntryAbility -b 元服务包名

:::info
注意：hdc工具已经集成到HarmonyOS SDK中，需要配置环境变量

• hdc工具通过HarmonyOS SDK获取，存放于SDK的toolchains目录下
• 将 <font style="color:#000000;">/Users/xxxx/Library/OpenHarmony/Sdk/12/toolchains</font> 配置到环境变量下

:::