c7b3d349创建于 2025年7月14日历史提交

@ohos.arkui.UIContext (UIContext)(系统接口)

在Stage模型中，WindowStage/Window可以通过loadContent接口加载页面并创建UI的实例，并将页面内容渲染到关联的窗口中，所以UI实例和窗口是一一关联的。一些全局的UI接口是和具体UI实例的执行上下文相关的，在当前接口调用时，通过追溯调用链跟踪到UI的上下文，来确定具体的UI实例。若在非UI页面中或者一些异步回调中调用这类接口，可能无法跟踪到当前UI的上下文，导致接口执行失败。

说明：

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

示例效果请以真机运行为准，当前DevEco Studio预览器不支持。

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.arkui.UIContext (UIContext)。

UIContext

以下API需先使用ohos.window中的getUIContext()方法获取UIContext实例，再通过此实例调用对应方法。或者可以通过自定义组件内置方法getUIContext()获取。本文中UIContext对象以uiContext表示。

setDynamicDimming¹²⁺

setDynamicDimming(id: string, value: number): void

通过该方法设置组件的压暗程度。

说明：

设置该属性后设置其他效果类属性会导致效果冲突。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
id	string	是	组件id。
value	number	是	组件压暗程度取值范围[0,1], 由0到1逐渐变亮。

示例：

@Entry
@Component
struct Index {
  @State
  myCount : number = 100

  build() {
    Column(){
      Image($r('app.media.testImage')).width(500).height(800).id("test")
    }.width("100%").height("100%").onClick(()=>{
      this.getUIContext().setDynamicDimming("test",1)
      this.getUIContext()?.animateTo({duration:5000 },()=>{
        this.getUIContext().setDynamicDimming("test",0)
      })
    })
  }
}

api-switch-overview

animateToImmediately¹²⁺

animateToImmediately(param: AnimateParam , event: () => void): void

animateToImmediately接口允许用户通过UIContext对象，获取显式立即动画的能力。同时加载多个属性动画的情况下，使用该接口可以立即执行闭包代码中状态变化导致的过渡动效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
param	AnimateParam	是	设置动画效果相关参数。
event	() => void	是	指定显示动效的闭包函数，在闭包函数中导致的状态变化系统会自动插入过渡动画。

示例：

该示例实现了通过UIContext对象获取显式立即动画的能力，调用animateToImmediately接口实现参数定义的动画效果。

// xxx.ets
@Entry
@Component
struct AnimateToImmediatelyExample {
  @State widthSize: number = 250
  @State heightSize: number = 100
  @State opacitySize: number = 0
  private flag: boolean = true
  uiContext: UIContext | null | undefined = this.getUIContext();

  build() {
    Column() {
      Column()
        .width(this.widthSize)
        .height(this.heightSize)
        .backgroundColor(Color.Green)
        .opacity(this.opacitySize)
      Button('change size')
        .margin(30)
        .onClick(() => {
          if (this.flag) {
            this.uiContext?.animateToImmediately({
              delay: 0,
              duration: 1000
            }, () => {
              this.opacitySize = 1
            })
            this.uiContext?.animateTo({
              delay: 1000,
              duration: 1000
            }, () => {
              this.widthSize = 150
              this.heightSize = 60
            })
          } else {
            this.uiContext?.animateToImmediately({
              delay: 0,
              duration: 1000
            }, () => {
              this.widthSize = 250
              this.heightSize = 100
            })
            this.uiContext?.animateTo({
              delay: 1000,
              duration: 1000
            }, () => {
              this.opacitySize = 0
            })
          }
          this.flag = !this.flag
        })
    }.width('100%').margin({ top: 5 })
  }
}

animateToImmediately

freezeUINode¹⁸⁺

freezeUINode(id: string, isFrozen: boolean): void

通过id设置组件冻结状态，防止组件被标记为脏从而触发布局更新。

原子化服务API: 从API version 18 开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
id	string	是	组件的id。
isFrozen	boolean	是	是否设置冻结。 true表示设置冻结，false表示设置不冻结。默认值为false。

错误码：

以下错误码详情请参考通用错误码。

错误码ID	错误信息
202	The caller is not a system application.

@Entry
@Component
struct Index {
  @State columnWidth1: string = '100%';
  @State currentIndex: number = 0;
  private controller: TabsController = new TabsController();

  build() {
    Column() {
      Tabs({ 
        barPosition: BarPosition.Start, 
        index: this.currentIndex, 
        controller: this.controller 
      }) {
        TabContent() {
          Column()
          .width(this.columnWidth1)
          .height('100%')
          .backgroundColor('#00CB87')
        }
        .tabBar('green')
        .id('tab1')
        .onWillHide(() => {
          // id为tab1的TabContent隐藏的时候设置该节点的冻结状态为true。
          this.getUIContext().freezeUINode('tab1', true);
        })
        .onWillShow(() => {
          // id为tab1的TabContent显示的时候设置该节点的冻结状态为false。
          this.getUIContext().freezeUINode('tab1', false);
        })

        TabContent() {
          Column()
          .width('100%')
          .height('100%')
          .backgroundColor('#007DFF')
        }
        .tabBar('blue')
        .id('tab2')
        .onWillHide(() => {
          // id为tab2的TabContent隐藏的时候设置该节点的冻结状态为true。
          this.getUIContext().freezeUINode('tab2', true);
        })
        .onWillShow(() => {
          // 当id为tab2的TabContent显示的时候，将id为tab1的节点的冻结状态设置为true。
          // 通过状态变量改变id为tab1的节点中Column的宽度。因该节点的冻结状态为true，标脏至TabContent时终止标记，不触发布局。
          this.getUIContext().freezeUINode('tab1', true);
          this.columnWidth1 = '50%';
          // 配置延时任务。
          setTimeout(() => {
            // 将id为tab1的节点的冻结状态设置为false，重新触发标记和布局。
            this.getUIContext().freezeUINode('tab1', false);
            // 通过状态变量更新tab1内部Column节点的宽度，设置this.columnWidth1为'20%'。
            this.columnWidth1 = '20%';
          }, 5000)
        })

         TabContent() {
          Column()
          .width('100%')
          .height('100%')
          .backgroundColor('#FFBF00')
        }
        .tabBar('yellow')
        .id('tab3')
        .onWillHide(() => {
          // 当id为tab3的TabContent隐藏的时候设置该节点的冻结状态为true。
          this.getUIContext().freezeUINode('tab3', true);
        })
        .onWillShow(() => {
          // id为tab3的TabContent显示的时候设置该节点的冻结状态为false。
          this.getUIContext().freezeUINode('tab3', false);
        })

      }
      .vertical(false)
      .barMode(BarMode.Fixed)
      .barWidth(360)
      .barHeight(56)
      .animationDuration(0)
      .onChange((index: number) => {
        this.currentIndex = index;
      })
      .width(360)
      .height(296)
      .margin({ top: 52 })
      .backgroundColor('#F1F3F5')
    }.width('100%')
  }
}

freezeUINode¹⁸⁺

freezeUINode(uniqueId: number, isFrozen: boolean): void

通过uniqueId设置组件的冻结状态，防止组件被标记为脏从而触发布局更新。

原子化服务API: 从API version 18 开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
uniqueId	number	是	组件的uniqueId。
isFrozen	boolean	是	是否设置冻结。 true表示设置冻结，false表示设置不冻结。默认值为false。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	The caller is not a system application.

@Entry
@Component
struct Index {
  @State columnWidth1: string = '100%';
  @State currentIndex: number = 0;
  private controller: TabsController = new TabsController();

  build() {
    Column() {
      Tabs({ 
        barPosition: BarPosition.Start, 
        index: this.currentIndex, 
        controller: this.controller 
      }) {
        TabContent() {
          Column()
          .width(this.columnWidth1)
          .height('100%')
          .backgroundColor('#00CB87')
        }
        .tabBar('green')
        .id('tab1')
        .onWillHide(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab1');
          const uniqueId = node?.getUniqueId();
          // 当id为tab1的TabContent隐藏的时候，通过uniqueId设置该节点的冻结状态为true。
          this.getUIContext().freezeUINode(uniqueId, true);
        })
        .onWillShow(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab1');
          const uniqueId = node?.getUniqueId();
          // 当id为tab1的TabContent显示的时候，通过uniqueId设置该节点的冻结状态为false。
          this.getUIContext().freezeUINode(uniqueId, false)
        })

        TabContent() {
          Column()
          .width('100%')
          .height('100%')
          .backgroundColor('#007DFF')
        }
        .tabBar('blue')
        .id('tab2')
        .onWillHide(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab2');
          const uniqueId = node?.getUniqueId();
          // 当id为tab2的TabContent隐藏的时候，通过uniqueId设置该节点的冻结状态为true。
          this.getUIContext().freezeUINode(uniqueId, true);
        })
        .onWillShow(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab1');
          const uniqueId = node?.getUniqueId();
          // 当id为tab2的TabContent显示的时候，通过uniqueId设置id为tab1的节点的冻结状态为true。
          // 通过状态变量改变id为tab1的节点内部Column节点的宽度。由于id为tab1的节点冻结状态为true，标脏至该TabContent时会终止标记，并且不会从该节点开始触发布局。
          this.getUIContext().freezeUINode(uniqueId, true);
          this.columnWidth1 = '50%';

          // 设置延时任务。
          setTimeout(() => {
            // 将id为tab1的节点的冻结状态设置为false，以重新触发标记和布局。
            this.getUIContext().freezeUINode(uniqueId, false);
            this.columnWidth1 = '20%';
          }, 5000)
        })

         TabContent() {
          Column()
          .width('100%')
          .height('100%')
          .backgroundColor('#FFBF00')
        }
        .tabBar('yellow')
        .id('tab3')
        .onWillHide(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab3');
          const uniqueId = node?.getUniqueId();
          // 当id为tab3的TabContent隐藏时，通过uniqueId将该节点的冻结状态设置为true。
          this.getUIContext().freezeUINode(uniqueId, true);
        })
        .onWillShow(() => {
          // 通过id查询以获取对应节点的uniqueId。
          const node = this.getUIContext().getFrameNodeById('tab3');
          const uniqueId = node?.getUniqueId();
          // 当id为tab3的TabContent显示的时候，通过uniqueId设置该节点的冻结状态为false。
          this.getUIContext().freezeUINode(uniqueId, false);
        })

      }
      .vertical(false)
      .barMode(BarMode.Fixed)
      .barWidth(360)
      .barHeight(56)
      .animationDuration(0)
      .onChange((index: number) => {
        this.currentIndex = index;
      })
      .width(360)
      .height(296)
      .margin({ top: 52 })
      .backgroundColor('#F1F3F5')
    }.width('100%')
  }
}

@ohos.arkui.UIContext (UIContext)(系统接口)

UIContext

setDynamicDimming12+

animateToImmediately12+

freezeUINode18+

freezeUINode18+

setDynamicDimming¹²⁺

animateToImmediately¹²⁺

freezeUINode¹⁸⁺

freezeUINode¹⁸⁺