简体中文
为了丰富鸿蒙生态,为国产操作系统生态做贡献,DCloud 联合华为推出开发者激励计划,uni-app 开发者只需将 uni-app 项目发行为鸿蒙元服务,即可获得现金激励,发行多个元服务可以获得多份现金奖励,欢迎各位开发者积极提交,活动详情
如果你是服务商、外包商,承诺短期可快速上架 20 个元服务,欢迎点此联系我们,我们可提供单独技术支持,以及帮助协调鸿蒙测试机。
从 HBuilderX 4.34
版本开始,uni-app 支持 鸿蒙元服务 平台应用开发。鸿蒙元服务就是鸿蒙 Next 系统上的快应用、小程序。在鸿蒙 Next 系统上,不再支持快应用,对标替换产品即为鸿蒙元服务。
欢迎加入 uni-app 鸿蒙化技术交流群 进行交流。
注意
元服务的开发和上架需要使用元服务的包名 BundleName,包名的形式 com.atomicservice.[你的 APPID]
。
如果还没有创建元服务,访问 华为 AppGallery Connect 完成元服务应用的注册,得到相关包名。方便进行签名证书的操作。
元服务上架需要提前做好备案,强烈建议注册元服务时候立刻开始备案流程,避免临上架才开始备案,耽误上架时间。参考 App 备案相关注意事项.
如果你的元服务需要应到登录、支付权限,也立即开始着手准备申请相关权限,参考 华为支付服务开发准备。
初次运行元服务,需要配置好证书签名、权限设置等信息,第一次参与鸿蒙开发的新手请仔细阅读下面相关建议,否则可能会影响开发元服务。
如果你已有鸿蒙 App 开发经验,元服务的证书签名、权限配置和鸿蒙 App 的相关操作基本一致,参考 证书签名配置指南 。
签名证书分成两类:
接下来文档会面向新手,详细介绍如何使用自动签名证书。发行证书会在文档下方的 发行与上架 部分进行介绍。
建议用户动手使用 DevEco Studio 编辑器创建元服务的原生项目(下面称原生工程),完成相关配置,以保证开发环境配置正确。
打开 DevEco Studio 编辑器,选择 新建工程 - 元服务 AtomService - Empty Ability
,下面的截图来自 DevEco Studio:
选择 已注册好的 AppID,创建鸿蒙元服务示例(下面称原生工程)。
在编辑器的右上角点击Project Structure...
图标,勾选自动签名 Automatically generate signature。
注意:
File - Project Structure...
打开。这个时候点击 Run - Run 'entry'
或者编辑器顶部的小三角选择运行。如果可以运行成功官方的 Hello World 示例,说明相关环境、证书配置完成。
到这里前置工作就准备完成了。因为元服务还在开发迭代,下面补充相关注意事项。
请留意原生工程的两个文件比较特殊,后续 HBuilderX 编译运行需要这些文件:
build-profile.json5
- 证书签名参数等。后续元服务的开发运行、发布上架依赖此文件。entry/src/main/module.json5
- 项目权限配置、metadata 信息配置,元服务设置权限,比如访问网络、位置定位、手机震动等功能依赖此文件。具体的鸿蒙元服务权限列表可以参考 鸿蒙对所有应用开放的权限清单。在 HBuilderX 运行 uni-app 项目到元服务分成四个步骤:
manifest.json
文件build-profile.json5
module.json5
下面进行详细说明。
项目运行需要配置元服务包名,打开项目根目录的 mainefest.json
填写 鸿蒙元服务配置 - 应用包名
,结构类似 com.atomicservice.[你的AppID]
。
build-profile.json5
需要配置签名证书,这里依赖 准备签名证书 部分。项目根目录创建 harmony-mp-configs/build-profile.json5
文件,将上文提到的原生空白项目中的 build-profile.json5
文件内容复制。
在文件中搜索 useNormalizedOHMUrl
将值设置为 false。
注意: 考虑到很多用户不会修改配置,这里提供一个模版,强烈建议新手用户基于 这个模版 修改,只替换签名部分即可。
module.json5
鸿蒙元服务需要获取使用特定的能力,比如元服务登录、震动、获取网络状态等原生提供的能力,需要配置权限模版。
项目根目录创建 harmony-mp-configs/entry/src/main/module.json5
文件。将上文提到的原生空白项目中的 entry/src/main/module.json5
的内容复制填充。HBuilderX 在构建时候会识别替换相关文件。
确保在 module
字段内,存在下面三个字段,如果不存在需要添加,不添加可能会让元服务运行闪退。
请务必注意:这三个字段添加到 module
内部,保证 srcEntry
出现里两次。
"srcEntry": "./ets/abilitystage/AbilityStage.ets", // 此时页面有两个 srcEntry
"metadata": [
{
"name": "appgallery_privacy_hosted",
"value": "1" // 默认开启系统隐私弹窗,建议开启无需编写页面
},
{
"name": "app_id",
"value": "" // 填写实际应用的 app_id 获取方式见下方
},
{
"name": "client_id",
"value": "" // 填写实际应用的 client_id 获取方式见下方
}
],
"dependencies": [
{
"bundleName": "com.huawei.hms.ascf",
"moduleName": "ascf",
"versionCode": 100000
}
]
访问 AGC 后台,选择你的项目,在 项目设置 - 常规 页面中搜索 Client ID,匹配到的结果是下面需要到 client_id
,这个参数会关联当前应用的相关权限,比如位置服务等。
选择 运行 - 运行到小程序模拟器 - 鸿蒙元服务
,在弹出的鸿蒙设置选择框中选择鸿蒙真机。
构建流程完成后,控制台提示:
安装成功
在鸿蒙设备上启动运行 .hap ...
运行成功
同时真机页面更新,即可进行元服务开发和运行。
元服务的条件编译是 MP-HARMONY
。
开发过程中遇到的问题,欢迎加入 uni-app 鸿蒙化技术交流群 进行交流,有官方人员进行答疑和指导。
如果遇到需要 debug 或者白屏问题可以下面方案 进行调试。
元服务上架需要授权 DCloud 作为服务商完成上架,这里介绍如何将元服务上架到鸿蒙应用市场。
注意:目前上架元服务,部分应用信息需要在鸿蒙元服务后台填写,访问 华为 AppGallery Connect 后台,选择 我的元服务,选择对应的元服务 - 编辑。
需要填写 4 处资料:
应用上架 - 应用信息 - 应用分类标签
填写应用分类标签,是为了下一步的内容分级做准备。requestPermissions
字段一致,否则会被驳回。版权信息 - 免责函
选项。填写完点击页面右上角的 保存 按钮,其他没有提到的数据无需填写,这一步骤作用是填写上架所需的特定数据。
在 HBuilderX 中开发 uni-app 上架到鸿蒙元服务需要下面 5 个步骤:
下面进行详细说明。
点击 鸿蒙第三方授权链接 打开下面页面:
第一步:
第二步:
选择你要上架的元服务,授权 DCloud 完成后续的上架流程。
开发调试期间的证书不可用于应用上架。元服务发布证书的申请流程和鸿蒙应用开发类似,访问 鸿蒙发布元服务文档 进行发布证书的获取。
修改 build-profile.json5
里的 release 证书签名。务必注意调试和发行证书是两套,不能混用。
在 HBuilderX 中选择 发行 - 鸿蒙元服务
,进行元服务打包。等待打包完成,会提示上传完成。接下来到 DCloud 开发者中心完善上架资料。
上传成功截图如下:
在上个步骤中,控制台在上传完成之后,提示打开 DCloud 开发者中心。如果你是项目协作者账号登录,请切换为项目作者账号登录。
选择 应用管理 - 我的应用 - 选择项目 APPID
,进入项目详情,选择 各平台信息,打开下面截图的页面,选择 发布 按钮。
表单会默认填写部分元服务信息,请务必确定完成了 上架前置准备 要求内容。填写完成后选择 提交审核 按钮。
下面是用户上架遇到的问题,请 注意:
上架过程中遇到的问题,欢迎加入 uni-app 鸿蒙化技术交流群 进行交流,有官方人员进行答疑和指导。
如果你启动之后展示的是一个黑白界面展示了 Hello Wrold,说明 HBuilderX 提供的默认模版没有被修改,一般是自动化脚本没有成功执行,如果是 Mac 终端请务必注意:屏幕右上角会提示是否允许终端修改文件,一定要允许,才能保证自动化脚本执行成功。
如果你开发过鸿蒙应用,会发现元服务工程和鸿蒙应用开发设置一致,配置文件同样遵循 module.json5 效果优先于 app.json5 ,参考 鸿蒙应用组件配置文档。推荐在组件级别进行配置。
打开 entry/src/main/module.json5
,定位到 module.abilities[0]
会找到下面几个字段:
description
应用描述icon
应用图标label
应用标题startWindowIcon
应用启动图标,SplashscreenstartWindowBackground
应用启动时候屏幕颜色这里的取值一般是 $media:xxx
对应图片索引,$string:xxx
$color:xxx
对应配置文件的值。通过文件配置,在项目 harmony-mp-configs
目录创建 entry/src/main/resources/
目录,并将原生工程相关配置复制过来。注意,zh_CN
大于 base
配置,优先修改 zh_CN 配置。
举例,下面是 zh-CN/element/string.json
中的内容,可以修改 EntryAbility_label
字段。
{
"string": [
{
"name": "module_desc",
"value": "模块描述"
},
{
"name": "EntryAbility_desc",
"value": "description"
},
{
"name": "EntryAbility_label",
"value": "label"
}
]
}
元服务图标必须在华为提供的标准图标底板上设计,参考 生成元服务图标 生成图标,否则会上架审核不通过。最终得到 216x216 的图标放置在 harmony-mp-configs/entry/src/main/resources/base/media/app_icon.png
路径内。
上架时候,这个图标文件也需要在 DCloud 管理后台进行配置。
访问 开发者后台 - 凭证 - 项目级凭证,查询到当前项目的相关信息。
其中 OAth 2.0 客户端 ID 中的凭证名称标识对应的应用、元服务名称,客户端凭证ID
代表 ClientID
,密钥代表 ClientSecret
在解析 code 时候需要。
hvigor ERROR: Invalid storeFile value. Make sure it is not null or empty. The file must be included
如果发生在应用运行、发行阶段。可能是构建时候证书缺少或者配置不对。参考 鸿蒙发布元服务 进行证书申请。
如果是发生应用发行阶段,可能是未填写完整的发布证书,需要调整 build-profile.json5
。
需要主动开启网络访问状态、并且需要设置网络白名单。
开启网络配置。修改 harmony-mp-configs/entry/src/main/module.json5
,在 json 文件的添加,表明需要 INTERNET
权限。
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "$string:app_name",
"usedScene": {
"abilities": ["FromAbility"],
"when": "inuse"
}
}
]
还需要在配置网络访问白名单:
同上,发送网络请求报错的解决方案。
Map 和相关定位需要 华为 AppGallery Connect 后台 进行权限申请。具体可以参考 鸿蒙 Map Kit 开发准备,在 项目设置 - API 管理开启定位服务、位置服务、地图服务。
在 harmony-mp-configs/entry/src/main/module.json5
在 requestPermissions
字段里添加 ohos.permission.LOCATION
和 ohos.permission.APPROXIMATELY_LOCATION
两条记录。
元服务不允许未经用户同意发起定位。在请求位置之前需要获取用户授权。伪代码如下:
uni.authorize({
scope: "scope.userLocation",
success: () => {
uni.getLocation({});
},
fail: () => {
uni.showToast({
title: "未授权获取地理位置权限",
});
},
});
有用户上架驳回理由如下:您的元服务存在自行构造的登录页面,不符合华为应用市场审核标准。修改建议:请使用华为账号静默登录能力,确保用户可以获得完整、体验良好的账号体验。
元服务的登录要求可以参考阅读 《使用华为账号登录 静默登录》、《开发者可以使用自行设计的登录界面吗?》。
如果需要账号登录系统,必须使用 uni.login
登录,不得绕过自行使用账号密码登录。建议申请获取用户手机号权限,然后关联自己的账号系统。在应用在应用合适的时机调用登录接口换取 UnionID,先标识用户为华为用户,操作关键步骤时候接入现有账号,比如获取手机号关联现有账号。
同时务必提供注销用户功能,运行用户自行取消注册,否则会被驳回。
具体技术实现见下个问题。
参考鸿蒙 Account Kit 开发准备 设置相关权限,添加 scope 权限。
易错点: 1. 签名证书不能是自动签名,设置的是 agc 上下载的调试证书 2. mp-configs/entry/src/main/modueljson5
里有个 metadata client_id 确保值正确。 3. AGC 后台配置了指纹,添加了证书。
通过 uni.login
可以得到 code
,流程和其他小程序登录流程相似。参考 解析凭证 得到用户的 UnionID,开发者在这一步骤自行判断是已绑定华为 UnionID,如果未绑定,引导用户绑定现有账号体系。
也可以参考下面手机号接口申请,快速绑定手机号,具体见下个问题。
欢迎使用 uni-id-pages 插件加速元服务开发落地。
申请过手机号敏感权限之后,可以通过 button 获取用户手机号。使用这种方式快速注册、绑定账号体系。
<button open-type="getPhoneNumber" @getphonenumber="getphonenumber">
获取手机号
</button>
getphonenumber(e){
// 获取 code 数值:e.detai.code
console.log(e.detail.code);
}
access_token
access_token
获取用户手机号。需要 GET_NETWORK_INFO
和 vibrate
权限。具体的鸿蒙元服务权限列表可以参考 鸿蒙对所有应用开放的权限清单 进行查询。按照 配置权限模版 章节进行配置。
已修复。动态更新 rich-text
的 nodes
数据时候,内容不会更新。可以临时通过给 rich-text 添加 v-if 控制显隐,在 nextTick 中动态切换生效。
已知问题,等待元服务修复。目前 image
组件不支持本地路径,可临时通过路径字符串展示、或者上传后提供远程 URL 规避。
failed to install bundle. code:9568296 error: install failed due to error bundle type
模拟器或者真机上已经安装了当前 BundleName 的应用。可能是证书复用导致的错误,重新确认当前证书是元服务证书,而不是鸿蒙 App 的证书。
hvigor ERROR: SDK component missing. Please verify the integrity of your SDK.
你可能声明了不兼容的字段,需要在 harmony-mp-configs/build-profile.json5
里面去掉 app.products.*.compileSdkVersion
属性。
一般来说 harmony-mp-configs/entry/src/main/module.json5
配置文件有问题,导致运行失败,需要检查配置文件,如果配置文件没有问题,可以尝试删除文件,重新运行一下。
确保按照 配置 module.json5
章节添加了三个字段,请注意是 module 内部添加,不是和 module 字段平级。
文件 harmony-mp-configs/entry/src/main/module.json5
会用来配置应用的一些应为,你可以参考 鸿蒙 module.json5 配置文件 进行学习和参考。
如果你已经在开发鸿蒙 App ,见到 module.json5 会感觉比较熟悉,有几个属性需要特别注意:
module.installationFree
设置为 truemodule.srcEntry
module.metadata
和 module.dependencies
参考上一条问题。MP-HARMONY
,具体参考 条件编译文档。
Failed to install the HAP or HSP
参考文档顶部 开发环境准备 部分,请确认:
hvigor/hvigor-config.json5
文件,粘贴下面内容。{
"modelVersion": "5.0.0",
"dependencies": {
"@atomicservice/ascf-toolkit-hvigor-plugin": "~1.0.1"
},
"execution": {
// "analyze": "normal", /* Define the build analyze mode. Value: [ "normal" | "advanced" | false ]. Default: "normal" */
// "daemon": true, /* Enable daemon compilation. Value: [ true | false ]. Default: true */
// "incremental": true, /* Enable incremental compilation. Value: [ true | false ]. Default: true */
// "parallel": true, /* Enable parallel compilation. Value: [ true | false ]. Default: true */
// "typeCheck": false, /* Enable typeCheck. Value: [ true | false ]. Default: false */
},
"logging": {
// "level": "info" /* Define the log level. Value: [ "debug" | "info" | "warn" | "error" ]. Default: "info" */
},
"debugging": {
// "stacktrace": false /* Disable stacktrace compilation. Value: [ true | false ]. Default: false */
},
"nodeOptions": {
// "maxOldSpaceSize": 8192 /* Enable nodeOptions maxOldSpaceSize compilation. Unit M. Used for the daemon process. Default: 8192*/
// "exposeGC": true /* Enable to trigger garbage collection explicitly. Default: true*/
}
}
The subpackage path name does not meet the requirements
已修复。参考 运行报错 调整 hvigor 版本号。
Cannot find module '@atomicservice/ascf-toolkit'
已修复。参考 运行报错 调整 hvigor 版本号。
基于 ARM 架构 Mac M1 等系列芯片用户,目前可以申请 ARM 模拟器运行和调试鸿蒙元服务。如需申请,请发送邮件向华为运营人员申请。在收到邮件申请后,华为运营人员将在 1-3 个工作日内为你安排对接人员。
申请方法如下:
atomicservice@huawei.com
[模拟器联调版本申请]-[元服务名称]-[APP ID]-[Developer ID]
,APP ID 等查询方法见下方信息。XXX元服务当前正在进行鸿蒙化开发,由于样机不足等,特申请携带ASCF框架特性直板机模拟器 Mac Arm联调版本,用于XXX。
【使用范围】:开发调试XXX元服务
【版本接收人】:XXXX (接收人邮箱)
【华为账号ID】:XXXX (开发者ID,不是账号名称)
【使用时限】: 2024年X月XX日 - 2024年12月31日 (在结束时间点需要完成版本收编)
我承诺:我清楚该版本是非正式发布版本,可能存在部分问题。如遇到问题,我愿意参与帮助改进。该版本仅用于功能测试和问题联调,受限使用不会扩散,版本会按时收编。
承诺人:XX
日期:202X年X月XX日
注意:如何查询 APP ID 和 Developer ID?
打开 华为 AGC 后台,打开 我的项目 - 选择项目 ,也在页面顶部选择当前的元服务应用。页面中包含 Developer ID 和 APPID (APPID 也就是元服务包名中的数字部分)。
目前华为提供了一个自动化工具,用来自动化处理多个元服务的创建、信息维护和更新操作。详见 元服务工具使用指导
备案类问题参考阅读:APP 备案 FAQ。
补充: Mac 电脑上指纹信息填写 SHA-1 的数值,不要填写 SHA-256。
首先建议缩小问题范围,注释页面相关逻辑,锁定出问题的页面、组件、逻辑,从而针对性的调试。如果希望开启远程调试,可以按照下面方法操作。
阅读官方文档 使用 DevTools 工具调试前端页面
按照文档操作,简单来说可以分成三个步骤:
hdc shell "cat /proc/net/unix | grep devtools"
记录返回数据尾部的数字部分hdc fport tcp:9222 localabstract:webview_devtools_remote_[刚才的数字部分]
返回 OKchrome://inspect/#devices
观察 Remoet Target 进行调试。已知问题,等下修复。观察上传参数里是否有数字类型参数,强转为字符串。
有用户反馈在 Windows 平台下运行 DevEco 原生元服务正常,使用 HBuilderX 运行空白工程会卡主无法完成。发现是个别系统安全工具会默认拦截,拦截发生在 DevEco 调用内置的 node 处理编译时候。提示文案:“有程序正在进行可疑操作,建议阻止”。
目前没有好的方案解决,建议始终信任 DevEco 的操作,或者临时退出安全软件。有相关经验也欢迎交流反馈。
[AppGalleryConnectPublishServicelapp state can not be modified!
当前应用可能已经在审核中