• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# NavDestination
2
3作为子页面的根容器，用于显示[Navigation](ts-basic-components-navigation.md)的内容区。
4
5> **说明：**
6>
7> - 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9> - 该组件从API Version 11开始默认支持安全区避让特性(默认值为：expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]))，开发者可以重写该属性覆盖默认行为，API Version 11之前的版本需配合[expandSafeArea](ts-universal-attributes-expand-safe-area.md)属性实现安全区避让。
10>
11> - NavDestination组件必须配合Navigation使用，作为Navigation目的页面的根节点，单独使用只能作为普通容器组件，不具备路由相关属性能力。
12>
13> - 如果页面栈中间页面的生命周期发生变化，跳转之前的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)与跳转之后的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)均在最后触发。
14>
15> - NavDestination未设置主副标题并且没有返回键时，不显示标题栏。
16
17## 子组件
18
19> **说明：**
20>
21> - 子组件类型：系统组件和自定义组件，支持渲染控制类型（[if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)和[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)）。
22> - 子组件个数：多个。
23
24
25## 接口
26
27NavDestination()
28
29**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
30
31**系统能力：** SystemCapability.ArkUI.ArkUI.Full
32
33## 属性
34
35支持[通用属性](ts-component-general-attributes.md)。
36
37不推荐设置位置、大小等布局相关属性，可能会造成页面显示异常。
38
39### title
40
41title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle | Resource, options?: NavigationTitleOptions)
42
43设置页面标题。使用NavigationCustomTitle类型设置height高度时，[titleMode](ts-basic-components-navigation.md#titlemode)属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行2行后以...截断。如果设置副标题，先缩小后以...截断。
44
45**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
46
47**系统能力：** SystemCapability.ArkUI.ArkUI.Full
48
49**参数：**
50
51| 参数名 | 类型                                                         | 必填 | 说明       |
52| ------ | ------------------------------------------------------------ | ---- | ---------- |
53| value  | string \| [CustomBuilder](ts-types.md#custombuilder8) \| [NavDestinationCommonTitle](#navdestinationcommontitle) \| [NavDestinationCustomTitle](#navdestinationcustomtitle) \| [Resource](ts-types.md#resource)  | 是   | 页面标题。 |
54| options<sup>12+</sup> | [NavigationTitleOptions](ts-basic-components-navigation.md#navigationtitleoptions11) | 否   | 标题栏选项。 |
55
56### hideTitleBar
57
58hideTitleBar(value: boolean)
59
60设置是否隐藏标题栏。
61
62**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
63
64**系统能力：** SystemCapability.ArkUI.ArkUI.Full
65
66**参数：**
67
68| 参数名 | 类型    | 必填 | 说明                                                         |
69| ------ | ------- | ---- | ------------------------------------------------------------ |
70| value  | boolean | 是   | 是否隐藏标题栏。<br/>默认值：false<br/>true:&nbsp;隐藏标题栏。<br/>false:&nbsp;显示标题栏。 |
71
72### hideTitleBar<sup>13+</sup>
73
74hideTitleBar(hide: boolean, animated: boolean)
75
76设置是否隐藏标题栏，设置是否使用动画显隐标题栏。
77
78**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。
79
80**系统能力：** SystemCapability.ArkUI.ArkUI.Full
81
82**参数：**
83
84| 参数名 | 类型    | 必填 | 说明                                                         |
85| ------ | ------- | ---- | ------------------------------------------------------------ |
86| hide  | boolean | 是   | 是否隐藏标题栏。<br/>默认值：false<br/>true: 隐藏标题栏。<br/>false: 显示标题栏。 |
87| animated  | boolean | 是   | 设置是否使用动画显隐标题栏。<br/>默认值：false<br/>true: 使用动画显示隐藏标题栏。<br/>false: 不使用动画显示隐藏标题栏。 |
88
89### toolbarConfiguration<sup>13+</sup>
90
91toolbarConfiguration(toolbarParam: Array&lt;ToolbarItem&gt; | CustomBuilder, options?: NavigationToolbarOptions)
92
93设置工具栏内容。未调用本接口时不显示工具栏。
94
95**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。
96
97**系统能力：** SystemCapability.ArkUI.ArkUI.Full
98
99**参数：**
100
101| 参数名       | 类型                                                         | 必填 | 说明                                                         |
102| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
103| toolbarParam | &nbsp;Array&lt;[ToolbarItem](ts-basic-components-navigation.md#toolbaritem10)&gt; &nbsp;\|&nbsp;[CustomBuilder](ts-types.md#custombuilder8) | 是   | 工具栏内容。<br/>使用Array&lt;[ToolbarItem](ts-basic-components-navigation.md#toolbaritem10)&gt;写法设置的工具栏有如下特性：<br/>-工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。<br/>-文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，工具栏最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后截断。<br/>-竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标中，点击更多图标，可以展示剩余内容。横屏时，如果为[Split](ts-basic-components-navigation.md#navigationmode9枚举说明)模式，仍按照竖屏规则显示，如果为[Stack](ts-basic-components-navigation.md#navigationmode9枚举说明)模式需配合menus属性的Array&lt;[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)&gt;使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。<br/>使用[CustomBuilder](ts-types.md#custombuilder8)写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。 |
104| options      | [NavigationToolbarOptions](ts-basic-components-navigation.md#navigationtoolbaroptions11) | 否   | 工具栏选项。                                                 |
105
106> **说明：**
107>
108> 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。
109
110### hideToolBar<sup>13+</sup>
111
112hideToolBar(hide: boolean, animated?: boolean)
113
114设置是否隐藏工具栏，设置是否使用动画显隐工具栏。
115
116**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。
117
118**系统能力：** SystemCapability.ArkUI.ArkUI.Full
119
120**参数：**
121
122| 参数名 | 类型    | 必填 | 说明                                                         |
123| ------ | ------- | ---- | ------------------------------------------------------------ |
124| hide  | boolean | 是   | 是否隐藏工具栏。<br/>默认值：false<br/>true: 隐藏工具栏。<br/>false: 显示工具栏。 |
125| animated  | boolean | 否   | 设置是否使用动画显隐工具栏。<br/>默认值：false<br/>true: 使用动画显示隐藏工具栏。<br/>false: 不使用动画显示隐藏工具栏。 |
126
127### mode <sup>11+</sup>
128
129mode(value: NavDestinationMode)
130
131设置NavDestination类型，不支持动态修改。
132
133**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
134
135**系统能力：** SystemCapability.ArkUI.ArkUI.Full
136
137**参数：**
138
139| 参数名 | 类型                                                 | 必填 | 说明                                                         |
140| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
141| value  | [NavDestinationMode](#navdestinationmode枚举说明-11) | 是   | NavDestination类型。<br/>默认值: NavDestinationMode.STANDARD |
142
143### backButtonIcon<sup>11+</sup>
144
145backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)
146
147> **说明：**
148>
149> 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。
150
151
152设置标题栏返回键图标。
153
154**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
155
156**系统能力：** SystemCapability.ArkUI.ArkUI.Full
157
158**参数：**
159
160| 参数名 | 类型                                                         | 必填 | 说明               |
161| ------ | ------------------------------------------------------------ | ---- | ------------------ |
162| value  | [ResourceStr](ts-types.md#resourcestr)&nbsp;\|&nbsp;[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)&nbsp;\|&nbsp;[SymbolGlyphModifier<sup>12+</sup>](ts-universal-attributes-attribute-modifier.md)  | 是   | 标题栏返回键图标。 |
163
164### menus<sup>12+</sup>
165
166menus(value: Array&lt;NavigationMenuItem&gt; | CustomBuilder)
167
168> **说明：**
169>
170> 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。
171
172
173设置页面右上角菜单。不设置时不显示菜单项。使用Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)&gt; 写法时，竖屏最多支持显示3个图标，横屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。
174
175**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
176
177**系统能力：** SystemCapability.ArkUI.ArkUI.Full
178
179**参数：**
180
181| 参数名 | 类型                                                         | 必填 | 说明               |
182| ------ | ------------------------------------------------------------ | ---- | ------------------ |
183| value  | Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)&gt;&nbsp;\|&nbsp;[CustomBuilder](ts-types.md#custombuilder8) | 是   | 页面右上角菜单。 |
184
185### ignoreLayoutSafeArea<sup>12+</sup>
186
187ignoreLayoutSafeArea(types?: Array&lt;LayoutSafeAreaType&gt;, edges?: Array&lt;LayoutSafeAreaEdge&gt;)
188
189控制组件的布局，使其扩展到非安全区域
190
191**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
192
193**系统能力：** SystemCapability.ArkUI.ArkUI.Full
194
195**参数：**
196
197| 参数名 | 类型                                               | 必填 | 说明                                                         |
198| ------ | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
199| types  | Array <[LayoutSafeAreaType](ts-types.md#layoutsafeareatype12)> | 否   | 配置扩展安全区域的类型。<br />默认值: <br />[LayoutSafeAreaType.SYSTEM] |
200| edges  | Array <[LayoutSafeAreaEdge](ts-types.md#layoutsafeareaedge12)> | 否   | 配置扩展安全区域的方向。<br /> 默认值: <br />[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。|
201
202>  **说明：**
203>
204>  组件设置LayoutSafeArea之后生效的条件为：
205>  设置LayoutSafeAreaType.SYSTEM时，组件的边界与非安全区域重合时组件能够延伸到非安全区域下。例如：设备顶部状态栏高度100，组件在屏幕中纵向方位的绝对偏移需要在0到100之间。
206>
207>  若组件延伸到非安全区域内，此时在非安全区域里触发的事件（例如：点击事件）等可能会被系统拦截，优先响应状态栏等系统组件。
208
209### systemBarStyle<sup>12+</sup>
210
211systemBarStyle(style: Optional&lt;SystemBarStyle&gt;)
212
213当Navigation中显示当前NavDestination时，设置对应系统状态栏的样式。
214
215**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
216
217**系统能力：** SystemCapability.ArkUI.ArkUI.Full
218
219**参数：**
220
221| 参数名 | 类型         | 必填 | 说明               |
222| ------ | -------------- | ---- | ------------------ |
223| style  | [Optional](ts-universal-attributes-custom-property.md#optional12)&lt;[SystemBarStyle](../js-apis-window.md#systembarstyle12)&gt; | 是   | 系统状态栏样式。 |
224
225> **说明：**
226>
227> 1. 必须配合Navigation使用，作为其Navigation目的页面的根节点时才能生效。
228> 2. 其他使用限制请参考Navigation对应的[systemBarStyle](ts-basic-components-navigation.md#systembarstyle12)属性说明。
229
230### systemTransition<sup>14+</sup>
231systemTransition(type: NavigationSystemTransitionType)
232
233设置NavDestination系统转场动画，支持分别设置系统标题栏动画和内容动画。
234
235**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。
236
237**系统能力：** SystemCapability.ArkUI.ArkUI.Full
238
239**参数：**
240
241| 参数名 | 类型                                                 | 必填 | 说明                                                         |
242| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
243| type  | [NavigationSystemTransitionType](#navigationsystemtransitiontype14枚举说明) | 是   | 系统转场动画类型。<br/>默认值: NavigationSystemTransitionType.DEFAULT |
244
245### recoverable<sup>14+</sup>
246
247recoverable(recoverable: Optional&lt;boolean&gt;)
248
249配置NavDestination是否可恢复。如配置为可恢复，当应用进程异常退出并重新冷启动时，可自动创建该NavDestination。该功能需NavDestination对应的Navigation也配置了可恢复属性。
250
251**系统能力：** SystemCapability.ArkUI.ArkUI.Full
252
253**参数：**
254
255| 参数名 | 类型         | 必填 | 说明               |
256| ------ | -------------- | ---- | ------------------ |
257| recoverable  | [Optional](ts-universal-attributes-custom-property.md#optional12)&lt;boolean&gt; | 是   | NavDestination是否可恢复，默认为不可恢复。<br/>默认值:false<br/>true:页面栈可恢复。<br/>false:页面栈不可恢复。 |
258
259>  **使用说明：**
260>
261> 该接口需要配合Navigation的[recoverable](./ts-basic-components-navigation.md#recoverable14)接口使用。
262
263### bindToScrollable<sup>14+</sup>
264bindToScrollable(scrollers: Array&lt;Scroller&gt;)
265
266绑定NavDestination组件和可滚动容器组件（支持[List](./ts-container-list.md)、[Scroll](./ts-container-scroll.md)、[Grid](./ts-container-grid.md)、[WaterFlow](./ts-container-waterflow.md)），当滑动可滚动容器组件时，会触发所有与其绑定的NavDestination组件的标题栏和工具栏的显示和隐藏动效，上滑隐藏，下滑显示。一个NavDestination可与多个可滚动容器组件绑定，一个可滚动容器组件也可与多个NavDestination绑定。使用示例参见[示例1](#示例1)。
267
268> **说明：**
269>
270> - 只有NavDestination的标题栏或工具栏设置为可见时，联动效果才会生效。
271> - 当多个可滚动容器组件绑定了同一个NavDestination组件时，滚动任何一个容器都会触发标题栏和工具栏的显示或隐藏效果。且当任何一个可滚动容器组件滑动到底部或顶部位置时，会立即触发标题栏和工具栏的显示动效。因此，为了获得最佳用户体验，不建议同时触发多个可滚动容器组件的滚动事件。
272
273**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。
274
275**系统能力：** SystemCapability.ArkUI.ArkUI.Full
276
277**参数：**
278
279| 参数名 | 类型                                                 | 必填 | 说明                                                         |
280| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
281| scrollers | Array<[Scroller](./ts-container-scroll.md#scroller)> | 是   | 可滚动容器组件的控制器。 |
282
283### bindToNestedScrollable<sup>14+</sup>
284bindToNestedScrollable(scrollInfos: Array&lt;NestedScrollInfo&gt;)
285
286绑定NavDestination组件和嵌套的可滚动容器组件（支持[List](./ts-container-list.md)、[Scroll](./ts-container-scroll.md)、[Grid](./ts-container-grid.md)、[WaterFlow](./ts-container-waterflow.md)），当滑动父组件或子组件时，会触发所有与其绑定的NavDestination组件的标题栏和工具栏的显示和隐藏动效，上滑隐藏，下滑显示。一个NavDestination可与多个嵌套的可滚动容器组件绑定，嵌套的可滚动容器组件也可与多个NavDestination绑定。使用示例参见[示例1](#示例1)。
287
288> **说明：**
289>
290> - 只有NavDestination的标题栏或工具栏设置为可见时，联动效果才会生效。
291> - 当多个可滚动容器组件绑定了同一个NavDestination组件时，滚动任何一个容器都会触发标题栏和工具栏的显示或隐藏效果。且当任何一个可滚动容器组件滑动到底部或顶部位置时，会立即触发标题栏和工具栏的显示动效。因此，为了获得最佳用户体验，不建议同时触发多个可滚动容器组件的滚动事件。
292
293**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。
294
295**系统能力：** SystemCapability.ArkUI.ArkUI.Full
296
297**参数：**
298
299| 参数名 | 类型                                                 | 必填 | 说明                                                         |
300| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
301| scrollInfos | Array<[NestedScrollInfo](#nestedscrollinfo14)> | 是   | 嵌套的可滚动容器组件的控制器。 |
302
303### hideBackButton<sup>15+</sup>
304
305hideBackButton(hide: Optional&lt;boolean&gt;)
306
307设置是否隐藏标题栏中的返回键。
308
309**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
310
311**系统能力：** SystemCapability.ArkUI.ArkUI.Full
312
313**参数：**
314
315| 参数名 | 类型    | 必填 | 说明                                                         |
316| ------ | ------- | ---- | ------------------------------------------------------------ |
317| hide  | [Optional](ts-universal-attributes-custom-property.md#optional12)&lt;boolean&gt; | 是   | 是否隐藏标题栏中的返回键。 <br/>默认值：false<br/>true: 隐藏返回键。<br/>false: 显示返回键。 |
318
319### customTransition<sup>15+</sup>
320
321customTransition(delegate: NavDestinationTransitionDelegate)
322
323设置NavDestination自定义转场动画。
324
325> **说明：**
326>
327> 该属性与[systemTransition](#systemtransition14)同时设置时，后设置的属性生效。
328
329**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
330
331**系统能力：** SystemCapability.ArkUI.ArkUI.Full
332
333**参数：**
334
335| 参数名 | 类型    | 必填 | 说明                                                         |
336| ------ | ------- | ---- | ------------------------------------------------------------ |
337| delegate  | [NavDestinationTransitionDelegate](#navdestinationtransitiondelegate15) | 是   | NavDestination自定义动画的代理函数。 |
338
339## NavDestinationMode枚举说明 <sup>11+</sup>
340
341**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
342
343**系统能力：** SystemCapability.ArkUI.ArkUI.Full
344
345| 名称   | 值 | 说明                                     |
346| ---- | --- | ---------------------------------------- |
347| STANDARD | 0 | 标准模式的NavDestination。                       |
348| DIALOG | 1 | 默认透明，进出页面栈不影响下层NavDestination的生命周期。<br />API version 13之前，默认无系统转场动画。从API version 13开始，支持系统转场动画。  |
349
350## NavigationSystemTransitionType<sup>14+</sup>枚举说明
351
352**系统能力：** SystemCapability.ArkUI.ArkUI.Full
353
354| 名称   | 值   | 说明 |
355| ----  | ---   | ----- |
356| DEFAULT | 0 | 默认系统转场动画。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。|
357| NONE| 1 | 无系统转场动画。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。|
358| TITLE | 2 | 标题栏系统转场动画。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。|
359| CONTENT | 3 | 内容区系统转场动画。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。|
360| FADE<sup>15+</sup> | 4 | 渐变类型的系统转场动画。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 |
361| EXPLODE<sup>15+</sup> | 5 | 中心缩放类型的系统转场动画。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 |
362| SLIDE_RIGHT<sup>15+</sup> | 6 | 右侧平移类型的系统转场动画。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 |
363| SLIDE_BOTTOM<sup>15+</sup> | 7 | 底部平移类型的系统转场动画。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 |
364
365**说明：**
366>
367> 设置系统转场动画，支持分别设置系统标题栏动画和内容动画。
368>
369> 系统默认转场动画中只有STANDARD页面的push和pop动画有单独的标题栏动画，存在如下限制：
370> 1. 设置NavigationSystemTransitionType为TITLE时，系统转场只有标题栏动画。
371> 2. 设置NavigationSystemTransitionType为CONTENT时，系统转场只有内容区动画。
372>
373> 设置NONE或者TITLE时没有系统转场动画，设置CONTENT和DEFAULT时默认系统转场动画。
374
375## 事件
376
377除支持[通用事件](ts-component-general-events.md)外，还支持如下事件：
378
379### onShown<sup>10+</sup>
380
381onShown(callback:&nbsp;()&nbsp;=&gt;&nbsp;void)
382
383当该NavDestination页面显示时触发此回调。
384
385**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
386
387**系统能力：** SystemCapability.ArkUI.ArkUI.Full
388
389### onHidden<sup>10+</sup>
390
391onHidden(callback:&nbsp;()&nbsp;=&gt;&nbsp;void)
392
393当该NavDestination页面隐藏时触发此回调。
394
395**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
396
397**系统能力：** SystemCapability.ArkUI.ArkUI.Full
398
399### onWillAppear<sup>12+</sup>
400
401onWillAppear(callback: Callback\<void>)
402
403当该Destination挂载之前触发此回调。在该回调中允许修改页面栈，当前帧生效。
404
405**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
406
407**系统能力：** SystemCapability.ArkUI.ArkUI.Full
408
409### onWillShow<sup>12+</sup>
410
411onWillShow(callback: Callback\<void>)
412
413当该Destination显示之前触发此回调。
414
415**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
416
417**系统能力：** SystemCapability.ArkUI.ArkUI.Full
418
419### onWillHide<sup>12+</sup>
420
421onWillHide(callback: Callback\<void>)
422
423当该Destination隐藏之前触发此回调。
424
425**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
426
427**系统能力：** SystemCapability.ArkUI.ArkUI.Full
428
429### onWillDisappear<sup>12+</sup>
430
431onWillDisappear(callback: Callback\<void>)
432
433当该Destination卸载之前触发的生命周期(有转场动画时，在转场动画开始之前触发)。
434
435**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
436
437**系统能力：** SystemCapability.ArkUI.ArkUI.Full
438
439### onBackPressed<sup>10+</sup>
440
441onBackPressed(callback:&nbsp;()&nbsp;=&gt;&nbsp;boolean)
442
443当与Navigation绑定的页面栈中存在内容时，此回调生效。当点击返回键时，触发该回调。
444
445返回值为true时，表示重写返回键逻辑，返回值为false时，表示回退到上一个页面。
446
447**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
448
449**系统能力：** SystemCapability.ArkUI.ArkUI.Full
450
451### onReady<sup>11+</sup>
452
453onReady(callback:&nbsp;[Callback](../../apis-basic-services-kit/js-apis-base.md#callback)<[NavDestinationContext](#navdestinationcontext11)>)
454
455当NavDestination即将构建子组件之前会触发此回调。
456
457**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
458
459**系统能力：** SystemCapability.ArkUI.ArkUI.Full
460
461### onResult<sup>15+</sup>
462
463onResult(callback:&nbsp;Optional\<Callback\<ESObject\>\>)
464
465NavDestination返回时触发该回调。
466
467**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
468
469**系统能力：** SystemCapability.ArkUI.ArkUI.Full
470
471**参数：**
472| 参数名 | 类型 | 必填 | 说明 |
473| ------ | ------ | ---- | ---------------- |
474|callback | [Optional](./ts-universal-attributes-custom-property.md)\<[Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<ESObject\>\>| 是 | 页面返回回调， 入参为pop接口传入的result参数。如果不传该参数，入参为undefined。|
475
476## NavDestinationCommonTitle
477
478**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
479
480**系统能力：** SystemCapability.ArkUI.ArkUI.Full
481
482| 名称   | 类型     | 必填   | 说明     |
483| ---- | ------ | ---- | ------ |
484| main | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | 是    | 设置主标题。 |
485| sub  | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | 是    | 设置副标题。 |
486
487## NavDestinationCustomTitle
488
489**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
490
491**系统能力：** SystemCapability.ArkUI.ArkUI.Full
492
493| 名称      | 类型                                       | 必填   | 说明       |
494| ------- | ---------------------------------------- | ---- | -------- |
495| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是    | 设置标题栏内容。 |
496| height  | [TitleHeight](ts-appendix-enums.md#titleheight9) \| [Length](ts-types.md#length) | 是    | 设置标题栏高度。 |
497
498## NavDestinationContext<sup>11+</sup>
499
500**系统能力：** SystemCapability.ArkUI.ArkUI.Full
501
502| 名称   | 类型     | 必填   |  说明     |
503| ---- | ------ | ----- | ------ |
504| pathInfo | [NavPathInfo](ts-basic-components-navigation.md#navpathinfo10) | 是 | 跳转NavDestination时指定的参数。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
505| pathStack  | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | 是 | 当前NavDestination所处的页面栈。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
506| navDestinationId<sup>12+</sup> | string | 否 | 当前NavDestination的唯一ID，由系统自动生成，和组件通用属性id无关。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。|
507
508### getConfigInRouteMap<sup>12+</sup>
509
510getConfigInRouteMap(): RouteMapConfig |undefined
511
512**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
513
514**系统能力：** SystemCapability.ArkUI.ArkUI.Full
515
516**返回值**
517
518| 类型 | 说明 |
519| --- | --- |
520| [RouteMapConfig](#routemapconfig12) | 当前页面路由配置信息。 |
521| undefined | 当该页面不是通过路由表配置时返回undefined。 |
522
523## RouteMapConfig<sup>12+</sup>
524
525**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
526
527**系统能力：** SystemCapability.ArkUI.ArkUI.Full
528
529| 名称   | 类型   |必填 | 说明 |
530| ----  | ---   | ---- |----- |
531| name  | string | 是 | 页面名称。|
532| pageSourceFile| string | 是 | 页面在当前包中的路径。|
533| data | Object | 是 | 页面自定义字段信息。|
534
535## NestedScrollInfo<sup>14+</sup>
536
537嵌套可滚动容器组件信息
538
539**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。
540
541**系统能力：** SystemCapability.ArkUI.ArkUI.Full
542
543| 名称   | 类型   |必填 | 说明 |
544| ----  | ---   | ---- |----- |
545| parent | [Scroller](./ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。 |
546| child | [Scroller](./ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器，child对应的组件需要是parent对应组件的子组件，且组件间存在嵌套滚动关系。|
547
548## NavDestinationTransition<sup>15+</sup>
549
550NavDestination自定义动画接口。
551
552**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
553
554**系统能力：** SystemCapability.ArkUI.ArkUI.Full
555
556| 名称   | 类型   |必填 | 说明 |
557| ----  | ---   | ---- |----- |
558| onTransitionEnd | Callback\<void> | 否 | 转场动画结束时的回调函数。 |
559| duration | number | 否 | 转场动画的持续时间，默认值为1000（毫秒）。 |
560| curve | [Curve](ts-appendix-enums.md#curve) | 否 | 动画的曲线类型，默认值为[Curve.EaseInOut](ts-appendix-enums.md#curve)。 |
561| delay | number | 否 | 转场动画的延迟。默认值为0。 |
562| event | Callback\<void> | 是 | 指定转场动效的闭包函数，系统会根据闭包中对组件UI状态的修改，生成对应的过渡动画。参见[animateTo](../js-apis-arkui-UIContext.md#animateto)中的event。 |
563
564## NavDestinationTransitionDelegate<sup>15+</sup>
565
566type NavDestinationTransitionDelegate = (operation: NavigationOperation, isEnter: boolean) => Array\<NavDestinationTransition> | undefined
567
568NavDestination自定义转场动画的代理函数。
569
570**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
571
572**系统能力：** SystemCapability.ArkUI.ArkUI.Full
573
574**参数：**
575
576| 参数名  | 类型     | 必填 | 说明                    |
577|------|--------|----|-----------------------|
578| operation | [NavigationOperation](ts-basic-components-navigation.md#navigationoperation11枚举说明) | 是  | 当前页面转场的操作类型。 |
579| isEnter | boolean | 是  | 当前页面是否为入场页面。 |
580
581**返回值：**
582
583| 类型      | 说明        |
584|---------|-----------|
585| Array<[NavDestinationTransition](#navdestinationtransition15)> \| undefined | NavDestination页面的自定义动画集合。如果返回undefined则做系统默认动画。 |
586
587## 示例
588
589### 示例1（标题栏工具栏与可滚动类组件联动）
590
591以下示例主要演示NavDestination绑定可滚动容器组件来实现滚动内容时触发标题栏和工具栏显示隐藏的效果。
592
593```ts
594import { SymbolGlyphModifier } from '@kit.ArkUI';
595
596@Component
597struct MyPageOne {
598  private listScroller: Scroller = new Scroller();
599  private scrollScroller: Scroller = new Scroller();
600  private arr: number[] = [];
601
602  aboutToAppear(): void {
603    for (let i = 0; i < 30; i++) {
604      this.arr.push(i);
605    }
606  }
607
608  build() {
609    NavDestination() {
610      Scroll(this.scrollScroller) {
611        Column() {
612          List({ space: 0, initialIndex: 0, scroller: this.listScroller }) {
613            ForEach(this.arr, (item: number, index: number) => {
614              ListItem() {
615                Text('' + item)
616                  .height(100)
617                  .fontSize(16)
618                  .textAlign(TextAlign.Center)
619                  .width('90%')
620                  .margin({ left: '5%' })
621                  .borderRadius(10)
622                  .backgroundColor(Color.Gray)
623              }
624            }, (item: string) => item);
625          }.width('100%').height('80%').scrollBar(BarState.Off)
626          .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST })
627
628          ForEach(this.arr, (item: number, index: number) => {
629            ListItem() {
630              Text('' + item)
631                .height(100)
632                .fontSize(16)
633                .textAlign(TextAlign.Center)
634                .width('90%')
635                .margin({ top: '5%' })
636                .borderRadius(10)
637                .backgroundColor(Color.Pink)
638            }
639          }, (item: string) => item);
640        }
641      }
642      .width('100%')
643      .scrollBar(BarState.Off)
644      .scrollable(ScrollDirection.Vertical)
645      .edgeEffect(EdgeEffect.Spring)
646    }
647    .title('PageOne', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
648    .toolbarConfiguration([
649      {
650        value: 'item1',
651        symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
652      }
653    ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
654    // 绑定有父子关系的可滚动容器组件
655    .bindToNestedScrollable([{ parent: this.scrollScroller, child: this.listScroller }])
656  }
657}
658
659@Component
660struct MyPageTwo {
661  private listScroller: Scroller = new Scroller();
662  private arr: number[] = [];
663
664  aboutToAppear(): void {
665    for (let i = 0; i < 30; i++) {
666      this.arr.push(i);
667    }
668  }
669
670  build() {
671    NavDestination() {
672      List({ scroller: this.listScroller }) {
673        ForEach(this.arr, (item: number, index: number) => {
674          ListItem() {
675            Text('' + item)
676              .height(100)
677              .fontSize(16)
678              .textAlign(TextAlign.Center)
679              .width('90%')
680              .margin({ left: '5%' })
681              .borderRadius(10)
682              .backgroundColor(Color.Gray)
683          }
684        }, (item: string) => item);
685      }.width('100%')
686    }
687    .title('PageTwo', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
688    .toolbarConfiguration([
689      {
690        value: 'item1',
691        symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
692      }
693    ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
694    // 绑定可滚动容器组件
695    .bindToScrollable([this.listScroller])
696  }
697}
698
699@Entry
700@Component
701struct Index {
702  private stack: NavPathStack = new NavPathStack();
703
704  @Builder
705  MyPageMap(name: string) {
706    if (name === 'myPageOne') {
707      MyPageOne()
708    } else {
709      MyPageTwo()
710    }
711  }
712
713  build() {
714    Navigation(this.stack) {
715      Column() {
716        Button('push PageOne').onClick(() => {
717          this.stack.pushPath({ name: 'myPageOne' })
718        })
719        Button('push PageTwo').onClick(() => {
720          this.stack.pushPath({ name: 'myPageTwo' })
721        })
722      }.height('40%').justifyContent(FlexAlign.SpaceAround)
723    }.width('100%')
724    .height('100%')
725    .title({ main: 'MainTitle', sub: 'subTitle' })
726    .navDestination(this.MyPageMap)
727  }
728}
729```
730![navdestination_bind_scrollable](figures/navdestination_bind_scrollable.gif)
731
732### 示例2（设置NavDestination自定义转场）
733
734以下示例主要演示NavDestination设置自定义转场动画属性[customTransition](#customtransition15)的效果。
735
736```ts
737@Entry
738@Component
739struct NavDestinationCustomTransition {
740  stack: NavPathStack = new NavPathStack()
741
742  @Builder
743  pageMap(name: string) {
744    if (name) {
745      NavDest()
746    }
747  }
748
749  aboutToAppear(): void {
750    this.stack.pushPath({name: 'dest0'})
751  }
752
753  build() {
754    Navigation(this.stack) {
755      // empty
756    }
757    .navDestination(this.pageMap)
758    .hideNavBar(true)
759    .title('Main Page')
760    .titleMode(NavigationTitleMode.Mini)
761  }
762}
763
764declare type voidFunc = () => void;
765
766@Component
767struct NavDest {
768  @State name: string = 'NA'
769  @State destWidth: string = '100%'
770  stack: NavPathStack = new NavPathStack()
771  @State y: string = '0';
772
773  build() {
774    NavDestination() {
775      Column() {
776        Button('push next page', { stateEffect: true, type: ButtonType.Capsule })
777          .width('80%')
778          .height(40)
779          .margin(20)
780          .onClick(() => {
781            this.stack.pushPath({ name: this.name == 'PageOne' ? "PageTwo" : "PageOne" })
782          })
783      }
784      .size({ width: '100%', height: '100%' })
785    }
786    .title(this.name)
787    .translate({ y: this.y })
788    .onReady((context) => {
789      this.name = context.pathInfo.name;
790      this.stack = context.pathStack;
791    })
792    .backgroundColor(this.name == 'PageOne' ? '#F1F3F5' : '#ff11dee5')
793    .customTransition(
794      (op: NavigationOperation, isEnter: boolean)
795        : Array<NavDestinationTransition> | undefined => {
796        console.log('[NavDestinationTransition]', 'reached delegate in frontend, op: ' + op + ', isEnter: ' + isEnter);
797
798        let transitionOneEvent: voidFunc = () => { console.log('[NavDestinationTransition]', 'reached transitionOne, empty now!'); }
799        let transitionOneFinishEvent: voidFunc = () => { console.log('[NavDestinationTransition]', 'reached transitionOneFinish, empty now!'); }
800        let transitionOneDuration: number = 500;
801        if (op === NavigationOperation.PUSH) {
802          if (isEnter) {
803            // ENTER_PUSH
804            this.y = '100%';
805            transitionOneEvent = () => {
806              console.log('[NavDestinationTransition]', 'transitionOne, push & isEnter');
807              this.y = '0';
808            }
809          } else {
810            // EXIT_PUSH
811            this.y = '0';
812            transitionOneEvent = () => {
813              console.log('[NavDestinationTransition]', 'transitionOne, push & !isEnter');
814              this.y = '0';
815            }
816            transitionOneDuration = 450
817          }
818        } else if (op === NavigationOperation.POP) {
819          if (isEnter) {
820            // ENTER_POP
821            this.y = '0';
822            transitionOneEvent = () => {
823              console.log('[NavDestinationTransition]', 'transitionOne, pop & isEnter');
824              this.y = '0';
825            }
826          } else {
827            // EXIT_POP
828            this.y = '0';
829            transitionOneEvent = () => {
830              console.log('[NavDestinationTransition]', 'transitionOne, pop & !isEnter');
831              this.y = '100%';
832            }
833          }
834        } else {
835          console.log('[NavDestinationTransition]', '----- NOT-IMPL BRANCH of NAV-DESTINATION CUSTOM TRANSITION -----');
836        }
837
838        let transitionOne: NavDestinationTransition = {
839          duration: transitionOneDuration,
840          delay: 0,
841          curve: Curve.Friction,
842          event: transitionOneEvent,
843          onTransitionEnd: transitionOneFinishEvent
844        };
845
846        let transitionTwoEvent: voidFunc = () => { console.log('[NavDestinationTransition]', 'reached transitionTwo, empty now!'); }
847        let transitionTwo: NavDestinationTransition = {
848          duration: 1000,
849          delay: 0,
850          curve: Curve.EaseInOut,
851          event: transitionTwoEvent,
852          onTransitionEnd: () => { console.log('[NavDestinationTransition]', 'reached Two\'s finish'); }
853        };
854
855        return [
856          transitionOne,
857          transitionTwo,
858        ];
859      })
860  }
861}
862```
863![navdestination_custom_transition](figures/navdestination_custom_transition.gif)
864
865### 示例3（设置指定的NavDestination系统转场）
866
867以下示例主要演示NavDestination设置系统转场动画[systemTransition](#systemtransition14)为Fade、Explode、SlideBottom与SlideRight时的转场效果。
868
869```ts
870@Entry
871@Component
872struct NavDestinationSystemTransition {
873  @Provide stack: NavPathStack = new NavPathStack()
874  @Provide homePageTransitionType: NavigationSystemTransitionType = NavigationSystemTransitionType.DEFAULT;
875
876  @Builder
877  pageMap(name: string) {
878    if (name === 'Fade') {
879      Fade()
880    } else if (name === 'Explode') {
881      Explode()
882    } else if (name === 'SlideRight') {
883      SlideRight()
884    } else if (name === 'SlideBottom') {
885      SlideBottom()
886    } else {
887      Dest()
888    }
889  }
890
891  aboutToAppear(): void {
892    this.stack.pushPath({name: 'Dest'})
893  }
894
895  build() {
896    Navigation(this.stack) {
897      // empty
898    }
899    .navDestination(this.pageMap)
900    .hideNavBar(true)
901  }
902}
903
904@Component
905struct Dest {
906  @Consume stack: NavPathStack;
907  @Consume homePageTransitionType: NavigationSystemTransitionType;
908  @State name: string = 'NA';
909
910  build() {
911    NavDestination() {
912      HomeBody()
913    }
914    .title('Navigation System Animation')
915    .onReady((context) => {
916      this.name = context.pathInfo.name
917    })
918    .systemTransition(this.homePageTransitionType)
919  }
920}
921
922@Component
923struct Fade {
924  @Consume stack: NavPathStack;
925  @State name: string = 'NA';
926
927  build() {
928    NavDestination() {
929      DestBody({
930        name: this.name
931      })
932    }
933    .title(this.name)
934    .onReady((context) => {
935      this.name = context.pathInfo.name
936    })
937    .systemTransition(NavigationSystemTransitionType.FADE)
938  }
939}
940
941@Component
942struct Explode {
943  @Consume stack: NavPathStack;
944  @State name: string = 'NA';
945
946  build() {
947    NavDestination() {
948      DestBody({
949        name: this.name
950      })
951    }
952    .title(this.name)
953    .onReady((context) => {
954      this.name = context.pathInfo.name
955    })
956    .systemTransition(NavigationSystemTransitionType.EXPLODE)
957  }
958}
959
960@Component
961struct SlideRight {
962  @Consume stack: NavPathStack;
963  @State name: string = 'NA';
964
965  build() {
966    NavDestination() {
967      DestBody({
968        name: this.name
969      })
970    }
971    .title(this.name)
972    .onReady((context) => {
973      this.name = context.pathInfo.name
974    })
975    .systemTransition(NavigationSystemTransitionType.SLIDE_RIGHT)
976  }
977}
978
979@Component
980struct SlideBottom {
981  @Consume stack: NavPathStack;
982  @State name: string = 'NA';
983
984  build() {
985    NavDestination() {
986      DestBody({
987        name: this.name
988      })
989    }
990    .title(this.name)
991    .onReady((context) => {
992      this.name = context.pathInfo.name
993    })
994    .systemTransition(NavigationSystemTransitionType.SLIDE_BOTTOM)
995  }
996}
997
998@Component
999struct DestBody {
1000  name: string = 'NA'
1001
1002  columnTextSize: number = 22
1003  columnTextFontWeight: FontWeight = FontWeight.Bolder
1004  columnWidth: string = '65%'
1005  columnPadding: number = 22
1006  columnMargin: number = 10
1007  columnBorderRadius: number = 10
1008
1009  build() {
1010    Column() {
1011      Column()
1012        .width('85')
1013        .height(50)
1014        .backgroundColor(Color.White)
1015      Column() {
1016        Text(this.name)
1017          .fontSize(this.columnTextSize)
1018          .fontWeight(this.columnTextFontWeight)
1019      }
1020      .width(this.columnWidth)
1021      .padding(this.columnPadding)
1022      .margin(this.columnMargin)
1023      .borderRadius(this.columnBorderRadius)
1024      .shadow(ShadowStyle.OUTER_DEFAULT_LG)
1025    }
1026  }
1027}
1028
1029@Component
1030struct HomeBody {
1031  @Consume stack: NavPathStack;
1032  @Consume homePageTransitionType: NavigationSystemTransitionType;
1033
1034  columnTextSize: number = 22
1035  columnTextFontWeight: FontWeight = FontWeight.Bolder
1036  columnWidth: string = '85%'
1037  columnPadding: number = 22
1038  columnMargin: number = 10
1039  columnBorderRadius: number = 10
1040  columnShadow: ShadowStyle = ShadowStyle.OUTER_DEFAULT_MD
1041
1042  build() {
1043    Column() {
1044      Search({ value: 'Search' })
1045        .width(this.columnWidth)
1046
1047      Column() {
1048        Text('fade')
1049          .fontSize(this.columnTextSize)
1050          .fontWeight(this.columnTextFontWeight)
1051      }
1052      .width(this.columnWidth)
1053      .padding(this.columnPadding)
1054      .margin(this.columnMargin)
1055      .borderRadius(this.columnBorderRadius)
1056      .shadow(this.columnShadow)
1057      .onClick(() => {
1058        this.homePageTransitionType = NavigationSystemTransitionType.FADE
1059        this.stack.pushPath({name: 'Fade'})
1060      })
1061
1062      Column() {
1063        Text('explode')
1064          .fontSize(this.columnTextSize)
1065          .fontWeight(this.columnTextFontWeight)
1066      }
1067      .width(this.columnWidth)
1068      .padding(this.columnPadding)
1069      .margin(this.columnMargin)
1070      .borderRadius(this.columnBorderRadius)
1071      .shadow(this.columnShadow)
1072      .onClick(() => {
1073        this.homePageTransitionType = NavigationSystemTransitionType.EXPLODE
1074        this.stack.pushPath({name: 'Explode'})
1075      })
1076
1077      Column() {
1078        Text('slide right')
1079          .fontSize(this.columnTextSize)
1080          .fontWeight(this.columnTextFontWeight)
1081      }
1082      .width(this.columnWidth)
1083      .padding(this.columnPadding)
1084      .margin(this.columnMargin)
1085      .borderRadius(this.columnBorderRadius)
1086      .shadow(this.columnShadow)
1087      .onClick(() => {
1088        this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_RIGHT
1089        this.stack.pushPath({name: 'SlideRight'})
1090      })
1091
1092      Column() {
1093        Text('slide bottom')
1094          .fontSize(this.columnTextSize)
1095          .fontWeight(this.columnTextFontWeight)
1096      }
1097      .width(this.columnWidth)
1098      .padding(this.columnPadding)
1099      .margin(this.columnMargin)
1100      .borderRadius(this.columnBorderRadius)
1101      .shadow(this.columnShadow)
1102      .onClick(() => {
1103        this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_BOTTOM
1104        this.stack.pushPath({name: 'SlideBottom'})
1105      })
1106    }
1107  }
1108}
1109```
1110![navdestination_fade](figures/navdestination_fade_transition.gif)
1111![navdestination_explode](figures/navdestination_explode_transition.gif)
1112![navdestination_slide_bottom](figures/navdestination_slide_bottom_transition.gif)
1113![navdestination_slide_right](figures/navdestination_slide_right_transition.gif)
1114
1115NavDestination其他用法可参考[Navigation示例](ts-basic-components-navigation.md#示例1)。
1116