HarmonyOS元服务开发

元服务

1.什么是元服务

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

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

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

2.元服务开发流程

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

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

3. 开发第一个元服务

3.1 开发准备

在编写元服务代码之前必须先在 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进行元服务的代码开发。

3.2 通过DevEco Studio创建元服务工程

1. 选择 New Project 创建新工程
   
   
   
   
   
   

3.3 生成元服务图标

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

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

3.3.1 图标设计规范

开发者在元服务图标生成工具中上传的方形图资源需满足以下要求：
● 图片格式：.png、.jpeg、.jpg格式的静态图片资源
● 图片尺寸：1024 x 1024 px （正方形）
● 图片背景：不透明
● 质量要求：图标内容需清晰可辨，避免存在模糊、锯齿、拉伸等问题。
开发者在设计图标资源时，需确保主体元素占比适中，避免出现主体元素占比过大，导致图标内容显示不完整；或出现主体元素占比过小，图标展示不够饱满均衡的问题。图标主体元素在图片尺寸中的建议占比为77%。

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

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

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

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

3.3.2 生成元服务图标

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

1. 在工程中选中模块或文件，右键单击New > Image Asset，进入图标配置页面，选择满足要求的方形图片。
   
2. 在预览界面可以配置图标颜色、名称、保存路径等。

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

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

3.4 构建元服务页面

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

3.4.1 第一个页面

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 parameterslet loginRequest = new authentication.HuaweiIDProvider().createLoginWithHuaweiIDRequest();// Whether to forcibly launch the HUAWEI ID login page when the user is not logged in with the HUAWEI IDloginRequest.forceLogin = false;// Execute login requestlet 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}});}
}

3.4.2 第二个页面

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

3.5 服务卡片开发

3.5.1 在元服务中新建一张卡片

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

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

4. 实现点击卡片跳转到首页。添加如下代码，实现点击卡片空白处即可进入元服务。

@Entry
@Component
struct WidgetCard {@State x: number = 1@State y: number = 1build() {Column() {Button('Click to enlarge').onClick(() => {this.x = 1.1this.y = 1.1}).scale({ x: this.x, y: this.y }).animation({curve: Curve.EaseOut,playMode: PlayMode.AlternateReverse,duration: 200,onFinish: () => {this.x = 1this.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”替换成自定义的卡片快照效果图片：

3.5.2 使用真机运行元服务

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

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

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

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

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

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

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

注意：hdc工具已经集成到HarmonyOS SDK中，需要配置环境变量
● hdc工具通过HarmonyOS SDK获取，存放于SDK的toolchains目录下
● 将 /Users/xxxx/Library/OpenHarmony/Sdk/12/toolchains 配置到环境变量下