!21773 增加UIExtension文档

Merge pull request !21773 from lushi1202/master

zh-cn/application-dev/reference/arkui-ts/Readme-CN.md

@@ -139,6 +139,7 @@
   - [Swiper](ts-container-swiper.md)
   - [Tabs](ts-container-tabs.md)
   - [TabContent](ts-container-tabcontent.md)
+  - [UIExtensionComponent](ts-container-ui-extension-component.md)
   - [WaterFlow](ts-container-waterflow.md)
 - 媒体组件
   - [Video](ts-media-components-video.md)
@@ -189,5 +190,5 @@
 - [类型定义](ts-types.md)
 - 已停止维护的组件
   - [GridContainer](ts-container-gridcontainer.md)
-- 已停止维护的接口 
+- 已停止维护的接口
   - [点击控制](ts-universal-attributes-click.md)

zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md

@@ -272,39 +272,39 @@
 - [ScrollBar](ts-basic-components-scrollbar.md)
 
     滚动条组件，用于配合可滚动组件使用，如List、Grid、Scroll等。
-    
+
 - [Badge](ts-container-badge.md)
 
     可以附加在单个组件上用于信息标记的容器组件。
-    
+
 - [AlphabetIndexer](ts-container-alphabet-indexer.md)
 
     可以与容器组件联动用于按逻辑结构快速定位容器显示区域的索引条组件。
-    
+
 - [Panel](ts-container-panel.md)
 
     可滑动面板，提供一种轻量的内容展示窗口，方便在不同尺寸中切换。
-    
+
 - [Refresh](ts-container-refresh.md)
 
     可以进行页面下拉操作并显示刷新动效的容器组件。
-    
+
 - [AbilityComponent](ts-container-ability-component.md)
 
     独立显示Ability的容器组件。
-    
+
 - [RemoteWindow](ts-basic-components-remotewindow.md)
 
     远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。
-    
+
 - [FormComponent](ts-basic-components-formcomponent.md)
 
     提供卡片组件，实现卡片的显示功能。
-    
+
 - [FormLink](ts-container-formlink.md)
 
     提供静态卡片事件交互功能。
-    
+
 - [Hyperlink](ts-container-hyperlink.md)
 
     超链接组件，组件宽高范围内点击实现跳转。
@@ -312,11 +312,15 @@
 - [Menu](ts-basic-components-menu.md)
 
     以垂直列表形式显示的菜单。
-    
+
 - [MenuItem](ts-basic-components-menuitem.md)
 
     用来展示菜单Menu中具体的item菜单项。
-    
+
 - [MenuItemGroup](ts-basic-components-menuitemgroup.md)
 
     用来展示菜单MenuItem的分组。
+
+- [UIExtensionComponent](ts-container-ui-extension-component.md)
+
+    在页面中嵌入显示带UI界面的Ability扩展的容器组件。

zh-cn/application-dev/reference/arkui-ts/ts-container-ui-extension-component.md

+# UIExtensionComponent
+
+UIExtensionComponent用于支持在本页面内嵌入其他应用提供的UI。展示的内容在另外一个进程中运行，本应用并不参与其中的布局和渲染。
+
+通常用于有进程隔离诉求的模块化开发场景。
+
+> **说明：**
+>
+> 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+>
+> 本组件为系统接口。
+
+## 使用约束
+
+本组件不支持预览。
+
+被拉起的Ability必须是带UI的Ability扩展，如何实现带UI的Ability扩展请参考[实现带UI的Ability扩展](../apis/js-apis-app-ability-uiExtensionAbility.md)。
+
+必须显示设置组件宽高为非0有效值。
+
+## 子组件
+
+无
+
+## 接口
+
+UIExtensionComponent(want: Want)
+
+**参数：**
+
+| 参数名  | 参数类型                                     | 必填   | 参数描述            |
+| ---- | ---------------------------------------- | ---- | --------------- |
+| want | [Want](../apis/js-apis-app-ability-want.md) | 是    | 要加载的Ability。 |
+
+## UIExtensionProxy
+
+用于在双方建立连接成功后，组件使用方向被拉起的Ability发送数据的场景，提供send方法。
+
+### send
+
+send(data: { [key: string]: Object }): void
+
+**参数：**
+| 参数名  | 参数类型                                     | 必填   | 参数描述            |
+| ---- | ---------------------------------------- | ---- | --------------- |
+| data | { [key: string]: Object } | 是    | 发送给被拉起的扩展Ability的数据。 |
+
+## 属性
+
+支持[通用属性](ts-universal-attributes-size.md)。
+
+## 事件
+
+不支持[通用事件](ts-universal-events-click.md)。
+
+将事件经过坐标转换后传递给对端Ability处理。
+
+支持以下事件：
+
+### onRemoteReady
+
+onRemoteReady(callback: [Callback](../apis/js-apis-base.md#callback)\<UIExtensionProxy>)
+
+UIExtensionAbility连接完成时的回调，之后可使用proxy向被拉起的Ability发送数据。
+
+**参数：**
+
+| 参数名                       | 类型   | 说明                                                         |
+| ---------------------------- | ------ | ------------------------------------------------------------ |
+| proxy                        | UIExtensionProxy | 用于向对端Ability发送数据。                          |
+
+### onReceive
+
+onReceive(callback: [Callback](../apis/js-apis-base.md#callback)\<{ [key: string]: Object }>)
+
+收到被拉起的Ability发送的数据时触发的回调。
+
+**参数：**
+
+| 参数名                       | 类型   | 说明                                                         |
+| ---------------------------- | ------ | ------------------------------------------------------------ |
+| data                        | { [key: string]: Object } | 收到来自对端Ability的数据。                 |
+
+### onResult
+
+onResult(callback: [Callback](../apis/js-apis-base.md#callback)\<{code: number; want?: Want}>)
+
+被拉起的Ability扩展调用terminateSelfWithResult时会先触发本回调函数，再触发OnRelease。
+
+本回调内可处理对端Ability的结果数据，可参考[AbilityResult](../apis/js-apis-inner-ability-abilityResult.md)。
+
+| 参数名                       | 类型   | 说明                                                         |
+| ---------------------------- | ------ | ------------------------------------------------------------ |
+| code                        | number | 收到来自对端Ability的处理結果code。                          |
+| want                        | Want | 收到来自对端Ability的处理結果[Want](../apis/js-apis-app-ability-want.md)。 |
+
+### onRelease
+
+onRelease(callback: [Callback](../apis/js-apis-base.md#callback)\<number>)
+
+用于处理被拉起的Ability销毁时的回调。
+
+被拉起的Ability扩展调用terminateSelfWithResult或者terminateSelf时会触发本回调，此时releaseCode为0，即正常销毁。
+
+被拉起的Ability扩展意外Crash或被kill时，触发本回调，此时releaseCode为1，即异常死亡。
+
+| 参数名                       | 类型   | 说明                                                         |
+| ---------------------------- | ------ | ------------------------------------------------------------ |
+| releaseCode                        | number | 对端Ability销毁时的code，0为正常销毁，1为异常销毁。                          |
+
+### onError
+
+onError(callback:[ErrorCallback](../apis/js-apis-base.md#errorcallback))
+
+被拉起的Ability扩展在运行过程中发生异常时触发本回调。可通过回调参数中的code、name和message获取错误信息并做处理。
+
+| 参数名                       | 类型   | 说明                                                         |
+| ---------------------------- | ------ | ------------------------------------------------------------ |
+| err                        | [BusinessError](../apis/js-apis-base.md#businesserror) | 报错信息。    |
+
+## 示例
+
+本示例仅展示组件使用的方法和扩展的Ability，实际运行需在设备中安装bundleName为"com.example.uiextensionprovider"，abilityName为"UIExtensionProvider"的Ability扩展。
+
+```ts
+// 组件使用示例：
+@Entry
+@Component
+struct Index {
+  @State message: string = 'Hello World'
+  private myProxy: UIExtensionProxy
+  build() {
+    Row() {
+      Column() {
+        Text(this.message).fontColor(Color.Red)
+        UIExtensionComponent(
+          {
+            bundleName: "com.example.uiextensionprovider",
+            abilityName: "UIExtensionProvider",
+            parameters: { "x": 12345, "y": "data" }
+          }
+        )
+        .size({ width: "100%", height:"100%" })
+        .onRemoteReady((proxy) => {
+            this.message = "remote ready"
+            this.myProxy = proxy
+        })
+        .onReceive((data) => {
+            this.message = JSON.stringify(data)
+        })
+        .onRelease((releaseCode) => {
+          this.message = "Release: " + releaseCode
+        })
+        .onResult((data) => {
+          this.message = JSON.stringify(data)
+        })
+        .onError((error) => {
+          this.message = "onError: " + error["code"] + ", name: " + error.name + ", message: " + error.message
+        })
+        Button("sendData").onClick(() => {
+          this.myProxy.send({ "x": 5678910 })
+        })
+      }
+      .width("100%")
+    }
+    .height('100%')
+  }
+}
+```
+
+```ts
+// 扩展入口文件UIExtensionProvider.ts
+import UIExtensionAbility from '@ohos.app.ability.UIExtensionAbility'
+const TAG: string = '[UIExtAbility]'
+export default class UIExtAbility extends UIExtensionAbility {
+  onCreate() {
+    console.log(TAG, `UIExtAbility onCreate`)
+  }
+
+  onForeground() {
+    console.log(TAG, `UIExtAbility onForeground`)
+  }
+
+  onBackground() {
+    console.log(TAG, `UIExtAbility onBackground`)
+  }
+
+  onDestroy() {
+    console.log(TAG, `UIExtAbility onDestroy`)
+  }
+
+  onSessionCreate(want, session) {
+    console.log(TAG, `UIExtAbility onSessionCreate, want: ${JSON.stringify(want)}`)
+    let storage: LocalStorage = new LocalStorage({
+      'session': session
+    });
+    session.loadContent('pages/extension', storage);
+  }
+
+  onSessionDestroy(session) {
+    console.log(TAG, `UIExtAbility onSessionDestroy`)
+  }
+}
+```
+
+```ts
+// 扩展Ability入口页面文件extension.ets
+import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession'
+let storage = LocalStorage.GetShared()
+@Entry(storage)
+@Component
+struct Index {
+  @State message: string = 'UIExtension'
+  @State message2:string = 'message from comp'
+  private session: UIExtensionContentSession = storage.get<UIExtensionContentSession>('session');
+  controller: TextInputController = new TextInputController()
+  onPageShow() {
+    this.session.setReceiveDataCallback((data)=> {
+      this.message2 = "data come from comp"
+      this.message = JSON.stringify(data)
+    })
+  }
+  build() {
+    Row() {
+      Column() {
+        Text(this.message2)
+        Text(this.message)
+        Button("sendData")
+          .onClick(()=>{
+            this.session.sendData({"xxx": "data from extension"})
+          })
+        Button("terminateSelf")
+          .onClick(()=>{
+            this.session.terminateSelf();
+            storage.clear();
+          }).margin(5)
+        Button("TerminateSelfWithResult")
+          .onClick(()=>{
+            this.session.terminateSelfWithResult({
+              "resultCode": 0,
+              "want": {
+                "bundleName": "myName"
+              }
+            });
+            storage.clear();
+          }).margin(5)
+      }
+      .width('100%')
+    }
+    .height('100%')
+  }
+}
+```