一、自定义组件冻结
自定义组件冻结功能专为优化复杂UI页面的性能而设计，尤其适用于包含多个页面栈、长列表或宫格布局的场景。在这些情况下，当状态变量绑定了多个UI组件，其变化可能触发大量UI组件的刷新，进而导致界面卡顿和响应延迟。为了提升这类负载UI界面的刷新性能，开发者可以选择尝试使用自定义组件冻结功能。
组件冻结的工作原理是：
- 开发者通过设置freezeWhenInactive属性，即可激活组件冻结机制。
- 启用后，系统将仅对处于激活状态的自定义组件进行更新，这使得UI框架可以尽量缩小更新范围，仅限于用户可见范围内（激活状态）的自定义组件，从而提高复杂UI场景下的刷新效率。
- 当之前处于inactive状态的自定义组件重新变为active状态时，状态管理框架会对其执行必要的刷新操作，确保UI的正确展示。
简而言之，组件冻结旨在优化复杂界面下的UI刷新性能。在存在多个不可见自定义组件的情况下，如多页面栈、长列表或宫格，通过组件冻结可以实现按需刷新，即仅刷新当前可见的自定义组件，而将不可见自定义组件的刷新延迟至它们变为可见时。
需要注意，组件active/inactive并不等同于其可见性。组件冻结目前仅适用于以下场景：
- 页面路由：当前栈顶页面为active状态，非栈顶不可见页面为inactive状态。
- TabContent：只有当前显示的TabContent中的自定义组件处于active状态，其余则为inactive。
- LazyForEach：仅当前显示的LazyForEach中的自定义组件为active状态，而缓存节点的组件则为inactive状态。
- Navigation：当前显示的NavDestination中的自定义组件为active状态，而其他未显示的NavDestination组件则为inactive状态。
- 组件复用：进入复用池的组件为inactive状态，从复用池上树的节点为active状态。
其他场景，如堆叠布局（Stack）下的被遮罩的组件，这些组件尽管不可见，但并不被视为inactive状态，因此不在组件冻结的适用范围内。
1、freezeWhenInactive
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| freezeWhenInactive | bool | 否 | 是否开启组件冻结。 |
示例
@Component({
freezeWhenInactive: true })
struct MyComponent {
build() {
}
}
二、当前支持的场景
1、页面路由
当页面1调用router.pushUrl接口跳转到页面2时，页面1为隐藏不可见状态，此时如果更新页面1中的状态变量，不会触发页面1刷新。
图示如下：
页面1：
import {
router } from '@kit.ArkUI';
@Entry
@Component({
freezeWhenInactive: true })
struct Page1 {
@StorageLink('PropA') @Watch("first") storageLink: number = 47;
first() {
console.info("first page " + `${
this.storageLink}`)
}
build() {
Column() {
Text(`From first Page ${
this.storageLink}`).fontSize(50)
Button('first page storageLink + 1').fontSize(30)
.onClick(() => {
this.storageLink += 1
})
Button('go to next page').fontSize(30)
.onClick(() => {
router.pushUrl({
url: 'pages/Page2' })
})
}
}
}
页面2：
import {
router } from '@kit.ArkUI';
@Entry
@Component({
freezeWhenInactive: true })
struct Page2 {
@StorageLink('PropA') @Watch("second") storageLink2: number = 1;
second() {
console.info("second page: " + `${
this.storageLink2}`)
}
build() {
Column() {
Text(`second Page ${
this.storageLink2}`).fontSize(50)
Button('Change Divider.strokeWidth')
.onClick(() => {
router.back()
})
Button('second page storageLink2 + 2').fontSize(30)
.onClick(() => {
this.storageLink2 += 2
})
}
}
}
在上面的示例中：
1.点击页面1中的Button “first page storageLink + 1”，storageLink状态变量改变，@Watch中注册的方法first会被调用。
2.通过router.pushUrl({url: ‘pages/second’})，跳转到页面2，页面1隐藏，状态由active变为inactive。
3.点击页面2中的Button “this.storageLink2 += 2”，只回调页面2@Watch中注册的方法second，因为页面1的状态变量此时已被冻结。
4.点击“back”，页面2被销毁，页面1的状态由inactive变为active，重新刷新在inactive时被冻结的状态变量，页面1@Watch中注册的方法first被再次调用。
2、TabContent
对Tabs中当前不可见的TabContent进行冻结，不会触发组件的更新。
需要注意的是：在首次渲染的时候，Tab只会创建当前正在显示的TabContent，当切换全部的TabContent后，TabContent才会被全部创建。
图示如下
@Entry
@Component
struct TabContentTest {
@State @Watch("onMessageUpdated") message: number = 0;
private data: number[] = [0, 1]
onMessageUpdated() {
console.info(`TabContent message callback func ${
this.message}`)
}
build() {
Row() {
Column() {
Button('change message').onClick(() => {
this.message++
})
Tabs() {
ForEach(this.data, (item: number) => {
TabContent() {
FreezeChild({
message: this.message, index: item })
}.tabBar(`tab${
item}`)
}, (item: number) => item.toString())
}
}
.width('100%')
}
.height('100%')
}
}
@Component({
freezeWhenInactive: true })
struct FreezeChild {
@Link @Watch("onMessageUpdated") message: number
private index: number = 0
onMessageUpdated() {
console.info(`FreezeChild message callback func ${
this.message}, index: ${
this.index}`)
}
build() {
Text("message" + `${
this.message}, index: ${
this.index}`)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
}
在上面的示例中：
1.点击“change message”更改message的值，当前正在显示的TabContent组件中的@Watch中注册的方法onMessageUpdated被触发。
2.点击“two”切换到另外的TabContent，TabContent状态由inactive变为active，对应的@Watch中注册的方法onMessageUpdated被触发。
3.再次点击“change message”更改message的值，仅当前显示的TabContent子组件中的@Watch中注册的方法onMessageUpdated被触发。
3、Navigation
当NavDestination不可见时，会对其子自定义组件设置成非激活态，不会触发组件的刷新。当返回该页面时，其子自定义组件重新恢复成激活态，触发@Watch回调进行刷新。
在下面例子中，NavigationContentMsgStack会被设置成非激活态，将不再响应状态变量的变化，也不会触发组件刷新。
@Entry
@Component
struct MyNavigationTestStack {
@Provide('pageInfo') pageInfo: NavPathStack = new NavPathStack();
@State @Watch("info") message: number = 0;
@State logNumber: number = 0;
info() {
console.info(`freeze-test MyNavigation message callback ${
this.message}`);
}
@Builder
PageMap(name: string) {
if (name === 'pageOne') {
pageOneStack({
message: this.message, logNumber: this.logNumber })
} else if (name === 'pageTwo') {
pageTwoStack({
message: this.message, logNumber: this.logNumber })
} else if (name === 'pageThree') {
pageThreeStack({
message: this.message, logNumber: this.logNumber })
}
}
build() {
Column() {
Button('change message')
.onClick(() => {
this.message++;
})
Navigation(this.pageInfo) {
Column() {
Button('Next Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pushPath({
name: 'pageOne' }); //将name指定的NavDestination页面信息入栈
})
}
}.title('NavIndex')
.navDestination(this.PageMap)
.mode(NavigationMode.Stack)
}
}
}
@Component
struct pageOneStack {
@Consume('pageInfo') pageInfo: NavPathStack;
@State index: number = 1;
@Link message: number;
@Link logNumber: number;
build() {
NavDestination() {
Column() {
NavigationContentMsgStack({
message: this.message, index: this.index, logNumber: this.logNumber })
Text("cur stack size:" + `${
this.pageInfo.size()}`)
.fontSize(30)
.fontWeight(FontWeight.Bold)
Button('Next Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pushPathByName('pageTwo', null);
})
Button('Back Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pop();
})
}.width('100%').height('100%')
}.title('pageOne')
.onBackPressed(() => {
this.pageInfo.pop();
return true;
})
}
}
@Component
struct pageTwoStack {
@Consume('pageInfo') pageInfo: NavPathStack;
@State index: number = 2;
@Link message: number;
@Link logNumber: number;
build() {
NavDestination() {
Column() {
NavigationContentMsgStack({
message: this.message, index: this.index, logNumber: this.logNumber })
Text("cur stack size:" + `${
this.pageInfo.size()}`)
.fontSize(30)
.fontWeight(FontWeight.Bold)
Button('Next Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pushPathByName('pageThree', null);
})
Button('Back Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pop();
})
}.width('100%').height('100%')
}.title('pageTwo')
.onBackPressed(() => {
this.pageInfo.pop();
return true;
})
}
}
@Component
struct pageThreeStack {
@Consume('pageInfo') pageInfo: NavPathStack;
@State index: number = 3;
@Link message: number;
@Link logNumber: number;
build() {
NavDestination() {
Column() {
NavigationContentMsgStack({
message: this.message, index: this.index, logNumber: this.logNumber })
Text("cur stack size:" + `${
this.pageInfo.size()}`)
.fontSize(30)
.fontWeight(FontWeight.Bold)
Button('Next Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pushPathByName('pageOne', null);
})
Button('Back Page', {
stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pop();
})
}.width('100%').height('100%')
}.title('pageThree')
.onBackPressed(() => {
this.pageInfo.pop();
return true;
})
}
}
@Component({
freezeWhenInactive: true })
struct NavigationContentMsgStack {
@Link @Watch("info") message: number;
@Link index: number;
@Link logNumber: number;
info() {
console.info(`freeze-test NavigationContent message callback ${
this.message}`);
console.info(`freeze-test ---- called by content ${
this.index}`);
this.logNumber++;
}
build() {
Column() {
Text("msg:" + `${
this.message}`)
.fontSize(30)
.fontWeight(FontWeight.Bold)
Text("log number:" + `${
this.logNumber}`)
.fontSize(30)
.fontWeight(FontWeight.Bold)
}
}
}
在上面的示例中：
1.点击“change message”更改message的值，当前正在显示的MyNavigationTestStack组件中的@Watch中注册的方法info被触发。
2.点击“Next Page”切换到PageOne，创建pageOneStack节点。
3.再次点击“change message”更改message的值，仅pageOneStack中的NavigationContentMsgStack子组件中的@Watch中注册的方法info被触发。
4.再次点击“Next Page”切换到PageTwo，创建pageTwoStack节点。
5.再次点击“change message”更改message的值，仅pageTwoStack中的NavigationContentMsgStack子组件中的@Watch中注册的方法info被触发。
6.再次点击“Next Page”切换到PageThree，创建pageThreeStack节点。
7.再次点击“change message”更改message的值，仅pageThreeStack中的NavigationContentMsgStack子组件中的@Watch中注册的方法info被触发。
8.点击“Back Page”回到PageTwo，此时，仅pageTwoStack中的NavigationContentMsgStack子组件中的@Watch中注册的方法info被触发。
9.再次点击“Back Page”回到PageOne，此时，仅pageOneStack中的NavigationContentMsgStack子组件中的@Watch中注册的方法info被触发。
10.再次点击“Back Page”回到初始页，此时，无任何触发。
4、组件复用
组件复用通过重利用缓存池中已存在的节点，而非创建新节点，来优化UI性能并提升应用流畅度。复用池中的节点尽管未在UI组件树上展示，但是状态变量的更改仍会触发UI刷新。为了解决复用池中组件异常刷新问题，可以使用组件冻结避免复用池中的组件刷新。
@Reusable
@Component({
freezeWhenInactive: true})
struct ChildComponent {
@Link @Watch('descChange') desc: string;
@State count: number = 0;
descChange() {
console.info(`ChildComponent messageChange ${
this.desc}`);
}
aboutToReuse(params: Record<string, ESObject>): void {
this.count = params.count as number;
}
aboutToRecycle(): void {
console.info(`ChildComponent has been recycled`);
}
build() {
Column() {
Text(`ChildComponent desc: ${
this.desc}`)
.fontSize(20)
Text(`ChildComponent count ${
this.count}`)
.fontSize(20)
}.border({
width: 2, color: Color.Pink})
}
}
@Entry
@Component
struct Page {
@State desc: string = 'Hello World';
@State flag: boolean = true;
@State count: number = 0;
build() {
Column() {
Button(`change desc`).onClick(() => {
this.desc += '!';
})
Button(`change flag`).onClick(() => {
this.count++;
this.flag =! this.flag;
})
if (this.flag) {
ChildComponent({
desc: this.desc, count: this.count})
}
}
.height('100%')
}
}
具体流程如下：
1.点击change flag，改变flag为false：
-
被标记@Reusable的ChildComponent组件在下树时，不会被销毁，而是进入复用池，触发aboutToRecycle生命周期，同时设置状态为inactive。
-
ChildComponent同时也开启了组件冻结，当其状态为inactive时，不会响应任何状态变量变化带来的UI刷新。
2.点击change desc，触发Page的成员变量desc的变化。
-
desc是@State装饰的，其变化会通知给其子组件ChildComponent@Link装饰的desc。
-
但因为ChildComponent是inactive状态，且开启了组件冻结，所以这次变化并不会触发@Watch(‘descChange’)的回调，以及ChildComponentUI刷新。如果没有开启组件冻结，当前@Watch(‘descChange’)会立即回调，且复用池内的ChildComponent组件也会对应刷新。
3.再次点击change flag，改变flag为true：
-
ChildComponent从复用池中重新加入到组件树上。
-
回调aboutToReuse生命周期，将当前最新的count值同步给子组件。desc是通过@State->@Link同步的，所以无需开发者手动在aboutToReuse中赋值。
-
设置ChildComponent为active状态，并且刷新在inactive时没有刷新的组件，在当前例子中，就是Text(ChildComponent desc: ${this.desc})。
三、限制条件
如下面的例子所示，FreezeBuildNode中使用了自定义节点BuilderNode。BuilderNode可以通过命令式动态挂载组件，而组件冻结又是强依赖父子关系来通知是否开启组件冻结。如果父组件使用组件冻结，且组件树的中间层级上又启用了BuilderNode，则BuilderNode的子组件将无法被冻结。
import {
BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI';
// 定义一个Params类，用于传递参数
class Params {
index: number = 0;
constructor(index: number) {
this.index = index;
}
}
// 定义一个buildNodeChild组件，它包含一个message属性和一个index属性
@Component
struct buildNodeChild {
@StorageProp("buildNodeTest") @Watch("onMessageUpdated") message: string = "hello world";
@State index: number = 0;
// 当message更新时，调用此方法
onMessageUpdated() {
console.log(`FreezeBuildNode builderNodeChild message callback func ${
this.message},index：${
this.index}`);
}
build() {
Text(`buildNode Child message: ${
this.message}`).fontSize(30)
}
}
// 定义一个buildText函数，它接收一个Params参数并构建一个Column组件
@Builder
function buildText(params: Params) {
Column() {
buildNodeChild({
index: params.index })
}
}
// 定义一个TextNodeController类，继承自NodeController
class TextNodeController extends NodeController {
private textNode: BuilderNode<[Params]> | null = null;
private index: number = 0;
// 构造函数接收一个index参数
constructor(index: number) {
super();
this.index = index;
}
// 创建并返回一个FrameNode
makeNode(context: UIContext): FrameNode | null {
this.textNode = new BuilderNode(context);
this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.index));
return this.textNode.getFrameNode();
}
}
// 定义一个Index组件，它包含一个message属性和一个data数组
@Entry
@Component
struct Index {
@StorageLink("buildNodeTest") message: string = "hello";
private data: number[] = [0, 1];
build() {
Row() {
Column() {
Button("change").fontSize(30)
.onClick(() => {
this.message += 'a';
})
Tabs() {
ForEach(this.data, (item: number) => {
TabContent() {
FreezeBuildNode({
index: item })
}.tabBar(`tab${
item}`)
}, (item: number) => item.toString())
}
}
}
.width('100%')
.height('100%')
}
}
// 定义一个FreezeBuildNode组件，它包含一个message属性和一个index属性
@Component({
freezeWhenInactive: true })
struct FreezeBuildNode {
@StorageProp("buildNodeTest") @Watch("onMessageUpdated") message: string = "1111";
@State index: number = 0;
// 当message更新时，调用此方法
onMessageUpdated() {
console.log(`FreezeBuildNode message callback func ${
this.message}, index: ${
this.index}`);
}
build() {
NodeContainer(new TextNodeController(this.index))
.width('100%')
.height('100%')
.backgroundColor('#FFF0F0F0')
}
}
在上面的示例中：
点击Button(“change”)。改变message的值，当前正在显示的TabContent组件中的@Watch中注册的方法onMessageUpdated被触发。未显示的TabContent中的BuilderNode节点下组件的@Watch方法onMessageUpdated也被触发，并没有被冻结。
