• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.arkui.observer (Observer)
2
3The **Observer** module provides APIs for listening for UI component behavior changes.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
8>
9
10## Modules to Import
11
12```ts
13import observer from '@ohos.arkui.observer'
14```
15
16## NavDestinationState
17
18Describes the state of the **\<NavDestination>** component.
19
20**System capability**: SystemCapability.ArkUI.ArkUI.Full
21
22| Name     | Value | Description                    |
23| --------- | --- | ------------------------ |
24| ON_SHOWN  | 0   | The **\<NavDestination>** component is displayed.|
25| ON_HIDDEN | 1   | The **\<NavDestination>** component is hidden.|
26
27## RouterPageState
28
29Enumerates the states of a page during routing.
30
31**System capability**: SystemCapability.ArkUI.ArkUI.Full
32
33| Name             | Value | Description                   |
34| ----------------- | --- | ----------------------- |
35| ABOUT_TO_APPEAR       | 0   | The page is about to be displayed.           |
36| ABOUT_TO_DISAPPEAR    | 1   | The page is about to be destroyed.           |
37| ON_PAGE_SHOW          | 2   | The page is displayed.               |
38| ON_PAGE_HIDE          | 3   | The page is hidden.               |
39| ON_BACK_PRESS         | 4   | The page is returned.             |
40
41## NavDestinationInfo
42
43Provides information about the **\<NavDestination>** component.
44
45**System capability**: SystemCapability.ArkUI.ArkUI.Full
46
47| Name        | Type                                              | Mandatory| Description                                        |
48| ------------ | -------------------------------------------------- | ---- | -------------------------------------------- |
49| navigationId | [ResourceStr](../arkui-ts/ts-types.md#resourcestr) | Yes  | ID of the **\<Navigation>** component that contains the target **\<NavDestination>** component.|
50| name         | [ResourceStr](../arkui-ts/ts-types.md#resourcestr) | Yes  | Name of the **\<NavDestination>** component.                  |
51| state        | [NavDestinationState](#navdestinationstate)        | Yes  | State of the **\<NavDestination>** component.                  |
52
53## RouterPageInfo
54
55Provides the information about a page during routing.
56
57**System capability**: SystemCapability.ArkUI.ArkUI.Full
58
59| Name        | Type                                              | Mandatory| Description                                         |
60| ------------ | -------------------------------------------------- | ---- | -------------------------------------------- |
61| context      | [UIAbilityContext](./js-apis-inner-application-uiAbilityContext.md) / [UIContext](./js-apis-arkui-UIContext.md) | Yes  | Context of the page that invokes the lifecycle callback.|
62| index        | number                                             | Yes  | Position of the page that invokes the lifecycle callback, in the navigation stack.        |
63| name         | string                                             | Yes  | Name of the page that invokes the lifecycle callback.          |
64| path         | string                                             | Yes  | Path of the page that invokes the lifecycle callback.          |
65| state        | [RouterPageState](#routerpagestate)                | Yes  | State of the page that invokes the lifecycle callback.            |
66
67## observer.on('navDestinationUpdate')
68
69on(type: 'navDestinationUpdate', callback: Callback\<NavDestinationInfo\>): void
70
71Subscribes to status changes of the **\<NavDestination>** component.
72
73**System capability**: SystemCapability.ArkUI.ArkUI.Full
74
75**Parameters**
76
77| Name  | Type                                                 | Mandatory| Description                                                                    |
78| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------------------ |
79| type     | string                                                | Yes  | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the status change event of the **\<NavDestination>** component.|
80| callback | Callback\<[NavDestinationInfo](#navdestinationinfo)\> | Yes  | Callback used to return the current state of the **\<NavDestination>** component.                            |
81
82**Example**
83
84```ts
85observer.on('navDestinationUpdate', (info) => {
86    console.info('NavDestination state update', JSON.stringify(info));
87});
88```
89
90## observer.off('navDestinationUpdate')
91
92off(type: 'navDestinationUpdate', callback?: Callback\<NavDestinationInfo\>): void
93
94Unsubscribes from status changes of the **\<NavDestination>** component.
95
96**System capability**: SystemCapability.ArkUI.ArkUI.Full
97
98**Parameters**
99
100| Name  | Type                                                 | Mandatory| Description                                                                    |
101| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------------------ |
102| type     | string                                                | Yes  | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the status change event of the **\<NavDestination>** component.|
103| callback | Callback\<[NavDestinationInfo](#navdestinationinfo)\> | No  | Callback used to return the current state of the **\<NavDestination>** component.                            |
104
105**Example**
106
107```ts
108observer.off('navDestinationUpdate');
109```
110
111## observer.on('navDestinationUpdate')
112
113on(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback: Callback\<NavDestinationInfo\>): void
114
115Subscribes to status changes of the **\<NavDestination>** component.
116
117**System capability**: SystemCapability.ArkUI.ArkUI.Full
118
119**Parameters**
120
121| Name  | Type                                                                | Mandatory| Description                                                                    |
122| -------- | -------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------ |
123| type     | string                                                               | Yes  | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the status change event of the **\<NavDestination>** component.|
124| options  | { navigationId: [ResourceStr](../arkui-ts/ts-types.md#resourcestr) } | Yes  | ID of the **\<Navigation>** component that contains the target **\<NavDestination>** component.                                              |
125| callback | Callback\<[NavDestinationInfo](#navdestinationinfo)\>                | Yes  | Callback used to return the current state of the **\<NavDestination>** component.                            |
126
127**Example**
128
129```ts
130observer.on('navDestinationUpdate', { navigationId: "testId" }, (info) => {
131    console.info('NavDestination state update', JSON.stringify(info));
132});
133```
134
135## observer.off('navDestinationUpdate')
136
137off(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback?: Callback\<NavDestinationInfo\>): void
138
139Unsubscribes from status changes of the **\<NavDestination>** component.
140
141**System capability**: SystemCapability.ArkUI.ArkUI.Full
142
143**Parameters**
144
145| Name  | Type                                                                | Mandatory| Description                                                                    |
146| -------- | -------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------ |
147| type     | string                                                               | Yes  | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the status change event of the **\<NavDestination>** component.|
148| options  | { navigationId: [ResourceStr](../arkui-ts/ts-types.md#resourcestr) } | Yes  | ID of the **\<Navigation>** component that contains the target **\<NavDestination>** component.                                              |
149| callback | Callback\<[NavDestinationInfo](#navdestinationinfo)\>                | No  | Callback used to return the current state of the **\<NavDestination>** component.                            |
150
151**Example**
152
153```ts
154observer.off('navDestinationUpdate', { navigationId: "testId" });
155```
156
157## observer.on('routerPageUpdate')<sup>11+</sup>
158
159on(type: 'routerPageUpdate', context: UIAbilityContext | UIContext, callback: Callback\<observer.RouterPageInfo\>): void
160
161Subscribes to state changes of the page during routing.
162
163**System capability**: SystemCapability.ArkUI.ArkUI.Full
164
165**Parameters**
166
167| Name  | Type                                                        | Mandatory| Description                                                        |
168| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
169| type     | string                                                       | Yes  | Event type. The value is fixed at **'routerPageUpdate'**, which indicates the state change event of the page during routing.|
170| context  | [UIAbilityContext](./js-apis-inner-application-uiAbilityContext.md) / [UIContext](./js-apis-arkui-UIContext.md) | Yes  | Context information, which is used to specify the scope of the page to be listened for.|
171| callback | Callback\<[RouterPageInfo](#routerpageinfo)\>        | Yes  | Callback used to return the If **pageInfo** is passed, the current page state is returned.                |
172
173**Example**
174
175```ts
176// used in UIAbility
177import observer from '@ohos.arkui.observer';
178// callBackFunc is user defined function
179observer.on('routerPageUpdate', this.context, callBackFunc);
180// uiContext could be got by window's function: getUIContext()
181observer.on('routerPageUpdate', this.uiContext, callBackFunc);
182```
183
184## observer.off('routerPageUpdate')<sup>11+</sup>
185
186off(type: 'routerPageUpdate', context: UIAbilityContext | UIContext, callback?: Callback\<observer.RouterPageInfo\>): void
187
188Unsubscribes to state changes of the page during routing.
189
190**System capability**: SystemCapability.ArkUI.ArkUI.Full
191
192**Parameters**
193
194| Name  | Type                                                        | Mandatory| Description                                                        |
195| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
196| type     | string                                                       | Yes  | Event type. The value is fixed at **'routerPageUpdate'**, which indicates the state change event of the page during routing.|
197| context  | [UIAbilityContext](./js-apis-inner-application-uiAbilityContext.md) / [UIContext](./js-apis-arkui-UIContext.md) | Yes  | Context information, which is used to specify the scope of the page to be listened for.|
198| callback | Callback\<[RouterPageInfo](#routerpageinfo)\>        | No  | Callback to be unregistered.                |
199
200**Example**
201
202```ts
203// used in UIAbility
204import observer from '@ohos.arkui.observer';
205// callBackFunc is user defined function
206observer.off('routerPageUpdate', this.context, callBackFunc);
207// uiContext could be got by window's function: getUIContext()
208observer.off('routerPageUpdate', this.uiContext, callBackFunc);
209```
210