输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
管理中心
我的
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
开发与测试
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
开发与测试元服务开发元服务指南ASCF框架开发元服务开发和适配指南开放能力打开半屏元服务

打开半屏元服务

更新时间: 2026-10-19 12:43
复制页面
本文导读
展开章节

ASCF框架提供open-embedded-atomicservice组件，允许ASCF框架开发的元服务以半屏形式嵌入式拉起另一个元服务。

注意

嵌入式运行元服务的能力需与被嵌入方建立契约授权。目前处于Beta阶段，如需使用嵌入式能力，请通过邮件（atomicservice@huawei.com）与我们联系以获取授权。

实现的效果如下：

版本限制：

  • ASCF运行时版本1.0.17及以上版本支持，1.0.17以下不提供open-embedded-atomicservice组件。

  • HarmonyOS SDK版本≥5.1.0(18)

拉起方实现

在hxml文件中添加open-embedded-atomicservice组件，实现半屏拉起ASCF框架开发的元服务或ArkTS开发的元服务，注意两者传参格式会有所不同，具体用法见下方示例。

hxml文件：

收起
自动换行
深色代码主题
复制
  1. <view class="container">
  2.   <!-- 示例1：半屏嵌入式拉起ASCF框架开发的元服务 -->
  3.   <open-embedded-atomicservice
  4.     appid="{{ascfAppId}}"
  5.     path="{{ascfPath}}"
  6.     want-param="{{ascfWantParam}}"
  7.     binderror="onError"
  8.     bindterminated="onTerminated">
  9.     <view class="service-trigger">
  10.       <image class="service-icon" src="{{imgSrc}}"/>
  11.       <text class="service-label">demoA</text>
  12.     </view>
  13.   </open-embedded-atomicservice>
  14. 

  15.   <!-- 示例2：半屏嵌入式拉起ArkTS开发的元服务 -->
  16.   <open-embedded-atomicservice
  17.     appid="{{arkTsAppId}}"
  18.     want-param="{{arkTsWantParam}}"
  19.     binderror="onError"
  20.     bindterminated="onTerminated">
  21.     <view class="service-trigger">
  22.       <image class="service-icon" src="{{imgSrc}}"/>
  23.       <text class="service-label">demoB</text>
  24.     </view>
  25.   </open-embedded-atomicservice>
  26. </view>

js文件：

收起
自动换行
深色代码主题
复制
  1. Page({
  2.   data: {
  3.     ascfAppId: 'xxx', // 此处仅为样例，请开发者替换为实际可打开的元服务ID
  4.     ascfPath: 'pages/index/index?launcher=demo', // 此处仅为样例，请开发者替换为实际可打开的目标页面路径
  5.     ascfWantParam: {
  6.       ascfPara: {
  7.         extraData: {
  8.           developerParameters: 'test'
  9.         }
  10.       }
  11.     },
  12. 

  13.     arkTsAppId: 'xxx', // 此处仅为样例，请开发者替换为实际可打开的元服务ID
  14.     arkTsWantParam: {
  15.       developerParameters: 'test'
  16.     },
  17. 

  18.     imgSrc: 'icon.png' // 此处仅为样例，请开发者替换为实际可打开的图片地址
  19.   },
  20. 

  21.   onError(err) {
  22.     // 当被打开的元服务发生运行时异常时触发此回调函数
  23.     const code = err.detail.errCode;
  24.     const message = err.detail.errMsg;
  25.     console.error(`onError, code is ${code}, message is ${message}`);
  26.   },
  27. 

  28.   onTerminated(info) {
  29.     // 当被打开的元服务正常退出时触发此回调函数
  30.     const params = info.detail?.params;
  31.     console.info(`onTerminated, ${params?.resultMessage}`);
  32.   }
  33. });

css文件

收起
自动换行
深色代码主题
复制
  1. .container {
  2.   display: flex;
  3.   justify-content: space-evenly;
  4.   margin-top: 20px;
  5. }
  6. .service-trigger {
  7.   flex-direction: column;
  8.   align-items: center;
  9.   display: flex;
  10. }
  11. .service-icon {
  12.   width: 36px;
  13.   height: 36px;
  14.   margin-bottom: 5px;
  15. }
  16. .service-label {
  17.   font-size: 10px;
  18. }

被拉起方实现

在被拉起的元服务中，可以接收并处理拉起方传递的参数，并在完成操作后退出自身，将结果返回给拉起方。被拉起方可能是基于ASCF框架或ArkTS开发的元服务，二者在参数接收和结果返回的实现方式上有所差异。下方示例分别展示了两种场景下具体实现方法。

接收参数

被拉起方是ASCF框架开发的元服务，可通过以下两种方式获取拉起方传递的参数：

  • path中的查询参数：在目标页面onLoad生命周期的query参数中直接读取（例如路径为page/path/index?launcher=xxx时，query.launcher的值即为"xxx"）。

  • want-param中的结构化数据：通过has.getLaunchOptionsSync获取元服务启动参数，从中提取referrerInfo.extraData字段即为拉起方元服务通过want-param传递的业务数据。

收起
自动换行
深色代码主题
复制
  1. Page({
  2.   onLoad(query) {
  3.     // 1. 获取拉起方 path 属性中携带的 query 参数并打印
  4.     console.info(`Page onLoad, launcher: ${query.launcher}`);
  5.     // 2. 获取拉起方 want-param 属性中传递的结构化参数
  6.     const launchOptions = has.getLaunchOptionsSync(); // 获取元服务启动参数
  7.     if (launchOptions && launchOptions.referrerInfo) {
  8.       const extraData = has.getLaunchOptionsSync().referrerInfo.extraData;
  9.       console.info(`Page onLoad, data from launcher: ${extraData.developerParameters}`);
  10.     }
  11.   }
  12. });

被拉起方是ArkTS开发的元服务，在元服务的UIAbility的onCreate中通过want获取拉起方传给元服务的参数：

收起
自动换行
深色代码主题
复制
  1. export default class AtomicServiceHspAbility extends UIAbility {
  2.   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  3.     console.info(`onCreate, data from launcher: ${want.parameters?.developerParameters}`);
  4.   }
  5. }

退出并返回结果

被拉起方是ASCF框架开发的元服务，通过调用has.terminateSelf接口退出并返回结果给拉起方元服务：

收起
自动换行
深色代码主题
复制
  1. terminateSelf() {
  2.   has.terminateSelf({
  3.     resultCode: 100, // 自定义返回给拉起方元服务的结果码
  4.     params: {
  5.       resultMessage: 'aabb' // 自定义返回给拉起方元服务的信息
  6.     },
  7.     success: () => {
  8.       console.info('terminate success');
  9.     },
  10.     fail: (err) => {
  11.       console.error(`terminate fail, code is ${err.errCode}, message is ${err.errMsg}`);
  12.     },
  13.     complete: () => {
  14.       console.info('terminate complete');
  15.     }
  16.   })
  17. }

被拉起方是ArkTS开发的元服务，通过调用terminateSelfWithResult退出并返回结果给拉起方元服务：

收起
自动换行
深色代码主题
复制
  1. import { common } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   private uiContext = this.getUIContext();
  8.   private context: common.UIAbilityContext = this.uiContext?.getHostContext() as common.UIAbilityContext;
  9.   build() {
  10.     Column() {
  11.       Button('退出并返回数据')
  12.         .onClick(() => {
  13.           const abilityResult: common.AbilityResult = {
  14.             resultCode: 100, // 自定义返回给拉起方元服务的结果码
  15.             want: {
  16.               parameters: {
  17.                 resultMessage: 'aabb' // 自定义返回给拉起方元服务的信息
  18.               }
  19.             }
  20.           };
  21.           try {
  22.             this.context.terminateSelfWithResult(abilityResult)
  23.               .then(() => {
  24.                 console.info('terminateSelfWithResult succeed');
  25.               })
  26.               .catch((err: BusinessError) => {
  27.                 console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
  28.               });
  29.           } catch (err) {
  30.             console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
  31.           }
  32.         })
  33.     }.height('100%').width('100%').justifyContent(FlexAlign.Center)
  34.   }
  35. }

兼容性设计

当宿主机SDK版本低于5.1.0(18)时，open-embedded-atomicservice组件无法使用。为保障功能可用性并避免用户体验中断，可使用has.navigateToAtomicService接口，实现以全屏跳出方式拉起目标元服务。

示例代码：

hxml文件：

收起
自动换行
深色代码主题
复制
  1. <div class="container">
  2.   <div has:if="{{!isEmbeddedSupported}}">
  3.     <button bindtap="navigateToService">手机充值</button>
  4.   </div>
  5.   <div has:else>
  6.     <open-embedded-atomicservice appid="{{appid}}">
  7.       <button>点此跳转</button>
  8.     </open-embedded-atomicservice>
  9.   </div>
  10. </div>

js文件：

收起
自动换行
深色代码主题
复制
  1. Page({
  2.   data: {
  3.     appid: 'xxx', // 此处仅为样例，请开发者替换为实际可打开的元服务ID
  4.     isEmbeddedSupported: false, // 是否支持嵌入式打开
  5.   },
  6. 

  7.   onLoad() {
  8.     const apiVersion = has.getSystemInfoSync().OSApiVersion;
  9.     this.setData({
  10.       isEmbeddedSupported: apiVersion >= 18, // 当API版本大于等于18时支持半屏嵌入式方式打开另一个元服务
  11.     });
  12.     console.info('onLoad -> get API version:', apiVersion);
  13.   },
  14. 

  15.   navigateToService() {
  16.     has.navigateToAtomicService({
  17.       appId: this.data.appid,
  18.       success: () => {
  19.         console.info('Navigation to service successful');
  20.       },
  21.       fail: (res) => {
  22.         console.error('Failed to navigate to service:', res);
  23.       },
  24.       complete: () => {
  25.         console.info('Navigation to service completed');
  26.       }
  27.     })
  28.   }
  29. });

css文件：

收起
自动换行
深色代码主题
复制
  1. .container {
  2.   display: flex;
  3.   flex-direction: column;
  4.   align-items: center;
  5.   padding: 20px;
  6. }

开发者调试

嵌入式运行元服务能力默认是受限的，需要开发者申请权限，才能使用。如果开发者在申请权限之前开发调试阶段想临时开启权限，可以通过打开开发者选项中的“开发中元服务豁免管控”开关来获取调试嵌入式元服务的权限。

说明

开发者选项中的“开发中元服务豁免管控”开关具体放通规格说明：

  • 拉起方应用和被拉起方元服务，至少有一方的签名必须是调试签名，才可以通过打开该开关放通权限管控。

  • 如果拉起方应用需要调试嵌入式运行的元服务已经上架发布，需要先在负一屏手动搜索并下载安装该元服务，再测试嵌入式运行该元服务，目前版本不支持调试阶段嵌入式运行触发元服务免安装。

使用限制

当在open-embedded-atomicservice中使用button作为子组件时，按钮的按压态相关属性（如hover-class、hover-start-time等）将无法正常生效。

隐私托管
ASCF接口兼容性指南
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明