自定义组件冻结功能专为优化复杂UI页面的性能而设计,尤其适用于包含多个页面栈、长列表或宫格布局的场景。当状态变量绑定多个UI组件时,其变化易触发大量组件刷新,导致界面卡顿与响应延迟。为提升这类高负载UI界面的刷新性能,建议开发者使用自定义组件冻结功能。
组件冻结功能是一种性能优化机制,它会冻结非激活状态下的组件的刷新能力。当组件处于非激活状态时,即使其绑定的状态变量发生变化,也不会触发该组件的UI重新渲染,从而降低复杂UI场景下的刷新负载。
在阅读本文档前,开发者需要了解自定义组件基本语法。建议提前阅读:自定义组件。
从API version 11开始,支持自定义组件冻结功能。
从API version 18开始,支持自定义组件冻结混用场景。
从API version 20开始,通过配置BuilderNode的inheritFreezeOptions接口为true,实现BuilderNode继承冻结的能力。
组件冻结的工作原理是:
简而言之,组件冻结旨在优化复杂界面下的UI刷新性能。在存在多个不可见自定义组件的情况下,如多页面栈、长列表或宫格,通过组件冻结可以实现按需刷新,即仅刷新当前可见的自定义组件,而将不可见自定义组件的刷新延迟至它们变为可见时。
需要注意,组件active/inactive并不等同于其可见性。组件冻结目前仅适用于以下场景:
本示例使用了router进行页面跳转,建议开发者使用组件导航(Navigation)代替页面路由(router)来实现页面切换。Navigation提供了更多的功能和更灵活的自定义能力。请参考使用Navigation的组件冻结用例。
当页面1调用router.pushUrl接口跳转到页面2时,页面1为隐藏不可见状态,此时如果更新页面1中的状态变量,不会触发页面1刷新。
图示如下:

页面1:
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
const STORAGE_LINK_INITIAL_VALUE = 47;
@Entry
@Component({ freezeWhenInactive: true })
struct PageOne {
@StorageLink('PropA') @Watch('first') storageLink: number = STORAGE_LINK_INITIAL_VALUE;
first() {
hilog.info(DOMAIN, TAG, '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(() => {
// 此处传入的url,需要开发者自行替换。
this.getUIContext().getRouter().pushUrl({ url: 'View/PageTwo' }, (err: Error) => {
if (err) {
hilog.error(DOMAIN, TAG, 'pushUrl failed. Cause: %{public}s', JSON.stringify(err));
}
});
})
}
}
} 页面2:
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
@Entry
@Component({ freezeWhenInactive: true })
struct PageTwo {
@StorageLink('PropA') @Watch('second') storageLink: number = 1;
second() {
hilog.info(DOMAIN, TAG, 'second page: ' + `${this.storageLink}`);
}
build() {
Column() {
Text(`second Page ${this.storageLink}`).fontSize(50)
Button('back')
.onClick(() => {
this.getUIContext().getRouter().back();
})
// 点击Button修改storageLink,观察页面1隐藏时会不会触发first回调
Button('second page storageLink + 2').fontSize(30)
.onClick(() => {
this.storageLink += 2;
})
}
}
} 在上面的示例中:
1.在页面1中点击first page storageLink + 1,storageLink状态变量改变,@Watch注册的方法first会被调用。
2.在页面1中点击go to next page,跳转到页面2,页面1隐藏,状态由active变为inactive。
3.在页面2中点击second page storageLink + 2,只会回调页面2中@Watch注册的方法second,因为页面1的状态变量此时已被冻结。
4.在页面2中点击back,页面2被销毁,页面1的状态由inactive变为active,重新刷新在inactive时被冻结的状态变量,页面1中@Watch注册的方法first被再次调用。
对Tabs中当前不可见的TabContent进行冻结,修改状态变量不会触发冻结组件的更新。
需要注意的是:在首次渲染的时候,Tabs只会创建当前正在显示的TabContent,当切换全部的TabContent后,TabContent才会被全部创建。
图示如下:

import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
@Entry
@Component
struct TabContentTest {
@State @Watch('onMessageUpdated') message: number = 0;
private data: number[] = [0, 1];
onMessageUpdated() {
hilog.info(DOMAIN, TAG, `TabContent message callback func ${this.message}`);
}
build() {
Row() {
Column() {
// 点击Button修改message,触发可见TabContent的onMessageUpdated回调
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;
index: number = 0;
onMessageUpdated() {
hilog.info(DOMAIN, TAG, `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.点击tab1切换到另外的TabContent,该TabContent的状态由inactive变为active,对应的@Watch注册的方法onMessageUpdated被触发。
3.再次点击change message更改message的值,仅当前显示的TabContent子组件中的@Watch注册的方法onMessageUpdated被触发。

对LazyForEach中缓存的自定义组件进行冻结,修改状态变量不会触发缓存组件的更新。
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
// 用于处理数据监听的IDataSource的基本实现
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = [];
private originDataArray: string[] = [];
public totalCount(): number {
return 0;
}
public getData(index: number): string {
return this.originDataArray[index];
}
// 该方法为框架侧调用,为LazyForEach组件向其数据源处添加listener监听
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
hilog.info(DOMAIN, TAG, 'add listener');
this.listeners.push(listener);
}
}
// 该方法为框架侧调用,为对应的LazyForEach组件在数据源处去除listener监听
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
hilog.info(DOMAIN, TAG, 'remove listener');
this.listeners.splice(pos, 1);
}
}
// 通知LazyForEach组件需要重载所有子组件
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded();
});
}
// 通知LazyForEach组件需要在index对应索引处添加子组件
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index);
});
}
// 通知LazyForEach组件在index对应索引处数据有变化,需要重建该子组件
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index);
});
}
// 通知LazyForEach组件需要在index对应索引处删除该子组件
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index);
});
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = [];
public totalCount(): number {
return this.dataArray.length;
}
public getData(index: number): string {
return this.dataArray[index];
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data);
this.notifyDataAdd(index);
}
public pushData(data: string): void {
this.dataArray.push(data);
this.notifyDataAdd(this.dataArray.length - 1);
}
}
@Entry
@Component
struct LazyforEachTest {
private data: MyDataSource = new MyDataSource();
@State @Watch('onMessageUpdated') message: number = 0;
onMessageUpdated() {
hilog.info(DOMAIN, TAG, `LazyforEach message callback func ${this.message}`);
}
aboutToAppear() {
for (let i = 0; i <= 20; i++) {
this.data.pushData(`Hello ${i}`);
}
}
build() {
Column() {
Button('change message').onClick(() => {
this.message++;
})
List({ space: 3 }) {
LazyForEach(this.data, (item: string) => {
ListItem() {
FreezeChild({ message: this.message, index: item })
}
}, (item: string) => item)
}.cachedCount(5).height(500)
}
}
}
@Component({ freezeWhenInactive: true })
struct FreezeChild {
@Link @Watch('onMessageUpdated') message: number;
index: string = '';
aboutToAppear() {
hilog.info(DOMAIN, TAG, `FreezeChild aboutToAppear index: ${this.index}`);
}
onMessageUpdated() {
hilog.info(DOMAIN, TAG, `FreezeChild message callback func ${this.message}, index: ${this.index}`);
}
build() {
Text('message' + `${this.message}, index: ${this.index}`)
.width('90%')
.height(160)
.backgroundColor(0xAFEEEE)
.textAlign(TextAlign.Center)
.fontSize(30)
.fontWeight(FontWeight.Bold)
}
} 在上面的示例中:
1.点击change message更改message的值,当前正在显示的ListItem中的子组件@Watch注册的方法onMessageUpdated被触发。缓存节点中@Watch注册的方法不会被触发。(如果不加组件冻结,当前正在显示的ListItem和cachedCount缓存节点中@Watch注册的方法onMessageUpdated都会被触发。)
2.List区域外的ListItem滑动到List区域内,状态由inactive变为active,对应的@Watch注册的方法onMessageUpdated被触发。
3.再次点击change message更改message的值,仅有当前显示的ListItem中的子组件@Watch注册的方法onMessageUpdated被触发。

组件复用通过重利用缓存池中已存在的节点,而非创建新节点,来优化UI性能并提升应用流畅度。复用池中的节点尽管未在UI组件树上展示,但是状态变量的更改仍会触发UI刷新。为了解决复用池中组件异常刷新问题,可以使用组件冻结避免复用池中的组件刷新。
组件复用、if和组件冻结混用场景
下面是组件复用、if组件和组件冻结混合使用场景的例子,if组件绑定的状态变量变化成false时,触发子组件ChildComponent的下树,由于ChildComponent被标记了组件复用,所以不会被销毁,而是进入复用池,这个时候如果同时开启了组件冻结,则可以使在复用池里不再刷新。
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
@Reusable
@Component({ freezeWhenInactive: true })
struct ChildComponent {
@Link @Watch('descChange') desc: string;
@State count: number = 0;
descChange() {
hilog.info(DOMAIN, TAG, `ChildComponent messageChange ${this.desc}`);
}
aboutToReuse(params: Record<string, ESObject>): void {
this.count = params.count as number;
}
aboutToRecycle(): void {
// 输出recycled提示,确认组件进入复用池
hilog.info(DOMAIN, TAG, `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%')
}
} 在上面的示例中:
LazyForEach、组件复用和组件冻结混用场景
在数据很多的长列表滑动场景下,开发者会使用LazyForEach来按需创建组件,同时配合组件复用降低在滑动过程中因创建和销毁组件带来的开销。但是开发者如果根据其复用类型不同,设置了reuseId,或者为了保证滑动性能设置了较大的cachedCount,这就可能使复用池或者LazyForEach缓存较多的节点。在这种情况下,如果开发者触发List下所有子节点的刷新,就会带来节点刷新数量过多的问题,这个时候,可以考虑搭配组件冻结使用。
import { hilog, hiTraceMeter } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
// 用于处理数据监听的IDataSource的基本实现
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = [];
private originDataArray: string[] = [];
public totalCount(): number {
return 0;
}
public getData(index: number): string {
return this.originDataArray[index];
}
// 该方法为框架侧调用,为LazyForEach组件向其数据源处添加listener监听
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
hilog.info(DOMAIN, TAG, 'add listener');
this.listeners.push(listener);
}
}
// 该方法为框架侧调用,为对应的LazyForEach组件在数据源处去除listener监听
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
hilog.info(DOMAIN, TAG, 'remove listener');
this.listeners.splice(pos, 1);
}
}
// 通知LazyForEach组件需要重载所有子组件
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded();
});
}
// 通知LazyForEach组件需要在index对应索引处添加子组件
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index);
});
}
// 通知LazyForEach组件在index对应索引处数据有变化,需要重建该子组件
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index);
});
}
// 通知LazyForEach组件需要在index对应索引处删除该子组件
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index);
});
}
// 通知LazyForEach组件将from索引和to索引处的子组件进行交换
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMove(from, to);
});
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = [];
public totalCount(): number {
return this.dataArray.length;
}
public getData(index: number): string {
return this.dataArray[index];
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data);
this.notifyDataAdd(index);
}
public pushData(data: string): void {
this.dataArray.push(data);
this.notifyDataAdd(this.dataArray.length - 1);
}
}
@Reusable
@Component({freezeWhenInactive: true})
struct ChildComponent {
@Link @Watch('descChange') desc: string;
@State item: string = '';
@State index: number = 0;
descChange() {
hilog.info(DOMAIN, TAG, `ChildComponent messageChange ${this.desc}`);
}
aboutToReuse(params: Record<string, ESObject>): void {
this.item = params.item;
this.index = params.index;
}
aboutToRecycle(): void {
hilog.info(DOMAIN, TAG, `ChildComponent has been recycled`);
}
build() {
Column() {
Text(`ChildComponent index: ${this.index} item: ${this.item}`)
.fontSize(20)
Text(`desc: ${this.desc}`)
.fontSize(20)
}.border({width: 2, color: Color.Pink})
}
}
@Entry
@Component
struct Page {
@State desc: string = 'Hello World';
private data: MyDataSource = new MyDataSource();
aboutToAppear() {
for (let i = 0; i < 50; i++) {
this.data.pushData(`Hello ${i}`);
}
}
build() {
Column() {
Button(`change desc`).onClick(() => {
hiTraceMeter.startTrace('change desc', 1);
this.desc += '!';
hiTraceMeter.finishTrace('change desc', 1);
})
List({ space: 3 }) {
LazyForEach(this.data, (item: string, index: number) => {
ListItem() {
ChildComponent({index: index, item: item, desc: this.desc}).reuseId(index % 10 < 5 ? '1': '0')
}
}, (item: string) => item)
}.cachedCount(5)
}
.height('100%')
}
} 在上面的示例中:
图示如下:

可通过trace观察,仅触发了15个ChildComponent节点的刷新。

LazyForEach、if、组件复用和组件冻结混用场景
下面的场景中展示了LazyForEach、if、组件复用和组件冻结混用场景。在同一个父自定义组件下,可复用的节点可能通过不同的方式进入复用池,比如:
import { hilog, hiTraceMeter } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = [];
private originDataArray: string[] = [];
public totalCount(): number {
return 0;
}
public getData(index: number): string {
return this.originDataArray[index];
}
// 该方法为框架侧调用,为LazyForEach组件向其数据源处添加listener监听
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
hilog.info(DOMAIN, TAG, 'add listener');
this.listeners.push(listener);
}
}
// 该方法为框架侧调用,为对应的LazyForEach组件在数据源处去除listener监听
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
hilog.info(DOMAIN, TAG, 'remove listener');
this.listeners.splice(pos, 1);
}
}
// 通知LazyForEach组件需要重载所有子组件
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded();
});
}
// 通知LazyForEach组件需要在index对应索引处添加子组件
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index);
});
}
// 通知LazyForEach组件在index对应索引处数据有变化,需要重建该子组件
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index);
});
}
// 通知LazyForEach组件需要在index对应索引处删除该子组件
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index);
});
}
// 通知LazyForEach组件将from索引和to索引处的子组件进行交换
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMove(from, to);
});
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = [];
public totalCount(): number {
return this.dataArray.length;
}
public getData(index: number): string {
return this.dataArray[index];
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data);
this.notifyDataAdd(index);
}
public pushData(data: string): void {
this.dataArray.push(data);
this.notifyDataAdd(this.dataArray.length - 1);
}
}
@Reusable
@Component({ freezeWhenInactive: true })
struct ChildComponent {
@Link @Watch('descChange') desc: string;
@State item: string = '';
@State index: number = 0;
descChange() {
hilog.info(DOMAIN, TAG, `ChildComponent messageChange ${this.desc}`);
}
aboutToReuse(params: Record<string, ESObject>): void {
this.item = params.item;
this.index = params.index;
}
aboutToRecycle(): void {
hilog.info(DOMAIN, TAG, `ChildComponent has been recycled`);
}
build() {
Column() {
Text(`ChildComponent index: ${this.index} item: ${this.item}`)
.fontSize(20)
Text(`desc: ${this.desc}`)
.fontSize(20)
}.border({ width: 2, color: Color.Pink })
}
}
@Entry
@Component
struct Page {
@State desc: string = 'Hello World';
@State flag: boolean = true;
private data: MyDataSource = new MyDataSource();
aboutToAppear() {
for (let i = 0; i < 50; i++) {
this.data.pushData(`Hello ${i}`);
}
}
build() {
Column() {
Button(`change desc`).onClick(() => {
hiTraceMeter.startTrace('change desc', 1);
this.desc += '!';
hiTraceMeter.finishTrace('change desc', 1);
})
Button(`change flag`).onClick(() => {
hiTraceMeter.startTrace('change flag', 1);
this.flag = !this.flag;
hiTraceMeter.finishTrace('change flag', 1);
})
List({ space: 3 }) {
LazyForEach(this.data, (item: string, index: number) => {
ListItem() {
ChildComponent({ index: index, item: item, desc: this.desc }).reuseId(index % 10 < 5 ? '1' : '0')
}
}, (item: string) => item)
}
.cachedCount(5)
.height('60%')
if (this.flag) {
ChildComponent({ index: -1, item: 'Hello', desc: this.desc }).reuseId('1')
}
}
.height('100%')
}
} 在上面的示例中:
开启组件冻结trace:

没有开启组件冻结trace:

当支持组件冻结的场景彼此之间组合使用时,对于不同的API版本,冻结行为会有不同。给父组件设置组件冻结标志,在API version 17及以下,当父组件解冻时,会解冻自己子组件所有的节点;从API version 18开始,父组件解冻时,只会解冻子组件的屏上节点。
Navigation和TabContent的混用
代码示例如下:
// index.ets
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
const TAB_STATE_INITIAL_VALUE = 47;
@Component
struct ChildOfParamComponent {
@Prop @Watch('onChange') childVal: number;
onChange() {
hilog.info(DOMAIN, TAG, `Appmonitor ChildOfParamComponent: childVal changed:${this.childVal}`);
}
build() {
Column() {
Text(`Child Param: ${this.childVal}`)
}
}
}
@Component
struct ParamComponent {
@Prop @Watch('onChange') paramVal: number;
onChange() {
hilog.info(DOMAIN, TAG, `Appmonitor ParamComponent: paramVal changed:${this.paramVal}`);
}
build() {
Column() {
Text(`val: ${this.paramVal}`)
ChildOfParamComponent({ childVal: this.paramVal })
}
}
}
@Component
struct DelayComponent {
@Prop @Watch('onChange') delayVal: number;
onChange() {
hilog.info(DOMAIN, TAG, `Appmonitor DelayComponent: delayVal changed:${this.delayVal}`);
}
build() {
Column() {
Text(`Delay Param: ${this.delayVal}`)
}
}
}
@Component({ freezeWhenInactive: true })
struct TabsComponent {
private controller: TabsController = new TabsController();
@State @Watch('onChange') tabState: number = TAB_STATE_INITIAL_VALUE;
onChange() {
hilog.info(DOMAIN, TAG, `Appmonitor TabsComponent: tabState changed:${this.tabState}`);
}
build() {
Column({ space: 10 }) {
Button(`Incr state ${this.tabState}`)
.fontSize(25)
.onClick(() => {
hilog.info(DOMAIN, TAG, 'Button increment state value');
this.tabState = this.tabState + 1;
})
Tabs({ barPosition: BarPosition.Start, index: 0, controller: this.controller }) {
TabContent() {
ParamComponent({ paramVal: this.tabState })
}.tabBar('Update')
TabContent() {
DelayComponent({ delayVal: this.tabState })
}.tabBar('DelayUpdate')
}
.vertical(false)
.scrollable(true)
.barMode(BarMode.Fixed)
.barWidth(400)
.barHeight(150)
.animationDuration(400)
.width('100%')
.height(200)
.backgroundColor(0xF5F5F5)
}
}
}
@Entry
@Component
struct MyNavigationTestStack {
@Provide('pageInfo') pageInfo: NavPathStack = new NavPathStack();
@Builder
PageMap(name: string) {
if (name === 'pageOne') {
PageOneStack()
} else if (name === 'pageTwo') {
PageTwoStack()
}
}
build() {
Column() {
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;
build() {
NavDestination() {
Column() {
TabsComponent()
Button('Next Page', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfo.pushPathByName('pageTwo', null);
})
}.width('100%').height('100%')
}.title('pageOne')
.onBackPressed(() => {
this.pageInfo.pop();
return true;
})
}
}
@Component
struct PageTwoStack {
@Consume('pageInfo') pageInfo: NavPathStack;
build() {
NavDestination() {
Column() {
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;
})
}
} 代码运行结果图如下:

点击Next Page,进入pageOne页面,页面中存在两个tab标签,默认在Update标签,开启组件冻结功能,TabContent的标签如果未被选中,状态变量不会刷新,如以下操作。
点击Incr state,日志中查询Appmonitor,存在3个打印。

切换到DelayUpdate标签,点击Incr state,日志中查询Appmonitor,存在2个打印。DelayUpdate中状态变量不会刷新与Update标签中相关的状态变量。

在API version 17及以下:
点击Next page进入下一个页面并返回,标签默认在DelayUpdate,再次点击Incr state,日志中查询Appmonitor,存在4个打印,页面路由返回时,会解冻TabContent所有的标签。

在API version 18及以上:
点击Next page进入下一个页面并返回,标签默认在DelayUpdate,再次点击Incr state,日志中查询Appmonitor,存在2个打印,页面路由返回时,只会解冻对应标签的节点。

页面和LazyForEach
Navigation和TabContent混用时,之所以会解冻TabContent标签的子节点,是因为回到前一个页面时会从父组件开始递归解冻子组件,与此行为类似的还有页面生命周期:OnPageShow。OnPageShow会将当前Page中的根节点设置为active状态,TabContent作为页面的子节点,也会被设置为active状态。在屏幕灭屏和屏幕亮屏时会分别触发页面的生命周期:OnPageHide和OnPageShow,因此页面中使用LazyForEach时,手动灭屏和亮屏也能实现页面路由一样的效果,如以下示例代码:
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
// 用于处理数据监听的IDataSource的基本实现
class BasicDataSource implements IDataSource {
private listeners: DataChangeListener[] = [];
private originDataArray: string[] = [];
public totalCount(): number {
return 0;
}
public getData(index: number): string {
return this.originDataArray[index];
}
// 该方法为框架侧调用,为LazyForEach组件向其数据源处添加listener监听
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
hilog.info(DOMAIN, TAG, 'add listener');
this.listeners.push(listener);
}
}
// 该方法为框架侧调用,为对应的LazyForEach组件在数据源处去除listener监听
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
hilog.info(DOMAIN, TAG, 'remove listener');
this.listeners.splice(pos, 1);
}
}
// 通知LazyForEach组件需要重载所有子组件
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded();
});
}
// 通知LazyForEach组件需要在index对应索引处添加子组件
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdd(index);
});
}
// 通知LazyForEach组件在index对应索引处数据有变化,需要重建该子组件
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChange(index);
});
}
// 通知LazyForEach组件需要在index对应索引处删除该子组件
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDelete(index);
});
}
// 通知LazyForEach组件将from索引和to索引处的子组件进行交换
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMove(from, to);
});
}
}
class MyDataSource extends BasicDataSource {
private dataArray: string[] = [];
public totalCount(): number {
return this.dataArray.length;
}
public getData(index: number): string {
return this.dataArray[index];
}
public addData(index: number, data: string): void {
this.dataArray.splice(index, 0, data);
this.notifyDataAdd(index);
}
public pushData(data: string): void {
this.dataArray.push(data);
this.notifyDataAdd(this.dataArray.length - 1);
}
}
@Reusable
@Component({ freezeWhenInactive: true })
struct ChildComponent {
@State desc: string = '';
@Link @Watch('sumChange') sum: number;
sumChange() {
hilog.info(DOMAIN, TAG, `sum: Change ${this.sum}`);
}
aboutToReuse(params: Record<string, Object>): void {
this.desc = params.desc as string;
this.sum = params.sum as number;
}
aboutToRecycle(): void {
hilog.info(DOMAIN, TAG, `ChildComponent has been recycled`);
}
build() {
Column() {
Divider()
.color('#ff11acb8')
Text(`subcomponent: ${this.desc}`)
.fontSize(30)
.fontWeight(30)
Text(`${this.sum}`)
.fontSize(30)
.fontWeight(30)
}
}
}
@Entry
@Component({ freezeWhenInactive: true })
struct Page {
private data: MyDataSource = new MyDataSource();
@State sum: number = 0;
@State desc: string = '';
aboutToAppear() {
for (let index = 0; index < 20; index++) {
this.data.pushData(index.toString());
}
}
build() {
Column() {
Button(`add sum`).onClick(() => {
this.sum++;
})
.fontSize(30)
.margin(20)
List() {
LazyForEach(this.data, (item: string) => {
ListItem() {
ChildComponent({ desc: item, sum: this.sum })
}
.width('100%')
.height(100)
}, (item: string) => item)
}.cachedCount(5)
}
.height('100%')
.width('100%')
}
} 在组件复用场景中,已经对LazyForEach的节点进行了详细说明,分为屏上节点和cachedCount节点。

向下滑动LazyForEach,让cachedCount补充节点,点击add sum,搜索打印日志:sum: Change,出现了8条打印。

在API version 17及以下:
灭屏之后亮屏,触发OnPageShow,点击add sum,打印数量为屏上节点与cachedCount数量的总和。

从API version 18开始:
灭屏之后亮屏,触发OnPageShow,点击add sum,只会打印屏上节点数量,不会再解冻cachedCount中的节点。

在API version 20之前,BuilderNode无法继承父组件冻结。如下面的例子所示,FreezeBuildNode中使用了自定义节点BuilderNode。BuilderNode可以通过命令式动态挂载组件,而组件冻结又是强依赖父子关系来通知是否开启组件冻结。如果父组件使用组件冻结,且组件树的中间层级上又启用了BuilderNode,则BuilderNode的子组件将无法被冻结。
在API version 20及以后,开发者可以通过配置BuilderNode的inheritFreezeOptions接口为true,实现BuilderNode继承冻结的能力。
import { BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
// 定义一个Params类,用于传递参数
class Params {
public 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() {
hilog.info(DOMAIN, TAG, `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() {
hilog.info(DOMAIN, TAG, `FreezeBuildNode message callback func ${this.message}, index: ${this.index}`);
}
build() {
NodeContainer(new TextNodeController(this.index))
.width('100%')
.height('100%')
.backgroundColor('#FFF0F0F0')
}
} 在上面的示例中:
点击change,改变message的值,当前正在显示的TabContent组件中@Watch注册的方法onMessageUpdated被触发。未显示的TabContent中的BuilderNode节点下组件的@Watch方法onMessageUpdated也被触发,并没有被冻结。

在以下示例中,子组件ChildComponent开启了组件冻结且被标记了组件复用,当if组件绑定的状态变量flag修改为false时,子组件ChildComponent下树并进入复用池。由于子组件开启了组件冻结,所以进入复用池时,该组件也会被冻结。在复用池内,若修改状态变量count,该组件因处于inactive状态,既不会刷新也不会触发Watch回调。
当if组件绑定的状态变量flag修改为true时,子组件ChildComponent出复用池并被标记为active状态,但不会触发状态变量count绑定的Watch回调。这是因为组件复用的执行逻辑早于组件解冻的执行逻辑。子组件被复用时会将脏节点刷新(包括在冻结期间需要延迟刷新的变量绑定的系统组件),并清空脏节点列表。在子组件被复用后,重新被标记为active状态,此时子组件执行解冻逻辑,由于复用时清空了脏节点列表,所以此时判断冻结期间无变量改变,不会触发Watch回调。
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'FreezeChild';
@Reusable
@Component({ freezeWhenInactive: true })
struct ChildComponent {
@Link @Watch('onChange') count: number;
onChange() {
hilog.info(DOMAIN, TAG, `ChildComponent messageChange ${this.count}`);
}
aboutToReuse(params: Record<string, ESObject>): void {
// 在aboutToReuse中改值,解冻时同样不会触发Watch回调
this.count++;
hilog.info(DOMAIN, TAG, `ChildComponent has been reused`);
}
aboutToRecycle(): void {
hilog.info(DOMAIN, TAG, `ChildComponent has been recycled`);
}
build() {
Column() {
Text(`ChildComponent count: ${this.count}`)
.fontSize(20)
}
}
}
@Entry
@Component
struct Index {
@State flag: boolean = true;
@State count: number = 0;
build() {
Column() {
Button(`change flag`)
.onClick(() => {
this.flag = !this.flag;
})
.margin(10)
.width('50%')
Button(`change count`)
.onClick(() => {
this.count++;
})
.margin(10)
.width('50%')
if (this.flag) {
ChildComponent({ count: this.count })
}
}
.height('100%')
}
}