1# IsolatedComponent (System API) 2 3**IsolatedComponent** is designed to support the embedding and display of UIs provided by independent .abc files within the current page, with the displayed content running in a restricted Worker thread. 4 5The **FolderStack** component is usually used in modular development scenarios where .abc file hot update is required. 6 7> **NOTE** 8> 9> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 10> 11> The APIs provided by this module are system APIs. 12 13## Constraints 14 15**Specifications Constraints** 16 171. This component does not support preview. 18 192. The .abc file must pass the [VerifyAbc](../../apis-ability-kit/js-apis-bundleManager-sys.md#bundlemanagerverifyabc11) verification before use. 20 213. Constructor parameter updates are not supported; only the initial input is effective. 22 234. Nesting of **IsolatedComponent** components is not supported. 24 25**Experience Constraints** 26 271. When an **IsolatedComponent** component is created, there is a certain amount of time required for the restricted Worker thread to load and render the .abc file layout. During this period, the background color of the **IsolatedComponent** is displayed. 28 292. The main thread and the restricted Worker thread handle layout rendering asynchronously, which can lead to desynchronization in page changes caused by layout alterations or rotations. 30 313. Event passing between the main thread and the restricted Worker thread is managed asynchronously, and there is no support for event bubbling between threads. As a result, UI interactions between threads may encounter event conflicts. 32 33**Security Constraints** 34 351. Displaying an independent .abc file through the **IsolatedComponent** component in the host process means that the .abc file content is fully accessible to the host, granting the host the control over the file content. For security-sensitive situations where such open access could be a risk, the use of this feature is disabled. 36 372. Running independent .abc files in a restricted Worker thread offers a level of security, as the .abc file content is isolated and does not interfere with the main thread. 38 39## Child Components 40 41Not supported 42 43## APIs 44 45IsolatedComponent(options: IsolatedOptions) 46 47Creates an **IsolatedComponent** component to display the .abc file executed in a restricted Worker thread. 48 49**System API**: This is a system API. 50 51**System capability**: SystemCapability.ArkUI.ArkUI.Full 52 53**Parameters** 54 55| Name | Type | Mandatory| Description | 56| --------------------- | ---------------------------------------------------------- | ---- | ------------------ | 57| options | [IsolatedOptions](#isolatedoptions) | Yes | Construction parameters.| 58 59## IsolatedOptions 60 61Describes the optional construction parameters during **IsolatedComponent** construction. 62 63**System API**: This is a system API. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67| Name | Type | Mandatory| Description | 68| ---- | ---------------------------------------- | ---- | --------------- | 69| want | [Want](../../apis-ability-kit/js-apis-app-ability-want.md) | Yes | .abc file information to load.| 70| worker | [RestrictedWorker](../../apis-arkts/js-apis-worker-sys.md#restrictedworker11) | Yes | Restricted Worker thread where the .abc file is running.| 71 72## Attributes 73Only the [width](ts-universal-attributes-size.md#width), [height](ts-universal-attributes-size.md#height), and [backgroundColor](ts-universal-attributes-background.md#backgroundcolor) universal attributes are supported. 74 75## Events 76 77The [universal events](ts-component-general-events.md) are not supported. 78 79Events are asynchronously passed to the restricted Worker thread after coordinate conversion. 80 81The following events are supported: 82 83### onError 84 85onError(callback:ErrorCallback) 86 87Invoked when an error occurs during the running of the **IsolatedComponent**. You can obtain the error information based on the **code**, **name**, and **message** parameters in the callback and rectify the exception accordingly. 88 89**System API**: This is a system API. 90 91**System capability**: SystemCapability.ArkUI.ArkUI.Full 92 93**Parameters** 94 95| Name | Type | Mandatory| Description | 96| --------------------- | ---------------------------------------------------------- | ---- | ------------------ | 97| callback | [ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes | Error information.| 98 99## Example: Loading an IsolatedComponent 100 101This example demonstrates the basic usage of the **IsolatedComponent** component. The sample application's **bundleName** is **"com.example.isolateddemo"**, and the component uses the .abc file and an extension page from the same application as the embedded content. The specific testing steps after building the application project are as follows: 1021. Build the HAP in DevEco Studio and install it on the device. 1032. Upload the generated **modules.abc** file to the application sandbox path** /data/app/el2/100/base/com.example.isolateddemo/haps/entry/files** using DevEco Studio or the [hdc](../../../dfx/hdc.md) tool. 1043. Open the application page and click the **verifyAbc** button to verify the .abc file, which logs "VerifyAbc successfully." 1054. Click the **showIsolatedComponent** button to display the **IsolatedComponent** with the content "Hello World." 106 107- Restricted Worker thread script **ets/workers/OhCardWorker.ets**: 108 ```ts 109 // OhCardWorker.ets 110 import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 111 const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 112 113 workerPort.onmessage = (e: MessageEvents) => {} 114 workerPort.onmessageerror = (e: MessageEvents) => {} 115 workerPort.onerror = (e: ErrorEvent) => {} 116 ``` 117 118- Home page (**ets/pages/Index.ets**) loaded by the entry ability (**EntryAbility**): 119 ```ts 120 import { worker } from '@kit.ArkTS'; 121 import { bundleManager, common } from '@kit.AbilityKit'; 122 import { BusinessError } from '@kit.BasicServicesKit'; 123 124 // Verify the .abc file and copy it to the specified sandbox path. 125 function VerifyAbc(abcPaths: Array<string>, deleteOriginalFiles: boolean) { 126 try { 127 bundleManager.verifyAbc(abcPaths, deleteOriginalFiles, (err) => { 128 if (err) { 129 console.error("VerifyAbc failed, error message: " + err.message); 130 } else { 131 console.info("VerifyAbc successfully."); 132 } 133 }); 134 } catch (err) { 135 let message = (err as BusinessError).message; 136 console.error("VerifyAbc failed, error message: " + message); 137 } 138 } 139 140 @Entry 141 @Component 142 struct Index { 143 @State isShow: boolean = false; 144 @State resourcePath: string = ""; 145 @State abcPath: string = ""; 146 @State entryPoint: string = ""; 147 @State context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 148 // .abc file name 149 private fileName: string = "modules"; 150 // Bundle name of the application to which the .abc file belongs 151 private bundleName: string = "com.example.isolateddemo"; 152 // Restricted Worker thread 153 private worker ?: worker.RestrictedWorker = new worker.RestrictedWorker("entry/ets/workers/OhCardWorker.ets"); 154 155 build() { 156 Row() { 157 Column() { 158 // 1. Verify the .abc file. 159 Button("verifyAbc").onClick(() => { 160 let abcFilePath = `${this.context.filesDir}/${this.fileName}.abc`; 161 console.info("abcFilePath: " + abcFilePath); 162 VerifyAbc([abcFilePath], false); 163 }).height(100).width(100) 164 165 // 2. Display the IsolatedComponent. 166 Button("showIsolatedComponent").onClick(() => { 167 if (!this.isShow) { 168 // Resource path 169 this.resourcePath = `${this.context.filesDir}/${this.fileName}.hap`; 170 // Sandbox path after the .abc file is verified 171 this.abcPath = `/abcs${this.context.filesDir}/${this.fileName}`; 172 // Entry to the page to be displayed 173 this.entryPoint = `${this.bundleName}/entry/ets/pages/extension`; 174 this.isShow = true; 175 } 176 }).height(100).width(100) 177 178 if (this.isShow) { 179 IsolatedComponent({ 180 want: { 181 "parameters": { 182 "resourcePath": this.resourcePath, 183 "abcPath": this.abcPath, 184 "entryPoint": this.entryPoint 185 } 186 }, 187 worker: this.worker 188 }) 189 .width(300) 190 .height(300) 191 .onError((err) => { 192 console.error("onError : " + JSON.stringify(err)); 193 }) 194 } 195 } 196 .width('100%') 197 } 198 .height('100%') 199 } 200 } 201 ``` 202 203- The entry page file **ets/pages/extension.ets**, which runs in a restricted Worker thread, needs to be configured in the **resources/base/profile/main_pages.json** file with the following content: 204 ```ts 205 @Entry 206 @Component 207 struct Extension { 208 @State message: string = 'Hello World'; 209 210 build() { 211 RelativeContainer() { 212 Text(this.message) 213 .id('HelloWorld') 214 .fontSize(50) 215 .fontWeight(FontWeight.Bold) 216 .alignRules({ 217 center: { anchor: '__container__', align: VerticalAlign.Center }, 218 middle: { anchor: '__container__', align: HorizontalAlign.Center } 219 }) 220 } 221 .height('100%') 222 .width('100%') 223 } 224 } 225 ``` 226 227- Add the **requestPermissions** tag in the **module.json5** configuration file to allow the execution of dynamically distributed Ark bytecode in restricted mode: 228 ```json 229 "requestPermissions": [ 230 { 231 "name": "ohos.permission.RUN_DYN_CODE", 232 "usedScene": { 233 "abilities": [ 234 "EntryAbility" 235 ], 236 "when": "inuse" 237 } 238 } 239 ] 240 ``` 241