鸿蒙5.0开发进阶：Stage模型-@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)

最新推荐文章于 2025-05-06 22:06:14 发布
原创 最新推荐文章于 2025-05-06 22:06:14 发布 · 757 阅读 · 29 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #前端 #鸿蒙系统 #ArkUI #Stage模型

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)

UIExtensionContentSession是UIExtensionAbility加载界面内容时创建的实例对象，当UIExtensionComponent控件拉起指定的UIExtensionAbility时，UIExtensionAbility会创建UIExtensionContentSession对象，并通过onSessionCreate回调传递给开发者。一个UIExtensionComponent控件对应一个UIExtensionContentSession对象，提供界面加载，结果通知等方法。每个UIExtensionAbility的UIExtensionContentSession之间互不影响，可以各自进行操作。

说明

本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

导入模块

import { UIExtensionContentSession } from '@kit.AbilityKit';

UIExtensionContentSession.loadContent

loadContent(path: string, storage?: LocalStorage): void

为当前UIExtensionComponent控件对应的窗口加载与LocalStorage相关联的具体页面内容。

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
pathstring是设置加载页面的路径。
storageLocalStorage否存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。默认为空。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050Internal error.

示例：

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let storage: LocalStorage = new LocalStorage();
    storage.setOrCreate('session', session);
    session.loadContent('pages/Extension', storage);
  }

  // ...
}

UIExtensionContentSession.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

停止UIExtensionContentSession对应的窗口界面对象。使用callback异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
callbackAsyncCallback<void>是回调函数。当停止UIExtensionContentSession对应的窗口界面对象成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

import { UIExtensionContentSession } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelf')
        .onClick(() => {
          this.session?.terminateSelf((err: BusinessError) => {
            if (err) {
              console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`);
              return;
            }
            console.info(`Successed in terminating self.`);
          });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIExtensionContentSession.terminateSelf

terminateSelf(): Promise<void>

停止UIExtensionContentSession对应的窗口界面对象。使用Promise异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

示例：

import { UIExtensionContentSession } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelf')
        .onClick(() => {
          this.session?.terminateSelf()
            .then(() => {
              console.info(`Successed in terminating self.`);
            })
            .catch((err: BusinessError) => {
              console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`);
            });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIExtensionContentSession.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用callback异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
parameterAbilityResult是返回给UIExtensionComponent控件的信息。
callbackAsyncCallback<void>是回调函数。当停止成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

import { UIExtensionContentSession, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelfWithResult')
        .onClick(() => {
          let abilityResult: common.AbilityResult = {
            resultCode: 0,
            want: {
              bundleName: 'com.ohos.uiextensioncontentsession',
              parameters: {
                'result': 123456
              }
            }
          };

          this.session?.terminateSelfWithResult(abilityResult, (err: BusinessError) => {
            if (err) {
              console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`);
              return;
            }
            console.info(`Successed in terminating self with result.`);
          });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIExtensionContentSession.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用Promise异步回调。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
parameterAbilityResult是返回给UIExtensionComponent控件的信息。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

import { UIExtensionContentSession, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Index {
  private session: UIExtensionContentSession | undefined =
    storage.get<UIExtensionContentSession>('session');

  build() {
    RelativeContainer() {
      Button('TerminateSelfWithResult')
        .onClick(() => {
          let abilityResult: common.AbilityResult = {
            resultCode: 0,
            want: {
              bundleName: 'com.ohos.uiextensioncontentsession',
              parameters: {
                'result': 123456
              }
            }
          };

          this.session?.terminateSelfWithResult(abilityResult)
            .then(() => {
              console.info(`Successed in terminating self with result.`);
            })
            .catch((err: BusinessError) => {
              console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`);
            });

          storage.clear();
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIExtensionContentSession.setWindowPrivacyMode

setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void>

设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用Promise异步回调。

系统能力： SystemCapability.Ability.AbilityRuntime.Core

需要权限： ohos.permission.PRIVACY_WINDOW

参数：

参数名类型必填说明
isPrivacyModeboolean是窗口是否为隐私模式。true表示模式开启；false表示模式关闭。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let isPrivacyMode: boolean = true;
    try {
      session.setWindowPrivacyMode(isPrivacyMode)
        .then(() => {
          console.info(`Successed in setting window to privacy mode.`);
        })
        .catch((err: BusinessError) => {
          console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`);
        });
    } catch (e) {
      let code = (e as BusinessError).code;
      let msg = (e as BusinessError).message;
      console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`);
    }
  }

  // ...
}

UIExtensionContentSession.setWindowPrivacyMode

setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void

设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用callback异步回调。

系统能力： SystemCapability.Ability.AbilityRuntime.Core

需要权限： ohos.permission.PRIVACY_WINDOW

参数：

参数名类型必填说明
isPrivacyModeboolean是窗口是否为隐私模式。true表示模式开启；false表示模式关闭。
callbackAsyncCallback<void>是回调函数。当设置成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let isPrivacyMode: boolean = true;
    try {
      session.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => {
        if (err) {
          console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`);
          return;
        }
        console.info(`Successed in setting window to privacy mode.`);
      });
    } catch (e) {
      let code = (e as BusinessError).code;
      let msg = (e as BusinessError).message;
      console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`);
    }
  }

  // ...
}

UIExtensionContentSession.startAbilityByType11+

startAbilityByType(type: string, wantParam: Record<string, Object>,

abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>): void

通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持处于前台的应用调用。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
typestring是显示拉起的UIExtensionAbility类型。
wantParamRecord<string, Object>是表示扩展参数。
abilityStartCallbackAbilityStartCallback是回调函数，返回启动失败后的详细错误信息。
callbackAsyncCallback<void>是回调函数。当启动Ability成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050Internal error.

示例：


import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
// ...

onSessionCreate(want: Want, session: UIExtensionContentSession): void {
let wantParams: Record<string, Object> = {
'sceneType': 1
};
let abilityStartCallback: common.AbilityStartCallback = {
onError: (code: number, name: string, message: string) => {
console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`);
},
onResult: (result: common.AbilityResult) => {
console.info(`onResult, result: ${JSON.stringify(result)}`);
}
};

session.startAbilityByType('test', wantParams, abilityStartCallback, (err: BusinessError) => {
if (err) {
console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`);
return;
}
console.info(`Successed in startAbilityByType`);
});
}

// ...
}

UIExtensionContentSession.startAbilityByType11+

startAbilityByType(type: string, wantParam: Record<string, Object>,

abilityStartCallback: AbilityStartCallback): Promise<void>

通过type隐式启动UIExtensionAbility。使用Promise异步回调。仅支持处于前台的应用调用。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
typestring是显示拉起的UIExtensionAbility类型。
wantParamRecord<string, Object>是表示扩展参数。
abilityStartCallbackAbilityStartCallback是回调函数，返回启动失败后的详细错误信息。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000050Internal error.

示例：

import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UIExtAbility extends UIExtensionAbility {
  // ...

  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let wantParams: Record<string, Object> = {
      'sceneType': 1
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`);
      },
      onResult: (result: common.AbilityResult) => {
        console.info(`onResult, result: ${JSON.stringify(result)}`);
      }
    };

    session.startAbilityByType('test', wantParams, abilityStartCallback)
      .then(() => {
        console.info(`Successed in startAbilityByType`);
      })
      .catch((err: BusinessError) => {
        console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`);
      });
  }

  // ...
}

UIExtensionContentSession.getUIExtensionWindowProxy12+

getUIExtensionWindowProxy(): uiExtension.WindowProxy

获取UIExtension窗口代理。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

返回值：

类型说明
uiExtension.WindowProxy返回UIExtension的窗口代理。

错误码：

以下错误码详细介绍

错误码ID错误信息
16000050Internal error.

示例：


// Index.ets
import { UIExtensionContentSession } from '@kit.AbilityKit';
import uiExtension from '@ohos.arkui.uiExtension';

let storage = LocalStorage.getShared();

@Entry(storage)
@Component
struct Extension {
@State message: string = 'EmbeddedUIExtensionAbility Index';
private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session');
private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy();

aboutToAppear(): void {
this.extensionWindow?.on('windowSizeChange', (size) => {
console.info(`size = ${JSON.stringify(size)}`);
});
this.extensionWindow?.on('avoidAreaChange', (info) => {
console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`);
});
}

aboutToDisappear(): void {
this.extensionWindow?.off('windowSizeChange');
this.extensionWindow?.off('avoidAreaChange');
}

build() {
Column() {
Text(this.message)
.fontSize(20)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
}

鸿蒙Harmony应用开发—ArkTS声明式开发（容器组件：UIExtensionComponent (系统接口)）
m0_64420071的博客
03-16 2015
ArkTS声明式开发（容器组件：UIExtensionComponent (系统接口)）
鸿蒙NEXT开发：Stage模型能力的接口-@ohos.app.ability.ShareExtensionAbility (分享模板服务扩展能力)
ZPYQAQ的博客
02-25 867
ShareExtensionAbility是为开发者提供分享操作业务模板.............
HarmonyOS实战开发：@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)
2401_84194030的博客
05-14 977
UIExtensionContentSession是UIExtensionAbility加载界面内容时创建的实例对象......
鸿蒙API13开发【@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作】Stage模型能力的接口
鸿蒙的技术博客
11-26 864
UIExtensionContentSession是[UIExtensionAbility]加载界面内容时创建的实例对象，当UIExtensionComponent控件拉起指定的UIExtensionAbility时，UIExtensionAbility会创建UIExtensionContentSession对象，并通过[onSessionCreate])回调传递给开发者。一个UIExtensionComponent控件对应一个UIExtensionContentSession对象，提供界面加载，结果通知等
鸿蒙Ability Kit（程序框架服务）【UIExtensionAbility】
鸿蒙的技术博客
06-04 2300
UIExtensionAbility]是UI类型的ExtensionAbility组件，需要与[UIExtensionComponent]一起配合使用，开发者可以在UIAbility的页面中通过UIExtensionComponent嵌入提供方应用的UIExtensionAbility提供的UI。UIExtensionAbility会在独立于UIAbility的进程中运行，完成其页面的布局和渲染。常用于有进程隔离诉求的系统弹窗、状态栏、胶囊等模块化开发的场景。
鸿蒙API14开发【@ohos.arkui.uiExtension (uiExtension)(系统接口)】应用框架API
最新发布
bbq的博客
05-06 682
用于EmbeddedUIExtensionAbility（或UIExtensionAbility）中获取宿主应用的窗口信息或对应的EmbeddedComponent（或UIExtensionComponent）组件的信息。
鸿蒙NEXT开发：Stage模型能力的接口-@ohos.app.ability.childProcessManager (childProcessManager)
ZPYQAQ的博客
02-23 891
childProcessManager模块提供子进程管理能力，支持子进程启动操作。
鸿蒙NEXT开发：ArkData数据管理-@ohos.data.unifiedDataChannel (标准化数据通路)
ZPYQAQ的博客
03-04 1139
本模块为统一数据管理框架（Unified Data Management Framework,UDMF）的组成部分......
鸿蒙5.0开发：Stage模型（应用上下文Context）
AyomQAQ的博客
10-20 962
应用上下文（Context）是应用程序的全局信息的接口。
鸿蒙5.0开发：Stage模型（UIAbility组件）
AyomQAQ的博客
10-17 2207
UIAbility是HarmonyOS系统中用于构建用户界面的基本组件之一。
GameFramework框架 （五）UI组件
weixin_36961960的博客
06-13 2562
GameFramework框架 UI组件
HarmonyOS Next开发学习手册——ExtensionAbility
maniuT的博客
06-24 1619
EmbeddedUIExtensionAbility需要和 EmbeddedComponent 一起配合使用，开发者可以在UIAbility的页面中通过EmbeddedComponent嵌入本应用的EmbeddedUIExtensionAbility提供的UI。EmbeddedUIExtensionAbility会在独立于UIAbility的进程中运行，完成其页面的布局和渲染。通常用于有进程隔离诉求的模块化开发场景。
鸿蒙API13开发【跨进程应用能力扩展】ArkUI开发
adsjgfjha123123的博客
12-23 780
UIExtension允许开发者创建可以嵌入到其他应用窗口上的界面扩展，使得应用能够提供更加丰富和灵活的用户体验。
【每日学点HarmonyOS Next知识】文本高度问题、长按图标弹出菜单、设置带圆角渐变边框、ArkX问题、进度条动画取消
轻口味的专栏
04-25 448
【每日学点HarmonyOS Next知识】文本高度问题、长按图标弹出菜单、设置带圆角渐变边框、ArkX问题、进度条动画取消
鸿蒙API13开发【WindowExtensionAbility（仅对系统应用开放）】ArkUI开发
adsjgfjha123123的博客
01-07 738
[WindowExtensionAbility]是一种ExtensionAbility组件，用于提供界面组合扩展能力，仅允许系统应用进行跨应用的界面拉起和嵌入。
鸿蒙NEXT（开发进阶）ArkTS异步锁
wea22984984的博客
10-17 796
为了解决多并发实例间的数据竞争问题，ArkTS语言基础库引入了异步锁能力。为了开发者的开发效率，AsyncLock对象支持跨并发实例引用传递。
如何使用命令行对RK开发板进行OpenHarmony版本烧录？
m0_64420071的博客
03-29 2073
开发版烧录
鸿蒙next-实现单例模式
LIUCHANGSHUO的博客
10-31 430
【代码】鸿蒙next-实现单例模式。
鸿蒙 NEXT 开发中，普通对象跨线程如何传递
威哥爱编程，优快云 博客专家、全栈领域新星创作者、华为 HDE，愿交天下 IT 技术爱好者
01-03 853
大家好，我是 V 哥，在鸿蒙HarmonyOS NEXT开发中，跨线程对象传递可以通过拷贝形式实现，确保两个线程的对象内容一致，但各自指向线程的隔离内存区间。以下是使用实现跨线程共享内存的完整案例代码，包括详细解释，整理的学习笔记，分享给大家。关注威哥不迷路，学习鸿蒙就很酷。
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值