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## 子组件 16 17> **说明：** 18> 19> - 子组件类型：系统组件和自定义组件，支持渲染控制类型（[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)）。 20> - 子组件个数：多个。 21 22 23## 接口 24 25NavDestination() 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31## 属性 32 33支持[通用属性](ts-universal-attributes-size.md)。 34 35不推荐设置位置、大小等布局相关属性，可能会造成页面显示异常。 36 37### title 38 39title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle | Resource, options?: NavigationTitleOptions) 40 41设置页面标题。使用NavigationCustomTitle类型设置height高度时，[titleMode](ts-basic-components-navigation.md#titlemode)属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行2行后以...截断。如果设置副标题，先缩小后以...截断。 42 43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| ------ | ------------------------------------------------------------ | ---- | ---------- | 51| value | string \| [CustomBuilder](ts-types.md#custombuilder8) \| [NavDestinationCommonTitle](#navdestinationcommontitle) \| [NavDestinationCustomTitle](#navdestinationcustomtitle) | 是 | 页面标题。 | 52| options<sup>12+</sup> | [NavigationTitleOptions](ts-basic-components-navigation.md#navigationtitleoptions11) | 否 | 标题栏选项。 | 53 54### hideTitleBar 55 56hideTitleBar(value: boolean) 57 58设置是否隐藏标题栏。 59 60**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.ArkUI.ArkUI.Full 63 64**参数：** 65 66| 参数名 | 类型 | 必填 | 说明 | 67| ------ | ------- | ---- | ------------------------------------------------------------ | 68| value | boolean | 是 | 是否隐藏标题栏。<br/>默认值：false<br/>true: 隐藏标题栏。<br/>false: 显示标题栏。 | 69 70### hideTitleBar<sup>14+</sup> 71 72hideTitleBar(hide: boolean, animated: boolean) 73 74设置是否隐藏标题栏，设置是否使用动画显隐标题栏。 75 76**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 77 78**系统能力：** SystemCapability.ArkUI.ArkUI.Full 79 80**参数：** 81 82| 参数名 | 类型 | 必填 | 说明 | 83| ------ | ------- | ---- | ------------------------------------------------------------ | 84| hide | boolean | 是 | 是否隐藏标题栏。<br/>默认值：false<br/>true: 隐藏标题栏。<br/>false: 显示标题栏。 | 85| animated | boolean | 是 | 设置是否使用动画显隐标题栏。<br/>默认值：false<br/>true: 使用动画显示隐藏标题栏。<br/>false: 不使用动画显示隐藏标题栏。 | 86 87### toolbarConfiguration<sup>14+</sup> 88 89toolbarConfiguration(value: Array<ToolbarItem> | CustomBuilder, options?: NavigationToolbarOptions) 90 91设置工具栏内容。未调用本接口时不显示工具栏。 92 93**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 94 95**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.ArkUI.ArkUI.Full 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 103| value | Array<[ToolbarItem](ts-basic-components-navigation.md#toolbaritem10)> \| [CustomBuilder](ts-types.md#custombuilder8) | 是 | 工具栏内容。<br/>使用Array<[ToolbarItem](ts-basic-components-navigation.md#toolbaritem10)>写法设置的工具栏有如下特性：<br/>-工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。<br/>-文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，工具栏最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后...截断。<br/>-竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标中，点击更多图标，可以展示剩余内容。横屏时，如果为[Split](ts-basic-components-navigation.md#navigationmode9枚举说明)模式，仍按照竖屏规则显示，如果为[Stack](ts-basic-components-navigation.md#navigationmode9枚举说明)模式需配合menus属性的Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。<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>14+</sup> 111 112hideToolBar(hide: boolean, animated?: boolean) 113 114设置是否隐藏工具栏，设置是否使用动画显隐工具栏。 115 116**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 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) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [SymbolGlyphModifier<sup>12+</sup>](ts-universal-attributes-attribute-modifier.md) | 是 | 标题栏返回键图标。 | 163 164### menus<sup>12+</sup> 165 166menus(value: Array<NavigationMenuItem> | CustomBuilder) 167 168> **说明：** 169> 170> 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。 171 172 173设置页面右上角菜单。不设置时不显示菜单项。使用Array<[NavigationMenuItem](ts-basic-components-navigation.md#navigationmenuitem)> 写法时，竖屏最多支持显示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)> \| [CustomBuilder](ts-types.md#custombuilder8) | 是 | 页面右上角菜单。 | 184 185### ignoreLayoutSafeArea<sup>12+</sup> 186 187ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>) 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<SystemBarStyle>) 212 213当Navigation中显示当前NavDestination时，设置对应系统状态栏的样式。 214 215**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 216 217**系统能力：** SystemCapability.ArkUI.ArkUI.Full 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ------ | -------------- | ---- | ------------------ | 223| style | Optional<[SystemBarStyle](../js-apis-window.md#systembarstyle12)> | 是 | 系统状态栏样式。 | 224 225> **说明：** 226> 227> 1. 必须配合Navigation使用，作为其Navigation目的页面的根节点时才能生效。 228> 2. 其他使用限制请参考Navigation对应的[systemBarStyle](ts-basic-components-navigation.md#systembarstyle12)属性说明。 229 230## NavDestinationMode枚举说明 <sup>11+</sup> 231 232**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 233 234**系统能力：** SystemCapability.ArkUI.ArkUI.Full 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238| 名称 | 说明 | 239| ---- | ---------------------------------------- | 240| STANDARD | 标准模式的NavDestination。 | 241| DIALOG | 默认透明，进出页面栈不影响下层NavDestination的生命周期。<br />API version 13之前，默认无系统转场动画。从API version 13开始，支持系统转场动画。 | 242 243## 事件 244 245除支持[通用事件](ts-universal-events-click.md)外，还支持如下事件： 246 247### onShown<sup>10+</sup> 248 249onShown(callback: () => void) 250 251当该NavDestination页面显示时触发此回调。 252 253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 254 255**系统能力：** SystemCapability.ArkUI.ArkUI.Full 256 257### onHidden<sup>10+</sup> 258 259onHidden(callback: () => void) 260 261当该NavDestination页面隐藏时触发此回调。 262 263**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 264 265**系统能力：** SystemCapability.ArkUI.ArkUI.Full 266 267### onWillAppear<sup>12+</sup> 268 269onWillAppear(callback: Callback\<void>) 270 271当该Destination挂载之前触发此回调。在该回调中允许修改页面栈，当前帧生效。 272 273**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 274 275**系统能力：** SystemCapability.ArkUI.ArkUI.Full 276 277### onWillShow<sup>12+</sup> 278 279onWillShow(callback: Callback\<void>) 280 281当该Destination显示之前触发此回调。 282 283**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 284 285**系统能力：** SystemCapability.ArkUI.ArkUI.Full 286 287### onWillHide<sup>12+</sup> 288 289onWillHide(callback: Callback\<void>) 290 291当该Destination隐藏之前触发此回调。 292 293**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 294 295**系统能力：** SystemCapability.ArkUI.ArkUI.Full 296 297### onWillDisappear<sup>12+</sup> 298 299onWillDisappear(callback: Callback\<void>) 300 301当该Destination卸载之前触发的生命周期(有转场动画时，在转场动画开始之前触发)。 302 303**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 304 305**系统能力：** SystemCapability.ArkUI.ArkUI.Full 306 307### onBackPressed<sup>10+</sup> 308 309onBackPressed(callback: () => boolean) 310 311当与Navigation绑定的页面栈中存在内容时，此回调生效。当点击返回键时，触发该回调。 312 313返回值为true时，表示重写返回键逻辑，返回值为false时，表示回退到上一个页面。 314 315**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 316 317**系统能力：** SystemCapability.ArkUI.ArkUI.Full 318 319### onReady<sup>11+</sup> 320 321onReady(callback: [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)<[NavDestinationContext](#navdestinationcontext11)>) 322 323当NavDestination即将构建子组件之前会触发此回调。 324 325**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 326 327**系统能力：** SystemCapability.ArkUI.ArkUI.Full 328 329## NavDestinationCommonTitle 330 331**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 332 333**系统能力：** SystemCapability.ArkUI.ArkUI.Full 334 335| 名称 | 类型 | 必填 | 说明 | 336| ---- | ------ | ---- | ------ | 337| main | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | 是 | 设置主标题。 | 338| sub | string \| [Resource<sup>14+<sup>](ts-types.md#resource) | 是 | 设置副标题。 | 339 340## NavDestinationCustomTitle 341 342**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 343 344**系统能力：** SystemCapability.ArkUI.ArkUI.Full 345 346| 名称 | 类型 | 必填 | 说明 | 347| ------- | ---------------------------------------- | ---- | -------- | 348| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 设置标题栏内容。 | 349| height | [TitleHeight](ts-appendix-enums.md#titleheight9) \| [Length](ts-types.md#length) | 是 | 设置标题栏高度。 | 350 351## NavDestinationContext<sup>11+</sup> 352 353**系统能力：** SystemCapability.ArkUI.ArkUI.Full 354 355| 名称 | 类型 | 必填 | 说明 | 356| ---- | ------ | ----- | ------ | 357| pathInfo | [NavPathInfo](ts-basic-components-navigation.md#navpathinfo10) | 是 | 跳转NavDestination时指定的参数。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 358| pathStack | [NavPathStack](ts-basic-components-navigation.md#navpathstack10) | 是 | 当前NavDestination所处的页面栈。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 359| navDestinationId<sup>12+</sup> | string | 否 | 当前NavDestination的唯一ID，由系统自动生成，和组件通用属性id无关。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 360 361### getConfigInRouteMap<sup>12+</sup> 362 363getConfigInRouteMap(): RouteMapConfig |undefined 364 365**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 366 367**系统能力：** SystemCapability.ArkUI.ArkUI.Full 368 369**返回值** 370 371| 类型 | 说明 | 372| --- | --- | 373| [RouteMapConfig](#routemapconfig12) | 当前页面路由配置信息。 | 374| undefined | 当该页面不是通过路由表配置时返回undefined。 | 375 376## RouteMapConfig<sup>12+</sup> 377 378**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 379 380**系统能力：** SystemCapability.ArkUI.ArkUI.Full 381 382| 名称 | 类型 |必填 | 说明 | 383| ---- | --- | ---- |----- | 384| name | string | 是 | 页面名称。| 385| pageSourceFile| string | 是 | 页面在当前包中的路径。| 386| data | Object | 是 | 页面自定义字段信息。| 387 388## 示例 389 390NavDestination用法可参考[Navigation示例](ts-basic-components-navigation.md#示例1)。 391