应用拉起元服务

更新时间: 2026-07-30 00:55

本文导读

问题现象

应用如何拉起开发者自身或三方开发的元服务？

背景知识

元服务是HarmonyOS提供的一种轻量应用程序形态，具备秒开直达，纯净清爽；服务相伴，恰合时宜；即用即走，账号相随；一体两面，嵌入运行；AI智能，全域流转；高效开发，生而可信等特征。
关联主体，也称关联实体，指与开发者具有关联关系的自然人、法人或组织。开发者可以将与HarmonyOS开放平台账号主体具有关联关系的主体申请绑定为关联主体。企业开发者可创建关联主体账号组，关联主体账号组内的成员可享受该账号组内专享的跳转互通政策。

解决方案

不建议使用下面的方式打开元服务：

展开

拉起方式	原因
通过FunctionalButton拉起元服务。	FunctionalButton组件打开元服务需要获取未开放的信息，增加开发成本。
通过startAbility/startAbilityForResult拉起元服务。	使用该接口打开元服务需要获取未开放的信息，增加开发成本。

方案一：使用FullScreenLaunchComponent拉起元服务。

FullScreenLaunchComponent允许开发者以全屏方式拉起元服务，使得应用能够提供更友好的用户体验。当被拉起方授权使用方应用嵌入式运行元服务时，使用方应用可全屏嵌入式运行该服务。若未授权，则使用方应用将以跳出式方式拉起元服务。

收起
自动换行
深色代码主题
复制
@Component
struct ByFullScreenLaunch {
  @Builder
  PhoneRechargeChild() {
    Column() {
      Button('ByFullScreenLaunch')
        .fontSize(16)
        .width(200)
    };
  }

  build() {
    Column() {
      FullScreenLaunchComponent({
        content: this.PhoneRechargeChild,
        appId: '****', // 请替换为待拉起元服务的真实appId
        options: {},
      });
    };
  }
}

方案二：使用openAtomicService拉起元服务。

openAtomicService打开一个独立窗口的元服务，并返回结果。使用Promise异步回调。仅支持在主线程调用。对于关联主体，首次跳转弹窗，后续直接跳转，非关联主体则每次跳转弹窗。

收起
自动换行
深色代码主题
复制
@Component
struct ByOpenAtomicService {
  build() {
    Column() {
      Button('ByOpenAtomicService')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let appId: string = '****'; // 请替换为待拉起元服务的真实appId
          let options: AtomicServiceOptions = {
            flags: wantConstant.Flags.FLAG_INSTALL_ON_DEMAND
          };
          try {
            context.openAtomicService(appId, options)
              .then((result: common.AbilityResult) => {
                // 执行正常业务
                console.info(`openAtomicService succeed, resultCode: ${result.resultCode}`);
              })
              .catch((err: BusinessError) => {
                // 处理业务逻辑错误
                console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
              });
          } catch (err) {
            // 处理入参错误异常
            let code = (err as BusinessError).code;
            let message = (err as BusinessError).message;
            console.error(`openAtomicService failed, code is ${code}, message is ${message}`);
          }
        });
    };
  }
}

方案三：使用openLink拉起元服务。

openLink接口实现以App Linking方式拉起元服务，开发者可根据业务需求进行编译。若有匹配的元服务，则直接打开目标元服务；否则，抛异常给开发者进行处理。

收起
自动换行
深色代码主题
复制
@Component
struct ByOpenLink {
  build() {
    Column() {
      Button('ByOpenLink')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          // 请替换成真实元服务链接
          let link: string = '****';
          context.openLink(link)
            .then(() => {
              // 执行正常业务
              console.info('openAtomicService succeed');
            })
            .catch((err: BusinessError) => {
              // 处理业务逻辑错误
              console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
            });
        });
    };
  }
}

方案四：使用FunctionalButton拉起元服务。

FunctionalButton组件，为开发者提供场景化开发能力，支持打开元服务。对于关联主体，首次跳转弹窗，后续直接跳转，非关联主体则每次跳转弹窗。

收起
自动换行
深色代码主题
复制
@Component
struct ByFunctionalButton {
  build() {
    Column() {
      FunctionalButton({
        params: {
          openType: functionalButtonComponentManager.OpenType.LAUNCH_APP,
          label: 'ByFunctionalButton',

          appParam: {
            bundleName: '****', // 请替换为待拉起元服务真实bundleName
            abilityName: '****', // 请替换为待拉起元服务真实abilityName
          },
          styleOption: {
            styleConfig: new functionalButtonComponentManager.ButtonConfig()
              .fontSize(16)
              .width(200)
          },
        },
        controller: new functionalButtonComponentManager.FunctionalButtonController().onLaunchApp((err) => {
          if (err) {
            // 异常处理
            return;
          }
        })
      });
    };
  }
}

方案五：使用startAbility/startAbilityForResult拉起元服务。

startAbility/startAbilityForResult拉起元服务。

收起
自动换行
深色代码主题
复制
@Component
struct ByStartAbility {
  build() {
    Column() {
      Button('ByStartAbility')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let want: Want = {
            bundleName: '****', // 请替换为待拉起元服务真实bundleName
            abilityName: '****', // 请替换为待拉起元服务真实abilityName
          };

          try {
            context.startAbility(want, (err: BusinessError) => {
              if (err.code) {
                // 处理业务逻辑错误
                console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
                return;
              }
              // 执行正常业务
              console.info('startAbility succeed');
            });
          } catch (err) {
            // 处理入参错误异常
            let code = (err as BusinessError).code;
            let message = (err as BusinessError).message;
            console.error(`startAbility failed, code is ${code}, message is ${message}`);
          }
        });
    };
  }
}

方案六：使用HalfScreenLaunchComponent组件半屏嵌入式启动元服务组件，当被拉起方未授权嵌入式运行元服务时，宿主将使用跳出式拉起元服务。

收起
自动换行
深色代码主题
复制
@Component
struct ByHalfScreenLaunch {
  build() {
    Column() {
      HalfScreenLaunchComponent({
        appId: '****', // 请替换为待拉起元服务的真实appId
        options: {},
        onTerminated: (info: TerminationInfo) => {
          console.info('onTerminated info = ' + info.want);
        },
        onError: (err) => {
          console.error(' onError code: ' + err.code + ', message: ', err.message);
        },
      }) {
        Column() {
          Button('ByHalfScreenLaunch')
            .fontSize(16)
            .width(200)
        };
      };
    };
  }
}

完整示例参考如下：

收起
自动换行
深色代码主题
复制
import { FullScreenLaunchComponent, HalfScreenLaunchComponent } from '@kit.ArkUI';
import { AtomicServiceOptions, common, Want, wantConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { FunctionalButton, functionalButtonComponentManager } from '@kit.ScenarioFusionKit';

@Entry
@Component
struct AppLaunchAtomicService {
  build() {
    Navigation() {
      Column({ space: 40 }) {
        ByFullScreenLaunch();
        ByOpenAtomicService();
        ByOpenLink();
        ByFunctionalButton();
        ByStartAbility();
        ByHalfScreenLaunch();
      }
      .height('100%')
      .width('100%')
      .justifyContent(FlexAlign.Center);
    }
    .title('应用拉起元服务')
    .hideBackButton(true)
    .titleMode(NavigationTitleMode.Mini)
    .mode(NavigationMode.Stack);
  }
}

@Component
struct ByFullScreenLaunch {
  @Builder
  PhoneRechargeChild() {
    Column() {
      Button('ByFullScreenLaunch')
        .fontSize(16)
        .width(200)
    };
  }

  build() {
    Column() {
      FullScreenLaunchComponent({
        content: this.PhoneRechargeChild,
        appId: '****', // 请替换为待拉起元服务的真实appId
        options: {},
      });
    };
  }
}

@Component
struct ByOpenAtomicService {
  build() {
    Column() {
      Button('ByOpenAtomicService')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let appId: string = '****'; // 请替换为待拉起元服务的真实appId
          let options: AtomicServiceOptions = {
            flags: wantConstant.Flags.FLAG_INSTALL_ON_DEMAND
          };
          try {
            context.openAtomicService(appId, options)
              .then((result: common.AbilityResult) => {
                // 执行正常业务
                console.info(`openAtomicService succeed, resultCode: ${result.resultCode}`);
              })
              .catch((err: BusinessError) => {
                // 处理业务逻辑错误
                console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
              });
          } catch (err) {
            // 处理入参错误异常
            let code = (err as BusinessError).code;
            let message = (err as BusinessError).message;
            console.error(`openAtomicService failed, code is ${code}, message is ${message}`);
          }
        });
    };
  }
}

@Component
struct ByOpenLink {
  build() {
    Column() {
      Button('ByOpenLink')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          // 请替换成真实元服务链接
          let link: string = '****';
          context.openLink(link)
            .then(() => {
              // 执行正常业务
              console.info('openAtomicService succeed');
            })
            .catch((err: BusinessError) => {
              // 处理业务逻辑错误
              console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
            });
        });
    };
  }
}

@Component
struct ByFunctionalButton {
  build() {
    Column() {
      FunctionalButton({
        params: {
          openType: functionalButtonComponentManager.OpenType.LAUNCH_APP,
          label: 'ByFunctionalButton',

          appParam: {
            bundleName: '****', // 请替换为待拉起元服务真实bundleName
            abilityName: '****', // 请替换为待拉起元服务真实abilityName
          },
          styleOption: {
            styleConfig: new functionalButtonComponentManager.ButtonConfig()
              .fontSize(16)
              .width(200)
          },
        },
        controller: new functionalButtonComponentManager.FunctionalButtonController().onLaunchApp((err) => {
          if (err) {
            // 异常处理
            return;
          }
        })
      });
    };
  }
}

@Component
struct ByStartAbility {
  build() {
    Column() {
      Button('ByStartAbility')
        .fontSize(16)
        .width(200)
        .onClick(() => {
          let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let want: Want = {
            bundleName: '****', // 请替换为待拉起元服务真实bundleName
            abilityName: '****', // 请替换为待拉起元服务真实abilityName
          };

          try {
            context.startAbility(want, (err: BusinessError) => {
              if (err.code) {
                // 处理业务逻辑错误
                console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
                return;
              }
              // 执行正常业务
              console.info('startAbility succeed');
            });
          } catch (err) {
            // 处理入参错误异常
            let code = (err as BusinessError).code;
            let message = (err as BusinessError).message;
            console.error(`startAbility failed, code is ${code}, message is ${message}`);
          }
        });
    };
  }
}

@Component
struct ByHalfScreenLaunch {
  build() {
    Column() {
      HalfScreenLaunchComponent({
        appId: '****', // 请替换为待拉起元服务的真实appId
        options: {},
        onTerminated: (info: TerminationInfo) => {
          console.info('onTerminated info = ' + info.want);
        },
        onError: (err) => {
          console.error(' onError code: ' + err.code + ', message: ', err.message);
        },
      }) {
        Column() {
          Button('ByHalfScreenLaunch')
            .fontSize(16)
            .width(200)
        };
      };
    };
  }
}

常见FAQ

Q：全屏嵌入式和跳出式运行元服务区别是什么？

A：全屏嵌入式运行元服务是指，通过UIExtensionComponent的组件方式嵌入到使用方的组件树中，拉起EmbeddableUIAbility，展示提供方的应用内容。能够实现组件式的交互体验。跳出式运行元服务是指，非组件化的方式拉起EmbeddableUIAbility，交互体验接近独立窗口。

Q：元服务是否支持跳转应用？

A：如果被拉起方是非关联主体的三方应用，则无法拉起。如果被拉起方是关联主体账号组的三方应用，则可以拉起。详情请参考跳转规则说明。

服务卡片加载图片不显示

已开启元服务豁免管控，AtomicServiceWeb加载网页失败

意见反馈

以上内容对您是否有帮助？

意见反馈

如果您有其他疑问，您也可以通过开发者社区问答频道来和我们联系探讨。

社区提问智能客服提问