Menu

以垂直列表形式显示的菜单。

包含MenuItem、MenuItemGroup子组件。

Menu子菜单展开样式枚举:

名称	描述
SIDE_EXPAND	默认展开样式, 子菜单位于同一平面侧边展开。
EMBEDDED_EXPAND	直接展开样式, 子菜单嵌于主菜单内展开。
STACK_EXPAND	堆叠样式, 子菜单浮于主菜单上方展开。

1、属性

除支持通用属性外，还支持以下属性：

fontSize(deprecated)

fontSize(value: Length)

参数名	类型	必填	说明
font	Font	是	Menu中所有文本的尺寸。 默认值： { size: 16, family: 'HarmonyOS Sans', weight: FontWeight.Medium, style: FontStyle.Normal }
fontColor	ResourceColor	是	统一设置Menu中所有文本的颜色。
radius	Dimension|BorderRadiuses	是	Menu边框圆角半径。
width	Length	是	Menu边框宽度
menultemDivider	DividerStyleOptions|undefined	是	设置menuItem分割线样式。 -strokeWidth:分割线的线宽。 -color：分割线的颜色。 -startMargin：分割线与menuItem侧边起端的距离。 -endMargin：分割线与menuItem侧边结束端的距离。
menuItemGroupDivider	DividerStyleOptions|undefined	是	设置menuItemGroup顶部和底部分割线样式。 -strokeWidth:分割线的线宽, 默认值是1px。 -color：分割线的颜色, 默认值是 #33000000。 -startMargin：分割线与menuItemGroup侧边起端的距离, 默认值是16。 -endMargin：分割线与menuItemGroup侧边结束端的距离, 默认值是16。
subMenuExpandingMode	SubMenuExpandingMode	是	Menu子菜单展开样式。 默认值：SubMenuExpandingMode.SIDE_EXPAND

SubMenuExpandingMode 枚举说明

名称	说明
SIDE_EXPAND	默认展开样式，子菜单位于同一平面侧边展开
EMBEDDED_EXPAND	直接展开样式，子菜单嵌于主菜单内展开
STACK_EXPAND	堆叠样式，子菜单浮于主菜单上方展开

2. MenuItem

用来展示菜单Menu中具体的item菜单项

1）接口

MenuItem(value?: MenuItemOptions| CustomBuilder)

MenuItemOptions对象说明

名称	类型	必填	说明
starticon	ResourceStr	否	item中显示在左侧的图标信息路径。
content	ResourceStr	否	item的内容信息
endicon	ResourceStr	否	item中显示在右侧的图标信息路径
labellnfo	ResourceStr	否	定义结束标签信息，如快捷方式Ctrl+C等。
buider	CustomBuilder	否	用于构建二级菜单
symbolStartIcon	SymbolGlyphModiffier	否	item中显示在左侧的HMSymbol图标信息路径。配置该项时，原先startIcon图标不显示。
symbolEndIcon	SymbolGlyphModiffier	否	item中显示在右侧的HMSymbol图标信息路径。配置该项时，原先endIcon图标不显示

​​​​​​​​​​​​​​​​​​​​​​​​​​​​（2）MenuItem属性

参数名	类型	必填	说明
selected	boolean	是	菜单项是否选中。 默认值：false
selectIcon	boolean|ResourceStr| SymbolGlyphModiffer	是	菜单项被选中时，是否显示被选中的图标。 默认值：false true: 菜单项被选中时，显示默认的对勾图标 false: 即使菜单项被选中也不显示图标 ResourceStr: 菜单项被选中时，显示指定的图标 SymbolGlyphModifier: 菜单项被选中时，显示指定的HMSymbol图标。
contentFont	Font	是	菜单项中内容信息的字体样式
contentFontColor	ResourceColor	是	菜单项中内容信息的字体颜色。
labelFont	Font	是	菜单项中标签信息的字体样式
labelFontColor	ResourceColor	是	菜单项中标签信息的字体颜色

（3）MenuItem事件

参数名	类型	必填	说明
onChange	boolean	是	选中状态发生变化时，触发该回调。 返回值为true时，表示已选中，为false时，表示未选中。

3. MenuItemGrop

该组件用来展示菜单MenuItem的分组。

子组件包含MenuItem子组件​​​​​​​

（1）MenuItemGrop接口

MenuItemGroup(value?: MenuItemGroupOptions)

MenuItemGroupOptions对象说明

名称	类型	必填	说明
header	ResourceStr | CustomBuilder	否	设置对应group的标题显示信息。
footer	ResourceStr | CustomBuilder	否	设置对应group的尾部显示信息。

​​​​​​​

Navigation

1.Navigation

Navigation组件是路由导航的根视图容器，一般作为Page页面的根容器使用，其内部默认包含了标题栏、内容区和工具栏，其中内容区默认首页显示导航内容（Navigation的子组件）或非首页显示（NavDestination的子组件），首页和非首页通过路由进行切换。

（1）Navigation接口

Navigation(pathInfos: NavPathStack)：绑定路由栈到Navigation组件。

参数名	类型	必填	说明
pathInfos	NavPathStack	是	路由栈信息。

（2）Navigation所有属性

1. title属性：设置页面标题

参数名	类型	必填	说明
value	ResourceStr10+ | CustomBuilder |  NavigationCommonTitle9+ |  NavigationCustomTitle9+	是	页面标题，使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行（2行）最后...截断。如果设置副标题，先缩小最后...截断。
options	NavigationTitleOptions	否	标题栏选项

2. Menus属性：设置页面右上角菜单

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

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

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

3.titleMode属性：设置页面标题栏显示模式

参数名	类型	必填	说明
value	NavigationTitleMode	是	页面标题栏显示模式。 默认值：NavigationTitleMode.Free

4.toolbarConfiguration属性：设置工具栏内容，不设置时不显示工具栏

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

参数名	类型	必填	说明
value	Array<ToolbarItem> | CustomBuilder	是	工具栏内容，使用Array<ToolbarItem>写法设置的工具栏有如下特性： 工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。 文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后...截断。 竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。横屏时，如果为Split模式，仍按照竖屏规则显示，如果为Stack模式需配合menus属性的Array<NavigationMenuItem>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。 使用CustomBuilder写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。
options	NavigationToolbarOptions1	否	工具栏选项。

5.hideToolBar属性：设置是否隐藏工具栏

参数名	类型	必填	说明
value	Boolean	是	是否隐藏工具栏。 默认值：false true: 隐藏工具栏。 false: 显示工具栏。

6.hideTitleBar属性：设置是否隐藏标题栏

参数名	类型	必填	说明
value	Boolean	是	是否隐藏标题栏。 默认值：false true: 隐藏标题栏。 false: 显示标题栏。

7.hideBackButton属性：设置是否隐藏标题栏中的返回键。

返回键仅针对titleMode为NavigationTitleMode.Mini时才生效。

参数名	类型	必填	说明
value	Boolean	是	是否隐藏标题栏中的返回键。 默认值：false true: 隐藏返回键。 false: 显示返回键。

8.navBarWidth：设置导航栏宽度

仅在Navigation组件分栏时生效。

参数名	类型	必填	说明
value	Length	是	导航栏宽度。 默认值：240 单位：vp undefined：行为不做处理，导航栏宽度与默认值保持一致。

9.navBarPosition：设置导航栏位置

仅在Navigation组件分栏时生效。

参数名	类型	必填	说明
value	NavBarPosition	是	导航栏位置。 默认值：NavBarPosition.Start

10.mode：设置导航栏的显示模式。

支持Stack、Split与Auto模式。

参数名	类型	必填	说明
value	NavigationMode	是	导航栏的显示模式。 默认值：NavigationMode.Auto 自适应：基于组件宽度自适应单栏和双栏。

11.backButtonIcon：设置标题栏中返回键图标

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

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

12.hideNavBar：设置是否隐藏导航栏

设置是否隐藏导航栏。设置为true时，隐藏Navigation的导航栏，包括标题栏、内容区和工具栏。如果此时路由栈中存在NavDestination页面，则直接显示栈顶NavDestination页面，反之显示空白。

参数名	类型	必填	说明
value	boolean	是	是否隐藏导航栏。 默认值：false

13.navDestination属性：创建NavDestination组件

创建NavDestination组件。使用builder函数，基于name和param构造NavDestination组件。builder下只能有一个根节点。builder中允许在NavDestination组件外包含一层自定义组件， 但自定义组件不允许设置属性和事件，否则仅显示空白。

14.navBarWidthRange：设置导航栏最小和最大宽度（双栏模式下生效）。

15.minContentWidth：设置导航栏内容区最小宽度（双栏模式下生效）

参数名	类型	必填	说明
value	Dimension	是	导航栏内容区最小宽度。 默认值：360 单位：vp undefined：行为不做处理，导航栏内容区最小宽度与默认值保持一致。 Auto模式断点计算：默认600vp，minNavBarWidth(240vp) + minContentWidth (360vp)

1. 仅设置navBarWidth，不支持Navigation分割线拖拽。

2. navBarWidthRange指定分割线可以拖拽范围。如果不设置值，则按照默认值处理。拖拽范围需要满足navBarWidthRange设置的范围和minContentWidth限制。

3. Navigation显示范围缩小：a. 缩小内容区大小。如果不设置minContentWidth属性，则可以缩小内容区至0， 否则最小缩小至minContentWidth。b. 缩小导航栏大小，缩小时需要满足导航栏宽度大于navBarRange的下限。c. 对显示内容进行裁切。

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

参数名	类型	必填	说明
types	Array <LayoutSafeAreaType>	否	配置扩展安全区域的类型。 默认值: [LayoutSafeAreaType.SYSTEM]
edges	Array <LayoutSafeAreaEdge>	否	配置扩展安全区域的方向。 默认值: [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

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

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

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

17.systemBarStyle：当Navigation中显示Navigation首页时，设置对应系统状态栏的样式。

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

1. 不建议混合使用systemBarStyle属性和window设置状态栏样式的相关接口，例如：setWindowSystemBarProperties。
2. 初次设置Navigation/NavDestination的systemBarStyle属性时，会备份当前状态栏样式用于后续的恢复场景。
3. Navigation总是以首页（页面栈内没有NavDestination时）或者栈顶NavDestination设置的状态栏样式为准。
4. Navigation首页或者任何栈顶NavDestination页面，如果设置了有效的systemBarStyle，则会使用设置的样式，反之如果之前已经备份了样式，则使用备份的样式，否则不做任何处理。
5. Split模式下的Navigation，如果内容区没有NavDestination，则遵从Navigation首页的设置，反之则遵从栈顶NavDestination的设置。
6. 仅支持在主窗口的主页面中使用systemBarStyle设置状态栏样式。
7. 仅当Navigation占满整个页面时，设置的样式才会生效，当Navigation没有占满整个页面时，如果有备份的样式，则恢复备份的样式。
8. 当页面设置不同样式时，在页面转场开始时生效。
9. 非全屏窗口下，Navigation/NavDestination设置的状态栏不生效。

​​​​​​​

（3）Navigation事件

1.onTitleModeChange

当titleMode为NavigationTitleMode.Free时，随着可滚动组件的滑动标题栏模式发生变化时触发此回调。

参数名	类型	必填	说明
titleMode	NavigationTitleMode	是	标题模式。

2.onNavBarStateChange

导航栏显示状态切换时触发该回调。

参数名	类型	必填	说明
isVisible	boolean	是	isVisible为true时表示显示，为false时表示隐藏。

3. onNavigationModeChange

当Navigation首次显示或者单双栏状态发生变化时触发该回调。

参数名	类型	必填	说明
mode	NavigationMode	是	NavigationMode.Split: 当前Navigation显示为双栏; NavigationMode.Stack: 当前Navigation显示为单栏。

4.customNavContentTransition

自定义转场动画回调。

参数名	类型	必填	说明
from	NavContentInfo	是	退场Destination的页面。
to	NavContentInfo	是	进场Destination的页面。
operation	NavigationOperation	是	转场类型。

返回值：

类型	说明
NavigationAnimatedTransition | undefined	自定义转场动画协议。 undefined: 返回未定义，执行默认转场动效。

5.NavPathStack

Navigation路由栈，允许被继承。开发者可以在派生类中新增属性方法，也可以重写基类NavPathStack的方法。派生类对象可以替代基类NavPathStack对象使用。

6.pushPath

将info指定的NavDestination页面信息入栈，具体根据options中指定不同的LaunchMode，有不同的行为

参数名	类型	必填	说明
info	NavPathInfo	是	NavDestination页面的信息。
options	NavigationOptions	否	页面栈操作选项。

7.pushPathByName

将name指定的NavDestination页面信息入栈，传递的数据为param，添加onPop回调接收入栈页面出栈时的返回结果，并进行处理。

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
onPop	Callback<PopInfo>	是	Callback回调，用于页面出栈时触发该回调处理返回结果。仅pop中设置result参数后触发。
animated	boolean	否	是否支持转场动画，默认值：true。

8.pushDestination

将info指定的NavDestination页面信息入栈，使用Promise异步回调返回接口调用结果，具体根据options中指定不同的LaunchMode，有不同的行为。

参数：

参数名	类型	必填	说明
info	NavPathInfo	是	NavDestination页面的信息。
options	NavigationOptions	否	页面栈操作选项。

返回值：

类型	说明
Promise<void>	异常返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.router(页面路由)错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	Internal error.
100005	Builder function not registered.
100006	NavDestination not found.

9.pushDestinationByName

将name指定的NavDestination页面信息入栈，传递的数据为param，并且添加用于页面出栈时处理返回结果的OnPop回调，使用Promise异步回调返回接口调用结果。

参数：

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
onPop	Callback<PopInfo>	是	Callback回调，用于页面出栈时处理返回结果。仅pop中设置result参数后触发。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
Promise<void>	异常返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.router(页面路由)错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001	Internal error.
100005	Builder function not registered.
100006	NavDestination not found.

10.replacePath

替换页面栈操作，具体根据options中指定不同的LaunchMode，有不同的行为

参数名	类型	必填	说明
info	NavPathInfo	是	新栈顶页面参数信息。
options	NavigationOptions	否	页面栈操作选项。

11.replacePathByName

将当前页面栈栈顶退出，将name指定的页面入栈。

参数：

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
animated11+	boolean	否	是否支持转场动画，默认值：true。

12.removeByIndexes

将页面栈内索引值在indexes中的NavDestination页面删除。

参数名	类型	必填	说明
indexes	Array<number>	是	待删除NavDestination页面的索引值数组。

返回值：

类型	说明
number	返回删除的NavDestination页面数量。