diff --git a/zh-cn/application-dev/ui/Readme-CN.md b/zh-cn/application-dev/ui/Readme-CN.md index 5127b6f98f20ee8624eabf818e8a5175e97d6e51..a173f9b67daf71257f423252431bf796b229d880 100755 --- a/zh-cn/application-dev/ui/Readme-CN.md +++ b/zh-cn/application-dev/ui/Readme-CN.md @@ -7,7 +7,7 @@ - [声明式UI描述](../ui/state-management/arkts-declarative-ui-description.md) - 自定义组件 - [创建自定义组件](../ui/state-management/arkts-create-custom-components.md) - - [router页面和自定义组件生命周期](../ui/state-management/arkts-page-custom-components-lifecycle.md) + - [自定义组件生命周期](../ui/state-management/arkts-page-custom-components-lifecycle.md) - [自定义组件的自定义布局](../ui/state-management/arkts-page-custom-components-layout.md) - [自定义组件成员属性访问限定符使用限制](../ui/state-management/arkts-custom-components-access-restrictions.md) - 组件扩展 diff --git a/zh-cn/application-dev/ui/state-management/arkts-page-custom-components-lifecycle.md b/zh-cn/application-dev/ui/state-management/arkts-page-custom-components-lifecycle.md index 9dcded2cb120b7e2f02d1fad957a89745e4ebc70..0edc94026468b305d0045039da06443f52f9181f 100644 --- a/zh-cn/application-dev/ui/state-management/arkts-page-custom-components-lifecycle.md +++ b/zh-cn/application-dev/ui/state-management/arkts-page-custom-components-lifecycle.md @@ -1,41 +1,25 @@ -# router页面和自定义组件生命周期 +# 自定义组件生命周期 -在开始之前，我们先明确自定义组件和页面的关系： +自定义组件生命周期，即用@Component或@ComponentV2装饰的自定义组件的生命周期，提供以下生命周期接口： -- 自定义组件：\@Component装饰的UI单元，可以组合多个系统组件实现UI的复用，可以调用组件的生命周期。 -- 页面：即router页面。可以由一个或者多个自定义组件组成，@Entry装饰的自定义组件为页面的入口组件，即页面的根节点，一个页面有且仅能有一个\@Entry。只有被\@Entry装饰的组件才可以调用页面的生命周期。 - -> **说明：** -> -> 当前router接口已不推荐使用，推荐使用Navigation实现路由跳转，Navigation页面的生命周期参考[Navigation页面生命周期](../arkts-navigation-navigation.md#页面生命周期)。 - -[router](../../reference/apis-arkui/js-apis-router.md)页面生命周期，即被[\@Entry](../../../application-dev/ui/state-management/arkts-create-custom-components.md#entry)装饰的组件生命周期，提供以下生命周期接口： - -- [onPageShow](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onpageshow)：页面每次显示时触发一次，包括路由过程、应用进入前台等场景。 - -- [onPageHide](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onpagehide)：页面每次隐藏时触发一次，包括路由过程、应用进入后台等场景。 - -- [onBackPress](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onbackpress)：当用户点击返回按钮时触发。 +- [aboutToAppear](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)：组件即将出现时回调该接口，具体时机为在创建自定义组件的新实例后，在执行其build函数之前执行。 - -组件生命周期，即一般用\@Component装饰的自定义组件的生命周期，提供以下生命周期接口： - - -- [aboutToAppear](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)：组件即将出现时回调该接口，具体时机为在创建自定义组件的新实例后，在执行其build()函数之前执行。 - -- [onDidBuild](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#ondidbuild12)：组件build()函数执行完成之后回调该接口，开发者可以在这个阶段进行埋点数据上报等不影响实际UI的功能。不建议在onDidBuild函数中更改状态变量、使用animateTo等功能，这可能会导致不稳定的UI表现。 +- [onDidBuild](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#ondidbuild12)：在组件首次渲染触发的build函数执行完成之后回调该接口，后续组件重新渲染将不回调该接口。开发者可以在这个阶段进行埋点数据上报等不影响实际UI的功能。不建议在onDidBuild函数中更改状态变量、使用animateTo等功能，这可能会导致不稳定的UI表现。 - [aboutToDisappear](../../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttodisappear)：aboutToDisappear函数在自定义组件析构销毁之前执行。不允许在aboutToDisappear函数中改变状态变量，特别是@Link变量的修改可能会导致应用程序行为不稳定。 +> **说明：** +> +> 页面生命周期及其相关内容参考[页面路由](../arkts-routing.md#生命周期)。 -生命周期流程如下图所示，下图展示的是被\@Entry装饰的组件（页面）生命周期。 +自定义组件生命周期流程如下图所示。 -![zh-cn_image_0000001502372786](figures/zh-cn_image_0000001502372786.png) +![custom-component-lifecycle-demo1](figures/custom-component-lifecycle-demo1.png) -根据上面的流程图，我们从自定义组件的初始创建、重新渲染和删除来详细说明。 +根据上面的流程图，接下来从自定义组件的初始创建、重新渲染和删除来详细说明。 ## 自定义组件的创建和渲染流程 @@ -52,67 +36,47 @@ ## 自定义组件重新渲染 -当事件句柄被触发（比如设置了点击事件，即触发点击事件）改变了状态变量时，或者LocalStorage / AppStorage中的属性更改，并导致绑定的状态变量更改其值时： +当触发事件（比如点击）改变状态变量时，或者LocalStorage / AppStorage中的属性更改，并导致绑定的状态变量更改其值时： 1. 框架观察到变化，启动重新渲染。 -2. 根据框架持有的两个map（[自定义组件的创建和渲染流程](#自定义组件的创建和渲染流程)中第4步），框架知道状态变量管理的UI组件及其更新函数。执行这些更新函数，实现最小化更新。 +2. 根据框架记录的状态变量和组件的映射关系，仅刷新发生变化的状态变量所关联的组件，实现最小化更新。 ## 自定义组件的删除 -如果if组件的分支改变或ForEach循环渲染中数组的个数改变，组件将被移除： +例如if组件的分支改变或ForEach循环渲染中数组的个数改变，组件将被移除： -1. 在删除组件之前，将调用其aboutToDisappear生命周期函数，标记着该节点将要被销毁。ArkUI的节点删除机制是：后端节点直接从组件树上摘下，后端节点被销毁，对前端节点解引用，前端节点已经没有引用时，将被JS虚拟机垃圾回收。 +1. 在删除组件之前，将调用其aboutToDisappear生命周期函数，标记着该节点将要被销毁。ArkUI的节点删除机制是：后端节点直接从组件树上摘下，后端节点被销毁，对前端节点解引用，前端节点已经没有引用时，将被Ark虚拟机垃圾回收。 2. 自定义组件和它的变量将被删除，如果组件有同步的变量（如[@Link](arkts-link.md)、[@Prop](arkts-prop.md)、[@StorageLink](arkts-appstorage.md#storagelink)），将从[同步源](arkts-state-management-overview.md#基本概念)上取消注册。 不建议在生命周期`aboutToDisappear`中使用`async await`。如果在此生命周期中使用异步操作（如 Promise 或回调方法），自定义组件将被保留在Promise的闭包中，直到回调方法执行完毕，这会阻止自定义组件的垃圾回收。 -以下示例展示了生命周期的调用时机： +## 自定义组件嵌套使用与示例 -> **说明：** -> -> 当前router接口已不推荐使用，此处为更直观体现页面和自定义组件生命周期之间的时序关系，才使用router进行页面路由跳转。 +通过以下示例，来详细说明自定义组件在嵌套使用时，自定义组件生命周期的调用时序： ```ts // Index.ets @Entry @Component -struct MyComponent { +struct Parent { @State showChild: boolean = true; @State btnColor: string = "#FF007DFF"; - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onPageShow() { - console.info('Index onPageShow'); - } - - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onPageHide() { - console.info('Index onPageHide'); - } - - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onBackPress() { - console.info('Index onBackPress'); - this.btnColor = "#FFEE0606"; - // 返回true表示页面自己处理返回逻辑，不进行页面路由；返回false表示使用默认的路由返回逻辑，不设置返回值按照false处理 - return true; - } - // 组件生命周期 aboutToAppear() { - console.info('MyComponent aboutToAppear'); + console.info('Parent aboutToAppear'); } // 组件生命周期 onDidBuild() { - console.info('MyComponent onDidBuild'); + console.info('Parent onDidBuild'); } // 组件生命周期 aboutToDisappear() { - console.info('MyComponent aboutToDisappear'); + console.info('Parent aboutToDisappear'); } build() { @@ -126,12 +90,8 @@ struct MyComponent { .backgroundColor(this.btnColor) .onClick(() => { // 更改this.showChild为false，删除Child子组件，执行Child aboutToDisappear - this.showChild = false; - }) - // push到Page页面，执行onPageHide - Button('push to next page') - .onClick(() => { - this.getUIContext().getRouter().pushUrl({ url: 'pages/Page' }); + // 更改this.showChild为true，添加Child子组件，执行Child aboutToAppear + this.showChild = !this.showChild; }) } } @@ -166,185 +126,43 @@ struct Child { } } ``` -```ts -// Page.ets -@Entry -@Component -struct Page { - @State textColor: Color = Color.Black; - @State num: number = 0; - - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onPageShow() { - console.info('Page onPageShow'); - this.num = 5; - } - - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onPageHide() { - console.info('Page onPageHide'); - } - - // 只有被@Entry装饰的组件才可以调用页面的生命周期 - onBackPress() { // 不设置返回值按照false处理 - console.info('Page onBackPress'); - this.textColor = Color.Grey; - this.num = 0; - } - - // 组件生命周期 - aboutToAppear() { - console.info('Page aboutToAppear'); - this.textColor = Color.Blue; - } - - // 组件生命周期 - onDidBuild() { - console.info('Page onDidBuild'); - } - - // 组件生命周期 - aboutToDisappear() { - console.info('Page aboutToDisappear'); - } - - build() { - Column() { - Text(`num 的值为：${this.num}`) - .fontSize(30) - .fontWeight(FontWeight.Bold) - .fontColor(this.textColor) - .margin(20) - .onClick(() => { - this.num += 5; - }) - } - .width('100%') - } -} -``` -以上示例中，Index页面包含两个自定义组件，一个是被\@Entry装饰的MyComponent，也是页面的入口组件，即页面的根节点；一个是Child，是MyComponent的子组件。只有\@Entry装饰的节点才可以使页面级别的生命周期方法生效，因此在MyComponent中声明当前Index页面的页面生命周期函数（onPageShow / onPageHide / onBackPress）。MyComponent及其子组件Child分别声明了各自的组件级别生命周期函数（aboutToAppear / onDidBuild / aboutToDisappear）。 +以上示例中，Index页面包含两个自定义组件，一个是Parent，一个是Child，Parent及其子组件Child分别声明了各自的自定义组件生命周期函数（aboutToAppear / onDidBuild / aboutToDisappear）。 -- 应用冷启动的初始化流程为：MyComponent aboutToAppear --> MyComponent build --> MyComponent onDidBuild --> Child aboutToAppear --> Child build --> Child onDidBuild --> Index onPageShow。此处体现了自定义组件懒展开特性，即MyComponent执行完onDidBuild之后才会执行Child组件的aboutToAppear。日志输出信息如下： +- 应用冷启动的初始化流程为：Parent aboutToAppear --> Parent build --> Parent onDidBuild --> Child aboutToAppear --> Child build --> Child onDidBuild。此处体现了自定义组件懒展开特性，即Parent执行完onDidBuild之后才会执行Child组件的aboutToAppear。日志输出信息如下： ```ts -MyComponent aboutToAppear -MyComponent onDidBuild +Parent aboutToAppear +Parent onDidBuild Child aboutToAppear Child onDidBuild -Index onPageShow ``` -- 点击“delete Child”，设置this.showChild为false，删除Child组件，执行Child aboutToDisappear方法。 +- 点击Button按钮，更改showChild为false，删除Child组件，执行Child aboutToDisappear方法。 -- 点击“push to next page”，调用this.getUIContext().getRouter().pushUrl({ url: 'pages/Page' })接口，跳转到另外一个页面，当前Index页面隐藏，执行页面生命周期Index onPageHide。此处调用的是pushUrl接口，Index页面被隐藏，并没有销毁，所以只调用onPageHide。跳转到新页面后，执行初始化新页面的生命周期的流程。 - -- 如果调用的是this.getUIContext().getRouter().replaceUrl({ url: 'pages/Page' })，则当前Index页面被销毁，上文已经提到，组件的销毁是从组件树上直接摘下子树，所以执行的生命周期流程将变为：Page aboutToAppear --> Page build --> Page onDidBuild --> Index onPageHide --> Page onPageShow --> MyComponent aboutToDisappear --> Child aboutToDisappear。此时日志输出信息如下： +- 如果直接退出应用，则会触发以下生命周期：Parent aboutToDisappear --> Child aboutToDisappear，此处体现了自定义组件删除顺序也是从父到子。日志输出信息如下： ```ts -Page aboutToAppear -Page onDidBuild -Index onPageHide -Page onPageShow -MyComponent aboutToDisappear +Parent aboutToDisappear Child aboutToDisappear ``` -- 如果当前页面在Index页，点击返回按钮，触发页面生命周期Index onBackPress，若onBackPress使用默认false返回值，则触发返回后会导致当前Index页面被隐藏，执行页面生命周期onPageHide。此时日志输出信息如下： +- 最小化应用或者应用进入后台，当前Index页面未被销毁，所以并不会执行组件的aboutToDisappear。 -```ts -Index onBackPress -Index onPageHide -``` - -- 如果当前页面在Page页，点击返回按钮，触发页面生命周期Page onBackPress，若onBackPress使用默认false返回值，则触发返回后会导致当前Page页面被销毁，执行页面生命周期onPageHide和组件生命周期aboutToDisappear。此时日志输出信息如下： +- 如果showChild的默认值为false，则应用冷启动的初始化流程为：Parent aboutToAppear --> Parent build --> Parent onDidBuild。日志输出信息如下： ```ts -Page onBackPress -Page onPageHide -Index onPageShow -Page aboutToDisappear +Parent aboutToAppear +Parent onDidBuild ``` +- 如果showChild的默认值为false，直接退出应用，则只执行Parent aboutToDisappear方法。 -- 最小化应用或者应用进入后台，触发Index onPageHide。当前Index页面未被销毁，所以并不会执行组件的aboutToDisappear。应用回到前台，执行Index onPageShow。 - -- 退出应用时，触发以下生命周期：Index onPageHide --> MyComponent aboutToDisappear --> Child aboutToDisappear。 - -## 自定义组件监听页面生命周期 - -使用[无感监听页面路由](../../reference/apis-arkui/js-apis-arkui-observer.md#uiobserveronrouterpageupdate11)的能力，能够实现在自定义组件中监听页面的生命周期。 +- 如果showChild的默认值为false，此时点击Button按钮，更改showChild为true，添加Child组件，添加流程为：Child aboutToAppear --> Child build --> Child onDidBuild。日志输出信息如下： ```ts -// Index.ets -import { uiObserver, UIObserver } from '@kit.ArkUI'; - -@Entry -@Component -struct Index { - listener: (info: uiObserver.RouterPageInfo) => void = (info: uiObserver.RouterPageInfo) => { - let routerInfo: uiObserver.RouterPageInfo | undefined = this.queryRouterPageInfo(); - if (info.pageId == routerInfo?.pageId) { - if (info.state == uiObserver.RouterPageState.ON_PAGE_SHOW) { - console.log(`Index onPageShow`); - } else if (info.state == uiObserver.RouterPageState.ON_PAGE_HIDE) { - console.log(`Index onPageHide`); - } - } - } - - aboutToAppear(): void { - let uiObserver: UIObserver = this.getUIContext().getUIObserver(); - uiObserver.on('routerPageUpdate', this.listener); - } - - aboutToDisappear(): void { - let uiObserver: UIObserver = this.getUIContext().getUIObserver(); - uiObserver.off('routerPageUpdate', this.listener); - } - - build() { - Column() { - Text(`this page is ${this.queryRouterPageInfo()?.pageId}`) - .fontSize(25) - Button("push self") - .onClick(() => { - this.getUIContext().getRouter().pushUrl({ url: 'pages/Index' }); - }) - Column() { - SubComponent() - } - } - } -} - -@Component -struct SubComponent { - listener: (info: uiObserver.RouterPageInfo) => void = (info: uiObserver.RouterPageInfo) => { - let routerInfo: uiObserver.RouterPageInfo | undefined = this.queryRouterPageInfo(); - if (info.pageId == routerInfo?.pageId) { - if (info.state == uiObserver.RouterPageState.ON_PAGE_SHOW) { - console.log(`SubComponent onPageShow`); - } else if (info.state == uiObserver.RouterPageState.ON_PAGE_HIDE) { - console.log(`SubComponent onPageHide`); - } - } - } - - aboutToAppear(): void { - let uiObserver: UIObserver = this.getUIContext().getUIObserver(); - uiObserver.on('routerPageUpdate', this.listener); - } - - aboutToDisappear(): void { - let uiObserver: UIObserver = this.getUIContext().getUIObserver(); - uiObserver.off('routerPageUpdate', this.listener); - } - - build() { - Column() { - Text(`SubComponent`) - } - } -} +Child aboutToAppear +Child onDidBuild ``` +当showchild为默认值true时，该示例的生命周期流程图如下所示： + +![custom-component-lifecycle-demo2](figures/custom-component-lifecycle-demo2.png) \ No newline at end of file diff --git a/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo1.png b/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo1.png new file mode 100644 index 0000000000000000000000000000000000000000..e8826a8a6228015f94cbbfc006ee7f36348361de Binary files /dev/null and b/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo1.png differ diff --git a/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo2.png b/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo2.png new file mode 100644 index 0000000000000000000000000000000000000000..c30046e512c2e4ac86e4d90971b27dae3bab4f5b Binary files /dev/null and b/zh-cn/application-dev/ui/state-management/figures/custom-component-lifecycle-demo2.png differ diff --git a/zh-cn/application-dev/ui/state-management/figures/zh-cn_image_0000001502372786.png b/zh-cn/application-dev/ui/state-management/figures/zh-cn_image_0000001502372786.png deleted file mode 100644 index 80116ae255d909e9a8b1af8019a940b4548bd64d..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/ui/state-management/figures/zh-cn_image_0000001502372786.png and /dev/null differ