1# @ohos.arkui.UIContext (UIContext)(系统接口) 2 3在Stage模型中，WindowStage/Window可以通过loadContent接口加载页面并创建UI的实例，并将页面内容渲染到关联的窗口中，所以UI实例和窗口是一一关联的。一些全局的UI接口是和具体UI实例的执行上下文相关的，在当前接口调用时，通过追溯调用链跟踪到UI的上下文，来确定具体的UI实例。若在非UI页面中或者一些异步回调中调用这类接口，可能无法跟踪到当前UI的上下文，导致接口执行失败。 4 5@ohos.window在API version 10 新增[getUIContext](./js-apis-window.md#getuicontext10)接口，获取UI上下文实例UIContext对象，使用UIContext对象提供的替代方法，可以直接作用在对应的UI实例上。 6 7> **说明：** 8> 9> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10> 11> 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。 12> 13> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.arkui.UIContext (UIContext)](js-apis-arkui-UIContext.md)。 14 15## UIContext 16 17以下API需先使用ohos.window中的[getUIContext()](./js-apis-window.md#getuicontext10)方法获取UIContext实例，再通过此实例调用对应方法。本文中UIContext对象以uiContext表示。 18 19### setDynamicDimming<sup>12+<sup> 20 21setDynamicDimming(id: string, value: number): void 22 23通过该方法设置组件的压暗程度。 24 25 26> **说明：** 27> 28> 设置该属性后设置其他效果类属性会导致效果冲突。 29 30**系统能力：** SystemCapability.ArkUI.ArkUI.Full 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| ------- | ------- | ------- | ------- | 36| id | string | 是 | 组件id。 | 37| value | number | 是 | 组件压暗程度取值范围[0,1], 由0到1逐渐变亮。 | 38 39**示例：** 40 41```ts 42@Entry 43@Component 44struct Index { 45 @State 46 myCount : number = 100 47 48 build() { 49 Column(){ 50 Image($r('app.media.testImage')).width(500).height(800).id("test") 51 }.width("100%").height("100%").onClick(()=>{ 52 this.getUIContext().setDynamicDimming("test",1) 53 this.getUIContext()?.animateTo({duration:5000 },()=>{ 54 this.getUIContext().setDynamicDimming("test",0) 55 }) 56 }) 57 } 58} 59``` 60 61 62### animateToImmediately<sup>12+</sup> 63 64animateToImmediately(param: AnimateParam , event: () => void): void 65 66animateToImmediately接口允许用户通过UIContext对象，获取显式立即动画的能力。同时加载多个属性动画的情况下，使用该接口可以立即执行闭包代码中状态变化导致的过渡动效。 67 68**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ----- | ---------------------------------------- | ---- | ------------------------------------- | 76| param | [AnimateParam](arkui-ts/ts-explicit-animation.md#animateparam对象说明) | 是 | 设置动画效果相关参数。 | 77| event | () => void | 是 | 指定显示动效的闭包函数，在闭包函数中导致的状态变化系统会自动插入过渡动画。 | 78 79**示例：** 80 81该示例实现了通过UIContext对象获取显式立即动画的能力，调用animateToImmediately接口实现参数定义的动画效果。 82 83```ts 84// xxx.ets 85@Entry 86@Component 87struct AnimateToImmediatelyExample { 88 @State widthSize: number = 250 89 @State heightSize: number = 100 90 @State opacitySize: number = 0 91 private flag: boolean = true 92 uiContext: UIContext | null | undefined = this.getUIContext(); 93 94 build() { 95 Column() { 96 Column() 97 .width(this.widthSize) 98 .height(this.heightSize) 99 .backgroundColor(Color.Green) 100 .opacity(this.opacitySize) 101 Button('change size') 102 .margin(30) 103 .onClick(() => { 104 if (this.flag) { 105 this.uiContext?.animateToImmediately({ 106 delay: 0, 107 duration: 1000 108 }, () => { 109 this.opacitySize = 1 110 }) 111 this.uiContext?.animateTo({ 112 delay: 1000, 113 duration: 1000 114 }, () => { 115 this.widthSize = 150 116 this.heightSize = 60 117 }) 118 } else { 119 this.uiContext?.animateToImmediately({ 120 delay: 0, 121 duration: 1000 122 }, () => { 123 this.widthSize = 250 124 this.heightSize = 100 125 }) 126 this.uiContext?.animateTo({ 127 delay: 1000, 128 duration: 1000 129 }, () => { 130 this.opacitySize = 0 131 }) 132 } 133 this.flag = !this.flag 134 }) 135 }.width('100%').margin({ top: 5 }) 136 } 137} 138``` 139 140 141### freezeUINode<sup>18+</sup> 142 143freezeUINode(id: string, isFrozen: boolean): void 144 145使用id设置组件冻结状态，防止自身脏区标记并进行布局更新。 146 147**原子化服务API:** 从API version 18 开始，该接口支持在原子化服务中使用。 148 149**系统能力：** SystemCapability.ArkUI.ArkUI.Full 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| --- | --- | --- | --- | 155| id | string | 是 | 组件的id。| 156| isFrozen | boolean | 是 | 是否设置冻结，默认值为false。| 157 158**错误码：** 159 160以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 161 162| 错误码ID | 错误信息 | 163| -------- | -------- | 164| 202 | The caller is not a system application. | 165 166```js 167@Entry 168@Component 169struct Index { 170 @State columnWidth1: string = '100%'; 171 @State currentIndex: number = 0; 172 private controller: TabsController = new TabsController(); 173 174 build() { 175 Column() { 176 Tabs({ 177 barPosition: BarPosition.Start, 178 index: this.currentIndex, 179 controller: this.controller 180 }) { 181 TabContent() { 182 Column() 183 .width(this.columnWidth1) 184 .height('100%') 185 .backgroundColor('#00CB87') 186 } 187 .tabBar('green') 188 .id('tab1') 189 .onWillHide(() => { 190 this.getUIContext().freezeUINode('tab1', true); 191 }) 192 .onWillShow(() => { 193 this.getUIContext().freezeUINode('tab1', false); 194 }) 195 196 TabContent() { 197 Column() 198 .width('100%') 199 .height('100%') 200 .backgroundColor('#007DFF') 201 } 202 .tabBar('blue') 203 .id('tab2') 204 .onWillHide(() => { 205 this.getUIContext().freezeUINode('tab2', true); 206 }) 207 .onWillShow(() => { 208 this.getUIContext().freezeUINode('tab1', true); 209 this.columnWidth1 = '50%'; 210 setTimeout(() => { 211 this.getUIContext().freezeUINode('tab1', false); 212 this.columnWidth1 = '20%'; 213 }, 5000) 214 }) 215 216 TabContent() { 217 Column() 218 .width('100%') 219 .height('100%') 220 .backgroundColor('#FFBF00') 221 } 222 .tabBar('yellow') 223 .id('tab3') 224 .onWillHide(() => { 225 this.getUIContext().freezeUINode('tab3', true); 226 }) 227 .onWillShow(() => { 228 this.getUIContext().freezeUINode('tab3', false); 229 }) 230 231 } 232 .vertical(false) 233 .barMode(BarMode.Fixed) 234 .barWidth(360) 235 .barHeight(56) 236 .animationDuration(0) 237 .onChange((index: number) => { 238 this.currentIndex = index; 239 }) 240 .width(360) 241 .height(296) 242 .margin({ top: 52 }) 243 .backgroundColor('#F1F3F5') 244 }.width('100%') 245 } 246} 247``` 248 249### freezeUINode<sup>18+</sup> 250 251freezeUINode(uniqueId: number, isFrozen: boolean): void 252 253使用uniqueId设置组件冻结状态，防止自身脏区标记并进行布局更新。 254 255**原子化服务API:** 从API version 18 开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.ArkUI.ArkUI.Full 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| --- | --- | --- | --- | 263| uniqueId | number | 是 | 组件的number。| 264| isFrozen | boolean | 是 | 是否设置冻结，默认值为false。| 265 266**错误码：** 267 268以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 269 270| 错误码ID | 错误信息 | 271| -------- | -------- | 272| 202 | The caller is not a system application. | 273 274```js 275@Entry 276@Component 277struct Index { 278 @State columnWidth1: string = '100%'; 279 @State currentIndex: number = 0; 280 private controller: TabsController = new TabsController(); 281 282 build() { 283 Column() { 284 Tabs({ 285 barPosition: BarPosition.Start, 286 index: this.currentIndex, 287 controller: this.controller 288 }) { 289 TabContent() { 290 Column() 291 .width(this.columnWidth1) 292 .height('100%') 293 .backgroundColor('#00CB87') 294 } 295 .tabBar('green') 296 .id('tab1') 297 .onWillHide(() => { 298 const node = this.getUIContext().getFrameNodeById('tab1'); 299 const uniqueId = node?.getUniqueId(); 300 this.getUIContext().freezeUINode(uniqueId, true); 301 }) 302 .onWillShow(() => { 303 const node = this.getUIContext().getFrameNodeById('tab1'); 304 const uniqueId = node?.getUniqueId(); 305 this.getUIContext().freezeUINode(uniqueId, false) 306 }) 307 308 TabContent() { 309 Column() 310 .width('100%') 311 .height('100%') 312 .backgroundColor('#007DFF') 313 } 314 .tabBar('blue') 315 .id('tab2') 316 .onWillHide(() => { 317 const node = this.getUIContext().getFrameNodeById('tab2'); 318 const uniqueId = node?.getUniqueId(); 319 this.getUIContext().freezeUINode(uniqueId, true); 320 }) 321 .onWillShow(() => { 322 const node = this.getUIContext().getFrameNodeById('tab1'); 323 const uniqueId = node?.getUniqueId(); 324 this.getUIContext().freezeUINode(uniqueId, true); 325 326 this.columnWidth1 = '50%'; 327 setTimeout(() => { 328 this.getUIContext().freezeUINode(uniqueId, false); 329 this.columnWidth1 = '20%'; 330 }, 5000) 331 }) 332 333 TabContent() { 334 Column() 335 .width('100%') 336 .height('100%') 337 .backgroundColor('#FFBF00') 338 } 339 .tabBar('yellow') 340 .id('tab3') 341 .onWillHide(() => { 342 const node = this.getUIContext().getFrameNodeById('tab3'); 343 const uniqueId = node?.getUniqueId(); 344 this.getUIContext().freezeUINode(uniqueId, true); 345 }) 346 .onWillShow(() => { 347 const node = this.getUIContext().getFrameNodeById('tab3'); 348 const uniqueId = node?.getUniqueId(); 349 this.getUIContext().freezeUINode(uniqueId, false); 350 }) 351 352 } 353 .vertical(false) 354 .barMode(BarMode.Fixed) 355 .barWidth(360) 356 .barHeight(56) 357 .animationDuration(0) 358 .onChange((index: number) => { 359 this.currentIndex = index; 360 }) 361 .width(360) 362 .height(296) 363 .margin({ top: 52 }) 364 .backgroundColor('#F1F3F5') 365 }.width('100%') 366 } 367} 368```
