输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS元服务

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
ASCF框架
ASCF框架开发指南HarmonyOS 4及以下版本的元服务适配指南

HarmonyOS 4及以下版本的元服务适配指南

更新时间: 2026-07-17 08:35
本文导读
展开章节
说明

当前适配接入为公测阶段，如有任何问题，请联系atomicservice@huawei.com。

为了扩大您的元服务的用户覆盖范围，给您带来更多的流量，我们计划以快应用中心为容器，将ASCF框架开发的元服务延展至HarmonyOS 4及以下版本中运行。

ASCF框架开发的元服务，结合快应用中心，可实现一套代码、一次开发、一次备案、一次上架，即可覆盖全量华为鸿蒙设备。

注意

总体开发上架流程和HarmonyOS 5.0及以上系统一致。

因为运行的OS和渲染环境不同，HarmonyOS 4及以下OS版本仍存在部分场景需要适配，可通过以下方式进行判断。

  1. 元服务内通过has.canIUse接口或has.getSystemInfo().SDKVersion判断运行环境。
  2. 元服务内HTML页面通过UserAgent判断运行环境。
    • HarmonyOS 5.0 及以上UserAgent举例：Mozilla/5.0 (Phone;HarmonyOS 5.1) AppleWebKit/537.36(KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile ASCF/${appid}
    • Harmony 4 及以下UserAgent举例：Mozilla/5.0 (Linux;**; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/114.0.5735.196 Mobile Safari/537.36 ASCF/${appid} ASCFC/1.0.2.100
    • 上面的appid是您的元服务appid。可通过ASCF/${appid}来判断当前是否是元服务场景，通过HarmonyOS来区分具体的OS运行环境。

运行调试元服务

扫码运行元服务

  1. 申请二维码：

    请您向华为运营人员发送邮件按需申请测试二维码。在收到您的请求后，华为运营人员将在1个工作日内发送测试二维码给到您。

    • 申请邮箱地址：atomicservice@huawei.com。

    • 邮件标题：[测试二维码]-[元服务名称]-[APP ID]，APP ID等查询方法可参见查看应用基本信息。

    • 邮件正文：说明申请二维码的需求，并放在邮件正文。

  2. 使用二维码：

    • 您需要进入应用市场，搜索快应用中心，将此应用升级到最新版本即可。

    • 您需要使用华为手机，打开智慧助手·今天（负一屏），点击右上角“扫一扫”，扫码可直接打开您的元服务。

加载器运行元服务

  • 需使用16.0.1.300以上版本的加载器（下载地址）。

  • 获取元服务的app包，通过加载器加载并运行。

使用ASCF工具链调试运行

请参考使用ASCF命令行工具，连接HarmonyOS 4及以下的版本手机，开发调测元服务。

适配指南

如果您的元服务已上架到HarmonyOS 5.0及以上版本，您希望该元服务同时分发到Harmony 4及以下版本并使用此版本进行测试，选择使用以下其中一种方式运行元服务。

组件/接口适配

元服务在HarmonyOS 5.0及以上的运行环境与HarmonyOS 4及以下版本类似，即逻辑层的JavaScript代码运行在V8中，视图层是基于HarmonyOS原生的ArkWeb引擎来渲染。

运行机制、更新机制、组件框架等均保持一致，但因为不同平台的WebView内核和系统接口不同，在一些特性支持度上会有区别，大多是与组件/接口相关。

开发者可通过has.canIUse接口或者通过has.getDeviceInfo().platform === 'ohos'判断，对业务逻辑做必要的兼容。罗列出暂未支持的特性，对使用到未支持的特性需做好兼容。其中组件/接口具体的支持情况可跳转至对应文档查看。

注意

通过has.getDeviceInfo().platform判断运行平台，满足has.getDeviceInfo().platform === 'ohos'是HarmonyOS 5.0及以上运行环境，否则是HarmonyOS 4及以下运行环境。

容器化差异

元服务提供标准的Deeplink入口，可以实现点击web页面的链接启动元服务。

说明
  • Deeplink链接前后不能有空格。
  • Deeplink链接不能在短信中直接点击唤起元服务。
  • Deeplink跳转不支持失败回调，如果您是在网页中使用，请自己维护fallback，确保在未跳转的情况下，仍然有合适的H5页面为用户提供服务。

安装快应用中心后，即可使用Deeplink。

支持的格式

Deeplink格式：

收起
自动换行
深色代码主题
复制
  1. hap://app/<package>/[path][?key=value]
展开
参数 类型 必填 描述
package string 是 元服务包名
path string 否 元服务内页面的路径，默认为首页。
key-value string 否 需要传给页面的参数，可以有多个。传递的参数值有可能被其他应用获取，建议不要传递安全敏感度较高的数据。

组件/接口的关键差异

组件

展开
组件 HarmonyOS 5.0及以上 HarmonyOS 4及以下 差异说明
input/text-area √ √ HarmonyOS 4及以下input组件、text-area组件输入法拉起后焦点检查，点击输入法右上角收起输入法，输入框仍有焦点。
camera √ √ HarmonyOS 4及以下相机的加载页面为透明色。
map √ √ HarmonyOS 4及以下map组件的定位图标样式、标记点图标样式、缩放图标默认展示、Marker上的label展示有差异。
video √ √ HarmonyOS 4及以下不支持播控中心。
注意

元服务在HarmonyOS 4及以下系统中采用堆叠渲染，使用cover-view/cover-image显示覆盖在原生组件之上的文本/图片视图。可覆盖的原生组件包括map、video、canvas、camera。

接口

在HarmonyOS 4及以下系统中，接口效果跟HarmonyOS 5.0及以上存在差异，详情见下表。针对不支持的接口，开发者需要暂时屏蔽或者采取替代方案。

展开
接口 HarmonyOS 5.0及以上 HarmonyOS 4及以下 差异说明
has.requestContract √ × HarmonyOS 4及以下暂不支持。
has.createThirdPayClient √ × HarmonyOS 4及以下暂不支持。
ThirdPayClient.pay √ × HarmonyOS 4及以下暂不支持。
has.hideShareMenu √ × HarmonyOS 4及以下暂不支持。
has.showShareMenu √ × HarmonyOS 4及以下暂不支持。
has.startRealNameVerification √ × HarmonyOS 4及以下暂不支持。
has.startRealNameAuth √ × HarmonyOS 4及以下暂不支持。
has.startFaceVerification √ √ HarmonyOS 4及以下，依赖华为钱包升级到9.0.46及以上版本。
has.getAvatarInfo √ × HarmonyOS 4及以下暂不支持。
has.getInvoiceTitle √ × HarmonyOS 4及以下暂不支持。
has.getDeliveryAddress √ × HarmonyOS 4及以下暂不支持。
has.getServiceSubscription √ × HarmonyOS 4及以下暂不支持。
has.onLazyLoadError √ × HarmonyOS 4及以下暂不支持。
has.offLazyLoadError √ × HarmonyOS 4及以下暂不支持。
has.chooseAddress √ × HarmonyOS 4及以下暂不支持。
has.chooseInvoiceTitle √ × HarmonyOS 4及以下暂不支持。
has.getPushToken √ × HarmonyOS 4及以下暂不支持。
has.deletePushToken √ × HarmonyOS 4及以下暂不支持。
服务卡片 √ × HarmonyOS 4及以下暂不支持。
has.scanCode √ √ HarmonyOS 4及以下，入参onlyFromCamera设置为true，仍能从相册选择照片。
canvas √ √ HarmonyOS 4及以下画布绘制的线条较粗。
CanvasContext.measureText √ √ HarmonyOS 4及以下width返回值会自动取整数，HarmonyOS 5.0及以上会保留小数。
CanvasContext.globalCompositeOperation √ √ HarmonyOS 4及以下destination-atop，source-in，destination-in绘图有差异。
CanvasContext.setStrokeStyle √ √ HarmonyOS 4及以下参数color传createLinearGradient(x0, y0, x1, y1)，其参数设置为不合法，与HarmonyOS 5.0及以上存在差异。
has.onSocketError / SocketTask.onError √ √ HarmonyOS 4及以下has.onSocketError/SocketTask.onError接口与HarmonyOS 5.0及以上在异常场景下错误码不一致，错误信息是底层网络框架层透传的。
has.request √ √ 由于底层网络框架差异，请求接口成功返回参数profile不一致。
BackgroundAudioManager √ √ HarmonyOS 4及以下播控中心界面展示有差异，不显示进度条、播放进度、音频总时长且音频封面展示在右边。
has.playBackgroundAudio √ √ HarmonyOS 4及以下背景音频播放时，没有控制后台播放的能力。
MapContext.toScreenLocation √ √ 由于依赖的地图SDK在不同平台的差异，获取经纬度对应的屏幕坐标精度不一致。
说明

在调用系统部分能力（如网络、地图，IAP等）部分异常场景下，框架会将底层错误发透传给元服务，存在错误码不一致的情况。

建议开发适配过程中，针对用户场景进行适配。

申请上架、下架

元服务在AG发布上线后，如需分发到系统版本HarmonyOS 4及以下的版本上，可以发送邮件申请，华为运营人员将在 3 个工作日内反馈处理结果。

  • 反馈邮箱地址：atomicservice@huawei.com

  • 邮件标题：[元服务上架/下架申请]-[元服务名称]-[APP ID]，APP ID等查询方法见下方基础信息。

  • 邮件内容：说明需要使用的相关信息。

展开
基础信息 描述
元服务名称 应用市场上架的元服务名称。
APP ID 登录华为开发者联盟，在 "开发与服务" 找到对应项目，"项目设置 > 常规 > 应用 > APP ID" 中获取。

您的元服务分发到系统版本HarmonyOS 4及以下的版本之后，如果您在AG上更新元服务版本，华为运营人员将在1个工作日内处理版本同步，不需要您额外处理。

元服务与卡片共享存储数据
API参考
相关推荐
文档发布元服务
文档ASCF框架概述
文档构建元服务
文档什么是元服务
文档运行调试元服务
文档元服务上架审核预检
文档元服务API说明
文档HarmonyOS 3.x/4.x已接入过华为推送，HarmonyOS Next/5.x及以上版本应用如何升级适配
文档HarmonyOS元服务开发解决方案
文档概述
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 ASCF框架 中进行搜索
请输入您想要搜索的关键词