鸿蒙5.0开发进阶：UI框架-ArkTS组件（NavDestination）

原创 于 2025-01-08 14:26:02 发布
· 890 阅读 · 21 ·
版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #鸿蒙系统 #前端 #ArkUI #ArkTS

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

NavDestination

作为子页面的根容器，用于显示Navigation的内容区。

说明

  • 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

  • 该组件从API Version 11开始默认支持安全区避让特性(默认值为：expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]))，开发者可以重写该属性覆盖默认行为，API Version 11之前的版本需配合expandSafeArea属性实现安全区避让。

  • NavDestination组件必须配合Navigation使用，作为Navigation目的页面的根节点，单独使用只能作为普通容器组件，不具备路由相关属性能力。

  • 如果页面栈中间页面的生命周期发生变化，跳转之前的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)与跳转之后的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)均在最后触发。

  • NavDestination未设置主副标题并且没有返回键时，不显示标题栏。

子组件

说明

  • 子组件类型：系统组件和自定义组件，支持渲染控制类型（if/else、ForEach和LazyForEach）。
  • 子组件个数：多个。

接口

NavDestination()

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

支持通用属性。

不推荐设置位置、大小等布局相关属性，可能会造成页面显示异常。

title

title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle, options?: NavigationTitleOptions)

设置页面标题。使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行2行后以...截断。如果设置副标题，先缩小后以...截断。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valuestring | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle是页面标题。
options12+NavigationTitleOptions否标题栏选项。

hideTitleBar

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueboolean是

是否隐藏标题栏。

默认值：false

true: 隐藏标题栏。

false: 显示标题栏。

mode 11+

mode(value: NavDestinationMode)

设置NavDestination类型，不支持动态修改。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueNavDestinationMode是

NavDestination类型。

默认值: NavDestinationMode.STANDARD

backButtonIcon11+

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

说明

不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

设置标题栏返回键图标。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueResourceStr | PixelMap | SymbolGlyphModifier12+是标题栏返回键图标。

menus(value: Array<NavigationMenuItem> | CustomBuilder)

说明

不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

设置页面右上角菜单。不设置时不显示菜单项。使用Array<NavigationMenuItem> 写法时，竖屏最多支持显示3个图标，横屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueArray<NavigationMenuItem> | CustomBuilder是页面右上角菜单。

ignoreLayoutSafeArea12+

ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>)

控制组件的布局，使其扩展到非安全区域

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
typesArray <LayoutSafeAreaType>否

配置扩展安全区域的类型。

默认值:

[LayoutSafeAreaType.SYSTEM]

edgesArray <LayoutSafeAreaEdge>否

配置扩展安全区域的方向。

默认值:

[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

说明

组件设置LayoutSafeArea之后生效的条件为：

设置LayoutSafeAreaType.SYSTEM时，组件的边界与非安全区域重合时组件能够延伸到非安全区域下。例如：设备顶部状态栏高度100，组件在屏幕中纵向方位的绝对偏移需要在0到100之间。

若组件延伸到非安全区域内，此时在非安全区域里触发的事件（例如：点击事件）等可能会被系统拦截，优先响应状态栏等系统组件。

systemBarStyle12+

systemBarStyle(style: Optional<SystemBarStyle>)

当Navigation中显示当前NavDestination时，设置对应系统状态栏的样式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
styleOptional<SystemBarStyle>是系统状态栏样式。

说明

  1. 必须配合Navigation使用，作为其Navigation目的页面的根节点时才能生效。
  2. 其他使用限制请参考Navigation对应的systemBarStyle属性说明。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称描述
STANDARD标准模式的NavDestination。
DIALOG默认透明，进出页面栈不影响下层NavDestination的生命周期，不支持系统转场动画。

事件

除支持通用事件外，还支持如下事件：

onShown10+

onShown(callback: () => void)

当该NavDestination页面显示时触发此回调。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onHidden10+

onHidden(callback: () => void)

当该NavDestination页面隐藏时触发此回调。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onWillAppear12+

onWillAppear(callback: Callback<void>)

当该Destination挂载之前触发此回调。在该回调中允许修改页面栈，当前帧生效。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onWillShow12+

onWillShow(callback: Callback<void>)

当该Destination显示之前触发此回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onWillHide12+

onWillHide(callback: Callback<void>)

当该Destination隐藏之前触发此回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onWillDisappear12+

onWillDisappear(callback: Callback<void>)

当该Destination卸载之前触发的生命周期(有转场动画时，在转场动画开始之前触发)。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onBackPressed10+

onBackPressed(callback: () => boolean)

当与Navigation绑定的页面栈中存在内容时，此回调生效。当点击返回键时，触发该回调。

返回值为true时，表示重写返回键逻辑，返回值为false时，表示回退到上一个页面。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

onReady11+

onReady(callback: Callback<NavDestinationContext>)

当NavDestination即将构建子组件之前会触发此回调。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
mainstring是设置主标题。
substring是设置副标题。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
builderCustomBuilder是设置标题栏内容。
heightTitleHeight | Length是设置标题栏高度。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
pathInfoNavPathInfo是

跳转NavDestination时指定的参数。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

pathStackNavPathStack是

当前NavDestination所处的页面栈。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

navDestinationId12+string否

当前NavDestination的唯一ID，由系统自动生成，和组件通用属性id无关。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

getConfigInRouteMap12+

getConfigInRouteMap(): RouteMapConfig |undefined

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值

类型说明
RouteMapConfig当前页面路由配置信息。
undefined当该页面不是通过路由表配置时返回undefined。

RouteMapConfig12+

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
namestring是页面名称。
pageSourceFilestring是页面在当前包中的路径。
dataobject是页面自定义字段信息。

评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值