上海仿站定制模板建站_html网页设计作品及其赏析_谷歌seo运营_重庆网站排名公司

组件–Menu

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

包含MenuItem、MenuItemGroup子组件。

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

属性

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

fontSize(deprecated)

fontSize(value: Length)

统一设置Menu中所有文本的尺寸。

从API Version 10开始废弃，建议使用font代替。

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

参数：

参数名	类型	必填	说明
value	Length	是	Menu中所有文本的尺寸，Length为number类型时，使用fp单位。

font10+

font(value: Font)

统一设置Menu中所有文本的尺寸。

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

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

参数：

参数名	类型	必填	说明
value	Font	是	Menu中所有文本的尺寸。

fontColor10+

fontColor(value: ResourceColor)

统一设置Menu中所有文本的颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	Menu中所有文本的颜色。

radius10+

radius(value: Dimension | BorderRadiuses)

设置Menu边框圆角半径。

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

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

参数：

参数名	类型	必填	说明
value	Dimension \| BorderRadiuses	是	Menu边框圆角半径。默认值跟随主题。从API version 12开始，当水平方向两个圆角半径之和的最大值大于菜单宽度，或垂直方向两个圆角半径之和的最大值大于菜单高度时，菜单四个圆角均采用菜单默认圆角半径值。

width10

width(value: Length)

设置Menu边框宽度，支持设置的最小宽度为64vp。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

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

参数：

参数名	类型	必填	说明
value	Length	是	Menu边框宽度。

menuItemDivider12+

menuItemDivider(options: DividerStyleOptions | undefined)

设置menuItem分割线样式, 不设置该属性则不展示分割线。

startMargin + endMargin 超过组件宽度后startMargin和endMargin会被置0。

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

参数：

参数名	类型	必填	说明
options	DividerStyleOptions \| undefined	是	设置menuItem分割线样式。-strokeWidth:分割线的线宽。-color：分割线的颜色。-startMargin：分割线与menuItem侧边起端的距离。-endMargin：分割线与menuItem侧边结束端的距离。

menuItemGroupDivider12+

menuItemGroupDivider(options: DividerStyleOptions | undefined)

设置menuItemGroup上下分割线的样式, 不设置该属性则默认展示分割线。

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

参数：

参数名	类型	必填	说明
options	DividerStyleOptions \| undefined	是	设置menuItemGroup顶部和底部分割线样式。-strokeWidth:分割线的线宽, 默认值是1px。-color：分割线的颜色, 默认值是 #33000000。-startMargin：分割线与menuItemGroup侧边起端的距离, 默认值是16。-endMargin：分割线与menuItemGroup侧边结束端的距离, 默认值是16。

subMenuExpandingMode12+

subMenuExpandingMode(mode: SubMenuExpandingMode)

设置Menu子菜单展开样式。

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

参数：

参数名	类型	必填	说明
mode	SubMenuExpandingMode	是	Menu子菜单展开样式。

示例1

@Entry
@Component
struct Index {@State select: boolean = trueprivate iconStr: ResourceStr = $r("app.media.view_list_filled")private iconStr2: ResourceStr = $r("app.media.arrow_right_filled")@BuilderSubMenu() {Menu() {MenuItem({ content: "复制", labelInfo: "Ctrl+C" })MenuItem({ content: "粘贴", labelInfo: "Ctrl+V" })}}@BuilderMyMenu(){Menu() {MenuItem({ startIcon: $r("app.media.icon"), content: "菜单选项" })MenuItem({ startIcon: $r("app.media.icon"), content: "菜单选项" }).enabled(false)MenuItem({startIcon: this.iconStr,content: "菜单选项",endIcon: this.iconStr2,builder: ():void=>this.SubMenu()})MenuItemGroup({ header: '小标题' }) {MenuItem({startIcon: this.iconStr,content: "菜单选项",endIcon: this.iconStr2,builder: ():void=>this.SubMenu()})MenuItem({startIcon: $r("app.media.app_icon"),content: "菜单选项",endIcon: this.iconStr2,builder: ():void=>this.SubMenu()})}MenuItem({startIcon: this.iconStr,content: "菜单选项",})}}build() {Row() {Column() {Text('click to show menu').fontSize(50).fontWeight(FontWeight.Bold)}.bindMenu(this.MyMenu).width('100%')}.height('100%')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2

普通菜单(使用symbol类型图标)

// xxx.ets
import { SymbolGlyphModifier } from '@kit.ArkUI';@Entry
@Component
struct Index {@State startIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_mic')).fontSize('24vp');@State endIconModifier: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_trash')).fontSize('24vp');@State selectIconModifier: SymbolGlyphModifier =new SymbolGlyphModifier($r('sys.symbol.checkmark')).fontSize('24vp');@State select: boolean = true;@BuilderSubMenu() {Menu() {MenuItem({ content: "复制", labelInfo: "Ctrl+C" })MenuItem({ content: "粘贴", labelInfo: "Ctrl+V" })}}@BuilderMyMenu() {Menu() {MenuItem({ symbolStartIcon: this.startIconModifier, content: "菜单选项" })MenuItem({ symbolStartIcon: this.startIconModifier, content: "菜单选项" }).enabled(false)MenuItem({symbolStartIcon: this.startIconModifier,content: "菜单选项",symbolEndIcon: this.endIconModifier,builder: (): void => this.SubMenu()})MenuItemGroup({ header: '小标题' }) {MenuItem({symbolStartIcon: this.startIconModifier,content: "菜单选项",symbolEndIcon: this.endIconModifier,builder: (): void => this.SubMenu()})MenuItem({symbolStartIcon: this.startIconModifier,content: "菜单选项",symbolEndIcon: this.endIconModifier,builder: (): void => this.SubMenu()})}MenuItem({content: "菜单选项",}).selected(this.select).selectIcon(this.selectIconModifier)}}build() {Row() {Column() {Text('click to show menu').fontSize(50).fontWeight(FontWeight.Bold)}.bindMenu(this.MyMenu).width('100%')}.height('100%')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

MenuItem

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

参数：

参数	类型	必填	参数描述
value	MenuItemOptions \| CustomBuilder	否	包含设置MenuItem的各项信息。

MenuItemOptions类型说明

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

名称	类型	必填	描述
startIcon	ResourceStr	否	item中显示在左侧的图标信息路径。
content	ResourceStr	否	item的内容信息。
endIcon	ResourceStr	否	item中显示在右侧的图标信息路径。
labelInfo	ResourceStr	否	定义结束标签信息，如快捷方式Ctrl+C等。
builder	CustomBuilder	否	用于构建二级菜单。
symbolStartIcon12+	SymbolGlyphModifier	否	item中显示在左侧的HMSymbol图标信息路径。配置该项时，原先startIcon图标不显示。
symbolEndIcon12+	SymbolGlyphModifier	否	item中显示在右侧的HMSymbol图标信息路径。配置该项时，原先endIcon图标不显示。

属性

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

selected

selected(value: boolean)

设置菜单项是否选中。

从API version 10开始，该参数支持$$双向绑定变量。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	菜单项是否选中。默认值：false

selectIcon

selectIcon(value: boolean | ResourceStr | SymbolGlyphModifier)

设置当菜单项被选中时，是否显示被选中的图标。

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

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

参数：

参数名	类型	必填	说明
value	boolean \| ResourceStr10+\| SymbolGlyphModifier12+	是	菜单项被选中时，是否显示被选中的图标。默认值：falsetrue: 菜单项被选中时，显示默认的对勾图标false: 即使菜单项被选中也不显示图标ResourceStr: 菜单项被选中时，显示指定的图标SymbolGlyphModifier: 菜单项被选中时，显示指定的HMSymbol图标。

contentFont10+

contentFont(value: Font)

设置菜单项中内容信息的字体样式。

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

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

参数：

参数名	类型	必填	说明
value	Font	是	菜单项中内容信息的字体样式。

contentFontColor10+

contentFontColor(value: ResourceColor)

设置菜单项中内容信息的字体颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	菜单项中内容信息的字体颜色。

labelFont10+

labelFont(value: Font)

设置菜单项中标签信息的字体样式。

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

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

参数：

参数名	类型	必填	说明
value	Font	是	菜单项中标签信息的字体样式。

labelFontColor10+

labelFontColor(value: ResourceColor)

设置菜单项中标签信息的字体颜色。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	菜单项中标签信息的字体颜色。

事件

onChange

onChange(callback: (selected: boolean) => void)

当选中状态发生变化时，触发该回调。只有手动触发且MenuItem状态改变时才会触发onChange回调。

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

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

参数：

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

MenuItemGroup

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

参数：

参数	类型	必填	参数描述
value	MenuItemGroupOptions	否	包含设置MenuItemGroup的标题和尾部显示信息。

MenuItemGroupOptions类型说明

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

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

Navigation

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

参数：

参数名	参数类型	必填	参数描述
pathInfos	NavPathStack	否	路由栈信息。

属性

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

title

title(value: ResourceStr | CustomBuilder | NavigationCommonTitle | NavigationCustomTitle, options?: NavigationTitleOptions)

设置页面标题。

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

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

参数：

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

subTitle(deprecated)

subTitle(value: string)

设置页面副标题。

从API Version 9开始废弃，建议使用title代替。

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

参数：

参数名	类型	必填	说明
value	string	是	页面副标题。

menus

menus(value: Array | CustomBuilder)

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

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

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

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

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

参数：

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

titleMode

titleMode(value: NavigationTitleMode)

设置页面标题栏显示模式。

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

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

参数：

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

toolBar(deprecated)

toolBar(value: object | CustomBuilder)

设置工具栏内容。不设置时不显示工具栏。items均分底部工具栏，在每个均分内容区布局文本和图标，文本超长时，逐级缩小，缩小之后换行，最后…截断。

从API version 10开始，该接口不再维护，推荐使用toolbarConfiguration代替。

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

参数：

参数名	类型	必填	说明
value	object \| CustomBuilder	是	工具栏内容。

object类型说明：

名称	类型	必填	描述
value	string	是	工具栏单个选项的显示文本。
icon	string	否	工具栏单个选项的图标资源路径。
action	() => void	否	当前选项被选中的事件回调。

toolbarConfiguration10+

toolbarConfiguration(value: Array | CustomBuilder, options?: NavigationToolbarOptions)

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

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

设置工具栏内容。不设置时不显示工具栏。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

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

hideToolBar

hideToolBar(value: boolean)

设置是否隐藏工具栏。

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

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

参数：

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

hideTitleBar

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

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

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

参数：

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

hideBackButton

hideBackButton(value: boolean)

设置是否隐藏标题栏中的返回键。返回键仅针对titleMode为NavigationTitleMode.Mini时才生效。

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

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

参数：

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

navBarWidth9+

navBarWidth(value: Length)

设置导航栏宽度。仅在Navigation组件分栏时生效。

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

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

参数：

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

navBarPosition9+

navBarPosition(value: NavBarPosition)

设置导航栏位置。仅在Navigation组件分栏时生效。

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

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

参数：

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

mode9+

mode(value: NavigationMode)

设置导航栏的显示模式。支持Stack、Split与Auto模式。

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

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

参数：

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

backButtonIcon9+

backButtonIcon(value: string | PixelMap | Resource | SymbolGlyphModifier)

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

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

设置标题栏中返回键图标。

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

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

参数：

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

hideNavBar9+

hideNavBar(value: boolean)

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

从API Version 9开始到API Version 10仅在双栏模式下生效。从API Version 11开始在单栏、双栏与自适应模式均生效。

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

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

参数：

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

navDestination10+

navDestination(builder: (name: string, param: unknown) => void)

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

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

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

参数：

参数名	类型	必填	说明
builder	(name: string, param: unknown) => void	是	创建NavDestination组件。

navBarWidthRange10+

navBarWidthRange(value: [Dimension, Dimension])

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

规则： 优先级规则详见说明。

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

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

参数：

参数名	类型	必填	说明
value	[Dimension, Dimension]	是	导航栏最小和最大宽度。默认值：最小默认值 240，最大默认值为组件宽度的40% ，且不大于 432，如果只设置一个值，则未设置的值按照默认值计算。单位：vp

minContentWidth10+

minContentWidth(value: Dimension)

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

规则： 优先级规则详见说明。

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

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

参数：

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

仅设置navBarWidth，不支持Navigation分割线拖拽。
navBarWidthRange指定分割线可以拖拽范围。如果不设置值，则按照默认值处理。拖拽范围需要满足navBarWidthRange设置的范围和minContentWidth限制。
Navigation显示范围缩小：a. 缩小内容区大小。如果不设置minContentWidth属性，则可以缩小内容区至0，否则最小缩小至minContentWidth。b. 缩小导航栏大小，缩小时需要满足导航栏宽度大于navBarRange的下限。c. 对显示内容进行裁切。

ignoreLayoutSafeArea12+

ignoreLayoutSafeArea(types?: Array, edges?: Array)

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

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

参数：

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

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

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

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

systemBarStyle12+

systemBarStyle(style: Optional)

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

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

参数：

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

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

事件

onTitleModeChange

onTitleModeChange(callback: (titleMode: NavigationTitleMode) => void)

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

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

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

参数：

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

onNavBarStateChange9+

onNavBarStateChange(callback: (isVisible: boolean) => void)

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

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

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

参数：

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

onNavigationModeChange11+

onNavigationModeChange(callback: (mode: NavigationMode) => void)

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

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

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

参数：

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

customNavContentTransition11+

customNavContentTransition(delegate(from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => NavigationAnimatedTransition | undefined)

自定义转场动画回调。

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

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

参数：

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

返回值：

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

NavPathStack10+

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

pushPath10+

pushPath(info: NavPathInfo, animated?: boolean): void

将info指定的NavDestination页面信息入栈。

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
animated11+	boolean	否	是否支持转场动画，默认值：true。

pushPath12+

pushPath(info: NavPathInfo, options?: NavigationOptions): void

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
options	NavigationOptions	否	页面栈操作选项。

pushPathByName10+

pushPathByName(name: string, param: unknown, animated?: boolean): void

将name指定的NavDestination页面信息入栈，传递的数据为param。

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

参数：

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

pushPathByName11+

pushPathByName(name: string, param: Object, onPop: Callback, animated?: boolean): void

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

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

参数：

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

pushDestination11+

pushDestination(info: NavPathInfo, animated?: boolean): Promise

将info指定的NavDestination页面信息入栈，使用Promise异步回调返回接口调用结果。

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

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

错误码：

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

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

pushDestination12+

pushDestination(info: NavPathInfo, options?: NavigationOptions): Promise

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	NavDestination页面的信息。
options	NavigationOptions	否	页面栈操作选项。

返回值：

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

错误码：

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

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

pushDestinationByName11+

pushDestinationByName(name: string, param: Object, animated?: boolean): Promise

将name指定的NavDestination页面信息入栈，传递的数据为param，使用Promise异步回调返回接口调用结果。

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

参数：

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

返回值：

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

错误码：

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

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

pushDestinationByName11+

pushDestinationByName(name: string, param: Object, onPop: Callback, animated?: boolean): Promise

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

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	Object	是	NavDestination页面详细参数。
onPop	Callback<PopInfo>	是	Callback回调，用于页面出栈时处理返回结果。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

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

错误码：

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

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

replacePath11+

replacePath(info: NavPathInfo, animated?: boolean): void

将当前页面栈栈顶退出，将info指定的NavDestination页面信息入栈。

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	新栈顶页面参数信息
animated11+	boolean	否	是否支持转场动画，默认值：true。

replacePath12+

replacePath(info: NavPathInfo, options?: NavigationOptions): void

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

参数：

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

replacePathByName11+

replacePathByName(name: string, param: Object, animated?: boolean): void

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

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

参数：

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

removeByIndexes11+

removeByIndexes(indexes: Array): number

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

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

参数：

名称	类型	必填	描述
indexes	Array	是	待删除NavDestination页面的索引值数组。

返回值：

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

removeByName11+

removeByName(name: string): number

将页面栈内指定name的NavDestination页面删除。

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

参数：

名称	类型	必填	描述
name	string	是	删除的NavDestination页面的名字。

返回值：

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

pop10+

pop(animated?: boolean): NavPathInfo | undefined

弹出路由栈栈顶元素。

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

参数：

名称	类型	必填	描述
animated11+	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
NavPathInfo	返回栈顶NavDestination页面的信息。
undefined	当路由栈为空时返回undefined。

pop11+

pop(result: Object, animated?: boolean): NavPathInfo | undefined

弹出路由栈栈顶元素，并触发onPop回调传入页面处理结果。

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

参数：

名称	类型	必填	描述
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
NavPathInfo	返回栈顶NavDestination页面的信息。
undefined	当路由栈为空时返回undefined。

popToName10+

popToName(name: string, animated?: boolean): number

回退路由栈到由栈底开始第一个名为name的NavDestination页面。

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
animated11+	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
number	如果栈中存在名为name的NavDestination页面，则返回由栈底开始第一个名为name的NavDestination页面的索引，否则返回-1。

popToName11+

popToName(name: string, result: Object, animated?: boolean): number

回退路由栈到由栈底开始第一个名为name的NavDestination页面，并触发onPop回调传入页面处理结果。

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
number	如果栈中存在名为name的NavDestination页面，则返回由栈底开始第一个名为name的NavDestination页面的索引，否则返回-1。

popToIndex10+

popToIndex(index: number, animated?: boolean): void

回退路由栈到index指定的NavDestination页面。

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。
animated11+	boolean	否	是否支持转场动画，默认值：true。

popToIndex11+

popToIndex(index: number, result: Object, animated?: boolean): void

回退路由栈到index指定的NavDestination页面，并触发onPop回调传入页面处理结果。

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。
result	Object	是	页面自定义处理结果。
animated	boolean	否	是否支持转场动画，默认值：true。

moveToTop10+

moveToTop(name: string, animated?: boolean): number

将由栈底开始第一个名为name的NavDestination页面移到栈顶。

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
animated11+	boolean	否	是否支持转场动画，默认值：true。

返回值：

类型	说明
number	如果栈中存在名为name的NavDestination页面，则返回由栈底开始第一个名为name的NavDestination页面的当前索引，否则返回-1。

moveIndexToTop10+

moveIndexToTop(index: number, animated?: boolean): void

将index指定的NavDestination页面移到栈顶。

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。
animated11+	boolean	否	是否支持转场动画，默认值：true。

clear10+

clear(animated?: boolean): void

清除栈中所有页面。

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

参数：

名称	类型	必填	描述
animated11+	boolean	否	是否支持转场动画，默认值：true。

getAllPathName10+

getAllPathName(): Array

获取栈中所有NavDestination页面的名称。

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

返回值：

类型	说明
Array	返回栈中所有NavDestination页面的名称。

getParamByIndex10+

getParamByIndex(index: number): unknown | undefined

获取index指定的NavDestination页面的参数信息。

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

参数：

名称	类型	必填	描述
index	number	是	NavDestination页面的位置索引。

返回值：

类型	说明
unknown	返回对应NavDestination页面的参数信息。
undefined	传入index无效时返回undefined。

getParamByName10+

getParamByName(name: string): Array

获取全部名为name的NavDestination页面的参数信息。

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。

返回值：

类型	说明
Array	返回全部名为name的NavDestination页面的参数信息。

getIndexByName10+

getIndexByName(name: string): Array

获取全部名为name的NavDestination页面的位置索引。

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。

返回值：

类型	说明
Array	返回全部名为name的NavDestination页面的位置索引。

size10+

size(): number

获取栈大小。

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

返回值：

类型	说明
number	返回栈大小。

disableAnimation11+

disableAnimation(value: boolean): void

关闭（true）或打开（false）当前Navigation中所有转场动画。

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

参数：

名称	类型	必填	描述
value	boolean	否	是否关闭转场动画，默认值：false。

getParent11+

getParent(): NavPathStack | null

获取父NavPathStack。

当出现Navigation嵌套Navigation的情况时（可以是直接嵌套，也可以是间接嵌套），内部Navigation的NavPathStack能够获取到外层Navigation的NavPathStack。

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

返回值：

类型	说明
NavPathStack \| null	如果当前NavPathStack所属Navigation的外层有另外的一层Navigation，则能够获取到外层Navigation的NavPathStack。否则获取不到NavPathStack，返回null。

setInterception12+

setInterception(interception: NavigationInterception): void

设置Navigation页面跳转拦截回调。

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

参数：

名称	类型	必填	描述
interception	NavigationInterception	是	设置Navigation跳转拦截对象。

NavPathInfo10+

路由页面信息。

constructor

constructor(name: string, param: unknown, onPop?: Callback)

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

参数：

名称	类型	必填	描述
name	string	是	NavDestination页面名称。
param	unknown	否	NavDestination页面详细参数。
onPop11+	Callback<PopInfo>	否	NavDestination页面触发pop时返回的回调。

PopInfo11+

下一个页面返回的回调信息载体。

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

参数：

名称	类型	必填	描述
info	NavPathInfo	是	页面触发返回时的当前页面信息，系统自动获取填入，无需开发者传入。
result	Object	是	页面触发返回时的结果，开发者自定义对象。

NavContentInfo11+

跳转Destination信息。

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

参数：

名称	类型	必填	描述
name	string	否	NavDestination名称，如果为根视图(NavBar)，则返回值为undefined。
index	number	是	NavDestination在NavPathStack中的序号，如果为根视图(NavBar)，则返回值为 -1。
mode	NavDestinationMode	否	NavDestination的模式，如果是根视图(NavBar)，则返回值为undefined。
param12+	Object	否	NavDestination页面加载的参数。
navDestinationId12+	string	否	NavDestination的唯一标识符。

NavigationAnimatedTransition11+

自定义转场动画协议，开发者需实现该协议来定义Navigation路由跳转的跳转动画。

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

参数：

名称	类型	必填	描述
timeout	number	否	动画超时结束时间。单位：ms。默认值：可交互动画无默认值，不可交互动画默认超时时间为1000ms。
transition	(transitionProxy : NavigationTransitionProxy) => void	是	自定义转场动画执行回调。transitionProxy: 自定义转场动画代理对象。
onTransitionEnd	(success: boolean):void	否	转场完成回调。success: 转场是否成功。
isInteractive12+	boolean	否	本次转场动画是否为可交互转场。默认值：false。

NavigationTransitionProxy 11+

自定义转场动画代理对象。

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

参数：

名称	类型	必填	描述
from	NavContentInfo	是	退场页面信息。
to	NavContentInfo	是	进场页面信息。
isInteractive12+	boolean	否	是否为可交互转场动画。

finishTransition

结束本次自定义转场动画，开发者需要主动触发该方法来结束本次转场，否则系统会在timeout的时间后结束本次转场。

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

cancelTransition12+

取消本次交互转场，恢复到页面跳转前的页面栈(不支持取消不可交互转场动画)。

updateTransition12+

更新交互转场动画进度(不可交互动画不支持动画进度设置)。

参数：

名称	类型	必填	描述
progress	number	是	设置交互转场动画进度百分比。取值范围 0-1。

NavigationInterception12+

Navigation跳转拦截对象。

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

名称	类型	必填	描述
willShow	InterceptionShowCallback	否	页面跳转前拦截，允许操作栈，在当前跳转中生效。
didShow	InterceptionShowCallback	否	页面跳转后回调。在该回调中操作栈在下一次跳转中刷新。
modeChange	InterceptionModeCallback	否	Navigation单双栏显示状态发生变更时触发该回调。

InterceptionShowCallback12+

type InterceptionShowCallback = (from: NavDestinationContext|NavBar, to: NavDestinationContext|NavBar, operation: NavigationOperation, isAnimated: boolean) => void

navigation页面跳转前和页面跳转后的拦截回调。

参数名	类型	必填	说明
from	NavDestinationContext \|NavBar	是	页面跳转之前的栈顶页面信息。参数值为navBar，则表示跳转前的页面为Navigation首页。
to	NavDestinationContext \|NavBar	是	页面跳转之后的栈顶页面信息。参数值为navBar，则表示跳转的目标页面为Navigation首页。
operation	NavigationOperation	是	当前页面跳转类型。
isAnimated	boolean	是	页面跳转是否有动画。

InterceptionModeCallback12+

type InterceptionModeCallback = (mode: NavigationMode) => void

navigation单双栏显示状态发生变更时的拦截回调。

参数名	类型	必填	说明
mode	NavigationMode	是	导航栏的显示模式。

NavBar12+

名称	描述
“navBar”	Navigation首页。

NavigationMenuItem类型说明

名称	类型	必填	描述
value	string	是	API Version 9: 显示菜单栏单个选项的文本。API Version 10: 不显示菜单栏单个选项的文本。元服务API：从API version 11开始，该接口支持在元服务中使用。
icon	string	否	菜单栏单个选项的图标资源路径。元服务API：从API version 11开始，该接口支持在元服务中使用。
isEnabled12+	boolean	否	使能状态，默认使能（false未使能，true使能）。元服务API：从API version 12开始，该接口支持在元服务中使用。
action	() => void	否	当前选项被选中的事件回调。元服务API：从API version 11开始，该接口支持在元服务中使用。
symbolIcon12+	SymbolGlyphModifier	否	菜单栏单个选项的symbol资源（优先级高于icon）。

object类型说明

名称	类型	必填	描述
value	string	是	工具栏单个选项的显示文本。
icon	string	否	工具栏单个选项的图标资源路径。
action	() => void	否	当前选项被选中的事件回调。

ToolbarItem10+类型说明

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

名称	类型	必填	描述
value	ResourceStr	是	工具栏单个选项的显示文本。
icon	ResourceStr	否	工具栏单个选项的图标资源路径。
action	() => void	否	当前选项被选中的事件回调。
status	ToolbarItemStatus	否	工具栏单个选项的状态。默认值：ToolbarItemStatus.NORMAL
activeIcon	ResourceStr	否	工具栏单个选项处于ACTIVE态时的图标资源路径。
symbolIcon12+	SymbolGlyphModifier	否	工具栏单个选项的symbol资源（优先级高于icon）。
activeSymbolIcon12+	SymbolGlyphModifier	否	工具栏单个选项处于ACTIVE态时的symbol资源（优先级高于activeIcon）。

ToolbarItemStatus10+枚举说明

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

名称	描述
NORMAL	设置工具栏单个选项为NORMAL态，该选项显示默认样式，可以触发Hover，Press，Focus事件并显示对应的多态样式。
DISABLED	设置工具栏单个选项为DISABLED态，该选项显示DISABLED态样式，并且不可交互。
ACTIVE	设置工具栏单个选项为ACTIVE态，该选项通过点击事件可以将icon图标更新为activeIcon对应的图片资源。

NavigationTitleMode枚举说明

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

名称	描述
Free	当内容为满一屏的可滚动组件时，标题随着内容向上滚动而缩小（子标题的大小不变、淡出）。向下滚动内容到顶时则恢复原样。说明：标题随着内容滚动大小联动的动效在title设置为ResourceStr和NavigationCommonTitle时生效，设置成其余自定义节点类型时字体样式无法变化，下拉时只影响标题栏偏移。可滚动组件不满一屏时，如果想使用联动效果，就要使用滚动组件提供的edgeEffect接口将options参数设置为true。未滚动状态，标题栏高度与Full模式一致；滚动时，标题栏的最小高度与Mini模式一致。
Mini	固定为小标题模式。默认值：API version 12之前，只有主标题时，标题栏高度为56vp；同时有主标题和副标题时，标题栏高度为82vp。从API version 12开始，该模式下标题栏高度为56vp。
Full	固定为大标题模式。默认值：只有主标题时，标题栏高度为112vp；同时有主标题和副标题时，标题栏高度为138vp。

NavigationCommonTitle9+类型说明

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

名称	类型	必填	描述
main	string	是	设置主标题。
sub	string	是	设置副标题。

NavigationCustomTitle9+类型说明

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

名称	类型	必填	描述
builder	CustomBuilder	是	设置标题栏内容。
height	TitleHeight \| Length	是	设置标题栏高度。

NavBarPosition9+枚举说明

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

名称	描述
Start	双栏显示时，主列在主轴方向首部。
End	双栏显示时，主列在主轴方向尾部。

NavigationMode9+枚举说明

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

名称	描述
Stack	导航栏与内容区独立显示，相当于两个页面。
Split	导航栏与内容区分两栏显示。以下navBarWidthRange的值用[minNavBarWidth,maxNavBarWidth]表示1.当navBarWidth属性的值，在navBarWidthRange属性的值范围以外时，navBarWidth按如下规则显示：navBarWidth < minNavBarWidth时，navBarWidth修正为minNavBarWidth;navBarWidth > maxNavBarWidth，且组件宽度 - minContentWidth - 分割线宽度(1vp) > maxNavBarWidth时，navBarWidth修正为maxNavBarWidth;navBarWidth > maxNavBarWidth，且组件宽度 - minContentWidth - 分割线宽度(1vp) < minNavBarWidth时，navBarWidth修正为minNavBarWidth;navBarWidth > maxNavBarWidth，且组件宽度 - minContentWidth - 分割线宽度(1vp)在navBarWidthRange范围内，navBarWidth修正为组件宽度 - 分割线宽度(1vp) - minContentWidth。2.当navBarWidth属性的值，在navBarWidthRange属性的值范围以内时，navBarWidth按如下规则显示：minNavBarWidth + minContentWidth + 分割线宽度(1vp) >= 组件宽度时，navBarWidth修正为minNavBarWidth；minNavBarWidth + minContentWidth + 分割线宽度(1vp) < 组件宽度，且navBarWidth + minContentWidth + 分割线宽度(1vp) >= 组件宽度时，navBarWidth修正为组件宽度 - 分割线宽度(1vp) - minContentWidth;minNavBarWidth + minContentWidth + 分割线宽度(1vp) < 组件宽度，且navBarWidth + minContentWidth + 分割线宽度(1vp) < 组件宽度时，navBarWidth为设置的值。3.缩小组件尺寸时，先缩小内容区的尺寸至minContentWidth，然后再缩小导航栏的尺寸至minNavBarWidth。若继续缩小，先缩小内容区，内容区消失后再缩小导航栏。4.设置导航栏为固定尺寸时，若持续缩小组件尺寸，导航栏最后压缩显示。5.若只设置了navBarWidth属性，则导航栏宽度为navBarWidth，且分割线不可拖动。
Auto	API version 9之前：窗口宽度>=520vp时，采用Split模式显示；窗口宽度<520vp时，采用Stack模式显示。API version 10及以上：窗口宽度>=600vp时，采用Split模式显示；窗口宽度<600vp时，采用Stack模式显示，600vp等于minNavBarWidth(240vp) + minContentWidth (360vp)。

TitleHeight9+枚举说明

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

名称	描述
MainOnly	只有主标题时标题栏的推荐高度（56vp）。
MainWithSub	同时有主标题和副标题时标题栏的推荐高度（82vp）。

NavigationOperation11+枚举说明

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

名称	描述
PUSH	本次转场为页面进场。
POP	本次转场为页面退场。
REPLACE	本次转场为页面替换。

BarStyle12+枚举说明

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

名称	描述
STANDARD	标题栏与内容区采用上下布局。
STACK	标题栏与内容区采用层叠布局，标题栏布局在内容区上层。

NavigationTitleOptions11+类型说明

名称	类型	必填	描述
backgroundColor	ResourceColor	否	标题栏背景颜色，不设置时为系统默认颜色。元服务API：从API version 11开始，该接口支持在元服务中使用。
backgroundBlurStyle	BlurStyle	否	标题栏背景模糊样式，不设置时关闭背景模糊效果。元服务API：从API version 11开始，该接口支持在元服务中使用。
barStyle12+	BarStyle	否	标题栏布局方式设置。默认值：BarStyle.STANDARD元服务API：从API version 12开始，该接口支持在元服务中使用。
paddingStart12+	LengthMetrics	否	标题栏起始端内间距。仅支持以下任一场景:1. 显示返回图标，即hideBackButton为false；2. 使用非自定义标题，即标题value类型为ResourceStr或NavigationCommonTitle。默认值：LengthMetrics.resource($r(‘sys.float.margin_left’))。元服务API：从API version 12开始，该接口支持在元服务中使用。
paddingEnd12+	LengthMetrics	否	标题栏结束端内间距。仅支持以下任一场景:1. 使用非自定义菜单，即菜单value为Array；2. 没有右上角菜单，且使用非自定义标题，即标题value类型为ResourceStr或NavigationCommonTitle。默认值：LengthMetrics.resource($r(‘sys.float.margin_right’))。元服务API：从API version 12开始，该接口支持在元服务中使用。

NavigationToolbarOptions11+类型说明

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

名称	类型	必填	描述
backgroundColor	ResourceColor	否	工具栏背景颜色，不设置时为系统默认颜色。
backgroundBlurStyle	BlurStyle	否	工具栏背景模糊样式，不设置时关闭背景模糊效果。

LaunchMode12+枚举说明

名称	描述
STANDARD	系统默认的栈操作模式。push操作会将指定的NavDestination入栈；replace操作会将当前栈顶NavDestination替换。
MOVE_TO_TOP_SINGLETON	从栈底向栈顶查找，如果指定的名称已经存在，则将对应的NavDestination页面移到栈顶（replace操作会将最后的栈顶替换成指定的NavDestination），否则行为和STANDARD一致。
POP_TO_SINGLETON	从栈底向栈顶查找，如果指定的名称已经存在，则将其上方的NavDestination页面全部移除（replace操作会将最后的栈顶替换成指定的NavDestination），否则行为和STANDARD一致。

NavigationOptions12+类型说明

名称	类型	必填	描述
launchMode	LaunchMode	否	页面栈的操作模式。默认值：LaunchMode.STANDARD
animated	boolean	否	是否支持转场动画。默认值：true。

示例1

// xxx.ets
class A {text: string = ''num: number = 0
}@Entry
@Component
struct NavigationExample {private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]@State currentIndex: number = 0@Builder NavigationTitle() {Column() {Text('Title').fontColor('#182431').fontSize(30).lineHeight(41).fontWeight(700)Text('subtitle').fontColor('#182431').fontSize(14).lineHeight(19).opacity(0.4).margin({ top: 2, bottom: 20 })}.alignItems(HorizontalAlign.Start)}@Builder NavigationMenus() {Row() {Image('resources/base/media/ic_public_add.svg').width(24).height(24)Image('resources/base/media/ic_public_add.svg').width(24).height(24).margin({ left: 24 })Image('common/ic_public_more.svg').width(24).height(24).margin({ left: 24 })}}build() {Column() {Navigation() {TextInput({ placeholder: 'search...' }).width('90%').height(40).backgroundColor('#FFFFFF').margin({ top: 8 })List({ space: 12, initialIndex: 0 }) {ForEach(this.arr, (item: number) => {ListItem() {Text('' + item).width('90%').height(72).backgroundColor('#FFFFFF').borderRadius(24).fontSize(16).fontWeight(500).textAlign(TextAlign.Center)}}, (item: number) => item.toString())}.height(324).width('100%').margin({ top: 12, left: '10%' })}.title(this.NavigationTitle).menus(this.NavigationMenus).titleMode(NavigationTitleMode.Full).toolbarConfiguration([{value: $r("app.string.navigation_toolbar_add"),icon: $r("app.media.ic_public_highlightsed")},{value: $r("app.string.navigation_toolbar_app"),icon: $r("app.media.ic_public_highlights")},{value: $r("app.string.navigation_toolbar_collect"),icon: $r("app.media.ic_public_highlights")}]).hideTitleBar(false).hideToolBar(false).onTitleModeChange((titleModel: NavigationTitleMode) => {console.info('titleMode' + titleModel)})}.width('100%').height('100%').backgroundColor('#F1F3F5')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2

// Index.ets@Entry
@Component
struct NavigationExample {pageInfos: NavPathStack = new NavPathStack()isUseInterception: boolean = false;registerInterception() {this.pageInfos.setInterception({willShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar",operation: NavigationOperation, animated: boolean) => {if (!this.isUseInterception) {return;}if (typeof to === "string") {console.log("target page is navigation home");return;}// redirect target page.Change pageTwo to pageOne.let target: NavDestinationContext = to as NavDestinationContext;if (target.pathInfo.name === 'pageTwo') {target.pathStack.pop();target.pathStack.pushPathByName('pageOne', null);}},didShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar",operation: NavigationOperation, isAnimated: boolean) => {if (!this.isUseInterception) {return;}if (typeof from === "string") {console.log("current transition is from navigation home");} else {console.log(`current transition is from  ${(from as NavDestinationContext).pathInfo.name}`)}if (typeof to === "string") {console.log("current transition to is navBar");} else {console.log(`current transition is to ${(to as NavDestinationContext).pathInfo.name}`);}},modeChange: (mode: NavigationMode) => {if (!this.isUseInterception) {return;}console.log(`current navigation mode is ${mode}`);}})}build() {Navigation(this.pageInfos) {Column() {Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.pushPath({ name: 'pageOne' }) //将name指定的NavDestination页面信息入栈})Button('use interception', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.isUseInterception = !this.isUseInterception;if (this.isUseInterception) {this.registerInterception();} else {this.pageInfos.setInterception(undefined);}})}}.title('NavIndex')}
}
// PageOne.ets
class TmpClass{count:number=10
}@Builder
export function PageOneBuilder(name: string, param: Object) {PageOne()
}@Component
export struct PageOne {pageInfos: NavPathStack = new NavPathStack()build() {NavDestination() {Column() {Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {let tmp = new TmpClass()this.pageInfos.pushPathByName('pageTwo', tmp) //将name指定的NavDestination页面信息入栈，传递的数据为param})Button('popToname', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.popToName('pageTwo') //回退路由栈到第一个名为name的NavDestination页面console.log('popToName' + JSON.stringify(this.pageInfos), '返回值' + JSON.stringify(this.pageInfos.popToName('pageTwo')))})Button('popToIndex', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.popToIndex(1) // 回退路由栈到index指定的NavDestination页面console.log('popToIndex' + JSON.stringify(this.pageInfos))})Button('moveToTop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.moveToTop('pageTwo') // 将第一个名为name的NavDestination页面移到栈顶console.log('moveToTop' + JSON.stringify(this.pageInfos), '返回值' + JSON.stringify(this.pageInfos.moveToTop('pageTwo')))})Button('moveIndexToTop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.moveIndexToTop(1) // 将index指定的NavDestination页面移到栈顶console.log('moveIndexToTop' + JSON.stringify(this.pageInfos))})Button('clear', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfos.clear() //清除栈中所有页面})Button('get', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {console.log('-------------------')console.log('获取栈中所有NavDestination页面的名称', JSON.stringify(this.pageInfos.getAllPathName()))console.log('获取index指定的NavDestination页面的参数信息', JSON.stringify(this.pageInfos.getParamByIndex(1)))console.log('获取全部名为name的NavDestination页面的参数信息', JSON.stringify(this.pageInfos.getParamByName('pageTwo')))console.log('获取全部名为name的NavDestination页面的位置索引', JSON.stringify(this.pageInfos.getIndexByName('pageOne')))console.log('获取栈大小', JSON.stringify(this.pageInfos.size()))})}.width('100%').height('100%')}.title('pageOne').onBackPressed(() => {const popDestinationInfo = this.pageInfos.pop() // 弹出路由栈栈顶元素console.log('pop' + '返回值' + JSON.stringify(popDestinationInfo))return true}).onReady((context: NavDestinationContext) => {this.pageInfos = context.pathStack})}
}
// PageTwo.ets
@Builder
export function PageTwoBuilder(name: string, param: Object) {PageTwo()
}@Component
export struct PageTwo {pathStack: NavPathStack = new NavPathStack()private menuItems: Array<NavigationMenuItem> = [{value: "1",icon: 'resources/base/media/undo.svg',},{value: "2",icon: 'resources/base/media/redo.svg',isEnabled: false,},{value: "3",icon: 'resources/base/media/ic_public_ok.svg',isEnabled: true,}]build() {NavDestination() {Column() {Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.pushPathByName('pageOne', null)})}.width('100%').height('100%')}.title('pageTwo').menus(this.menuItems).onBackPressed(() => {this.pathStack.pop()return true}).onReady((context: NavDestinationContext) => {this.pathStack = context.pathStack;console.log("current page config info is " + JSON.stringify(context.getConfigInRouteMap()))})}
}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/PageOne.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}},{"name": "pageTwo","pageSourceFile": "src/main/ets/pages/PageTwo.ets","buildFunction": "PageTwoBuilder"}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例3

该示例主要演示设置每个NavDestination子页面的自定义转场动画及可交互转场动画。

// Index.ets
import { CustomTransition, AnimateCallback } from './CustomNavigationUtils'@Entry
@Component
struct NavigationExample {pageInfos: NavPathStack = new NavPathStack();aboutToAppear() {if (this.pageInfos === undefined) {this.pageInfos = new NavPathStack();}this.pageInfos.pushPath({ name: 'pageOne', param: CustomTransition.getInstance().getAnimationId() });}build() {Navigation(this.pageInfos) {}.title('NavIndex').hideNavBar(true).customNavContentTransition((from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => {if (from.mode == NavDestinationMode.DIALOG || to.mode == NavDestinationMode.DIALOG) {return undefined;}// 首页不进行自定义动画if (from.index === -1 || to.index === -1) {return undefined;}CustomTransition.getInstance().operation = operation;if (CustomTransition.getInstance().interactive) {let customAnimation: NavigationAnimatedTransition = {onTransitionEnd: (isSuccess: boolean) => {console.log("===== current transition is " + isSuccess);CustomTransition.getInstance().recoverState();CustomTransition.getInstance().proxy = undefined;},transition: (transitionProxy: NavigationTransitionProxy) => {CustomTransition.getInstance().proxy = transitionProxy;let targetIndex: string | undefined = operation == NavigationOperation.PUSH ?(to.navDestinationId) : (from.navDestinationId);if (targetIndex) {CustomTransition.getInstance().fireInteractiveAnimation(targetIndex, operation);}},isInteractive: CustomTransition.getInstance().interactive}return customAnimation;}let customAnimation: NavigationAnimatedTransition = {onTransitionEnd: (isSuccess: boolean)=>{console.log(`current transition result is ${isSuccess}`)},timeout: 7000,// 转场开始时系统调用该方法，并传入转场上下文代理对象transition: (transitionProxy: NavigationTransitionProxy) => {if (!from.navDestinationId || !to.navDestinationId) {return;}// 从封装类CustomTransition中根据子页面的序列获取对应的转场动画回调let fromParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(from.navDestinationId);let toParam: AnimateCallback = CustomTransition.getInstance().getAnimateParam(to.navDestinationId);if (operation == NavigationOperation.PUSH) {if (toParam.start) {toParam.start(true, false);}animateTo({duration: 500, onFinish: () => {transitionProxy.finishTransition();}}, () => {if (toParam.finish) {toParam.finish(true, false);}})} else {if (fromParam.start) {fromParam.start(true, true);}animateTo({duration: 500, onFinish: () => {transitionProxy.finishTransition();}}, () => {if (fromParam.finish) {fromParam.finish(true, true);}})}}};return customAnimation;})}
}
// PageOne.ets
import {CustomTransition} from './CustomNavigationUtils';@Builder
export function PageOneBuilder(name: string, param: Object) {PageOne()
}@Component
export struct PageOne {pageInfos: NavPathStack = new NavPathStack();@State translateX: string = '0';pageId: string = '';rectWidth: number = 0;interactive: boolean = false;registerCallback() {CustomTransition.getInstance().registerNavParam(this.pageId, (isPush: boolean, isExit: boolean) => {if (isPush) {this.translateX = '100%';} else {this.translateX = '0';}}, (isPush: boolean, isExit: boolean) => {if (isPush) {this.translateX = '0';} else {this.translateX = '100%';}}, (isPush: boolean, isExit: boolean) => {this.translateX = '0';}, (operation: NavigationOperation) => {if (operation == NavigationOperation.PUSH) {this.translateX = '100%';animateTo({duration: 1000,onFinish: () => {this.translateX = '0';}}, () => {this.translateX = '0';})} else {this.translateX = '0';animateTo({duration: 1000,onFinish: () => {this.translateX = '0';}}, () => {this.translateX = '100%';})}}, 200);}build() {NavDestination() {Column() {Button(`setInteractive`).onClick(() => {CustomTransition.getInstance().interactive = !CustomTransition.getInstance().interactive;this.interactive = CustomTransition.getInstance().interactive;})Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {//将name指定的NavDestination页面信息入栈，传递的数据为paramthis.pageInfos.pushDestinationByName('pageTwo', CustomTransition.getInstance().getAnimationId());})}.size({ width: '100%', height: '100%' })}.title('pageOne').onDisAppear(() => {CustomTransition.getInstance().unRegisterNavParam(this.pageId);}).onReady((context: NavDestinationContext) => {this.pageInfos = context.pathStack;if (context.navDestinationId) {this.pageId = context.navDestinationId;this.registerCallback();}}).translate({ x: this.translateX }).backgroundColor('#F1F3F5').gesture(PanGesture().onActionStart((event: GestureEvent) => {this.rectWidth = event.target.area.width as number;if (event.offsetX < 0) {this.pageInfos.pushPath({ name: 'pageTwo', param: CustomTransition.getInstance().getAnimationId() });} else {this.pageInfos.pop();}}).onActionUpdate((event: GestureEvent) => {let rate = event.fingerList[0].localX / this.rectWidth;CustomTransition.getInstance().updateProgress(rate);}).onActionEnd((event: GestureEvent) => {let rate: number = event.fingerList[0].localX / this.rectWidth;CustomTransition.getInstance().finishInteractiveAnimation(rate);}))}
}
// PageTwo.ets
import {CustomTransition} from './CustomNavigationUtils'@Builder
export function PageTwoBuilder(name: string, param: Object) {PageTwo({param: param as number})
}@Component
export struct PageTwo {pageInfos: NavPathStack = new NavPathStack();@State translateX: string = '0';pageId: string = '';rectWidth: number = 0;param: number = 0;registerCallback() {CustomTransition.getInstance().registerNavParam(this.pageId, (isPush: boolean, isExit: boolean)=>{if (isPush) {this.translateX =  '100%'} else {this.translateX = '0';}}, (isPush: boolean, isExit: boolean)=>{if (isPush) {this.translateX = '0';} else {this.translateX = '100%'}}, (isPush: boolean, isExit: boolean) => {this.translateX = '0';}, (operation: NavigationOperation)=>{if (operation == NavigationOperation.PUSH) {this.translateX = '100%';animateTo({duration: 500, onFinish: ()=>{this.translateX = '0';}}, ()=>{this.translateX = '0'})} else {this.translateX = '0';animateTo({duration: 500, onFinish: ()=>{this.translateX = "0"}}, ()=>{this.translateX = '100%';})}}, 2000)}build() {NavDestination() {Column() {Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {//将name指定的NavDestination页面信息入栈，传递的数据为paramthis.pageInfos.pushPath({name:'pageOne', param: CustomTransition.getInstance().getAnimationId()})})}.size({ width: '100%', height: '100%' })}.title('pageTwo').gesture(PanGesture().onActionStart((event: GestureEvent)=> {this.rectWidth = event.target.area.width as number;if (event.offsetX < 0) {this.pageInfos.pushPath({ name: 'pageOne', param: CustomTransition.getInstance().getAnimationId() });} else {this.pageInfos.pop();}}).onActionUpdate((event: GestureEvent) => {let rate = event.fingerList[0].localX / this.rectWidth;CustomTransition.getInstance().updateProgress(rate);}).onActionEnd((event: GestureEvent)=> {let rate = event.fingerList[0].localX / this.rectWidth;CustomTransition.getInstance().finishInteractiveAnimation(rate);})).onAppear(() => {this.registerCallback();}).onDisAppear(()=>{CustomTransition.getInstance().unRegisterNavParam(this.pageId);}).onReady((context: NavDestinationContext) => {this.pageInfos = context.pathStack;if (context.navDestinationId) {this.pageId = context.navDestinationId;this.registerCallback();}}).translate({x: this.translateX}).backgroundColor(Color.Yellow)}
}
// CustomNavigationUtils.ts
// 自定义接口，用来保存某个页面相关的转场动画回调和参数
export interface AnimateCallback {finish: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined;start: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined;onFinish: ((isPush: boolean, isExit: boolean) => void | undefined) | undefined;interactive: ((operation: NavigationOperation) => void | undefined) | undefined;timeout: (number | undefined) | undefined;
}
const customTransitionMap: Map<string, AnimateCallback> = new Map();export class CustomTransition {static delegate = new CustomTransition();interactive: boolean = false;proxy: NavigationTransitionProxy| undefined = undefined;private animationId: number = 0;operation: NavigationOperation = NavigationOperation.PUSHstatic getInstance() {return CustomTransition.delegate;}/* 注册某个页面的动画回调* name: 注册页面的唯一id* startCallback：用来设置动画开始时页面的状态* endCallback：用来设置动画结束时页面的状态* onFinish：用来执行动画结束后页面的其他操作* interactiveCallback: 注册的可交互转场的动效* timeout：转场结束的超时时间*/registerNavParam(name: string, startCallback: (operation: boolean, isExit: boolean) => void,endCallback:(operation: boolean, isExit: boolean) => void,onFinish: (operation: boolean, isExit: boolean) => void,interactiveCallback: (operation: NavigationOperation) =>void,timeout: number): void {if (customTransitionMap.has(name)) {let param = customTransitionMap.get(name);if (param != undefined) {param.start = startCallback;param.finish = endCallback;param.timeout = timeout;param.onFinish = onFinish;param.interactive = interactiveCallback;return;}}let params: AnimateCallback = {timeout: timeout, start: startCallback, finish: endCallback, onFinish: onFinish,interactive: interactiveCallback};customTransitionMap.set(name, params);}getAnimationId() {return Date.now();}unRegisterNavParam(name: string): void {customTransitionMap.delete(name);}fireInteractiveAnimation(id: string, operation: NavigationOperation) {let animation = customTransitionMap.get(id)?.interactive;if (!animation) {return;}animation(operation);}updateProgress(progress: number) {if (!this.proxy?.updateTransition) {return;}progress = this.operation == NavigationOperation.PUSH ? 1 - progress : progress;this.proxy?.updateTransition(progress);}cancelTransition() {if (this.proxy?.cancelTransition) {this.proxy.cancelTransition();}}recoverState() {if (!this.proxy?.from.navDestinationId || !this.proxy?.to.navDestinationId) {return;}let fromParam = customTransitionMap.get(this.proxy.from.navDestinationId);if (fromParam?.onFinish) {fromParam.onFinish(false, false);}let toParam = customTransitionMap.get(this.proxy?.to.navDestinationId);if (toParam?.onFinish) {toParam.onFinish(true, true);}}finishTransition() {this.proxy?.finishTransition();}finishInteractiveAnimation(rate: number) {if (this.operation == NavigationOperation.PUSH) {if (rate > 0.5) {if (this.proxy?.cancelTransition) {this.proxy.cancelTransition();}} else {this.proxy?.finishTransition();}} else {if (rate > 0.5) {this.proxy?.finishTransition();} else {if (this.proxy?.cancelTransition) {this.proxy.cancelTransition();}}}}getAnimateParam(name: string): AnimateCallback {let result: AnimateCallback = {start: customTransitionMap.get(name)?.start,finish: customTransitionMap.get(name)?.finish,timeout: customTransitionMap.get(name)?.timeout,onFinish: customTransitionMap.get(name)?.onFinish,interactive: customTransitionMap.get(name)?.interactive,};return result;}
}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/PageOne.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}},{"name": "pageTwo","pageSourceFile": "src/main/ets/pages/PageTwo.ets","buildFunction": "PageTwoBuilder"}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例4

// Index.ets@Entry
@Component
struct NavigationExample {pageInfo: NavPathStack = new NavPathStack()build() {Navigation(this.pageInfo) {Column() {Button('StartTest', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pageInfo.pushPath({ name: 'pageOne' }); // 将name指定的NavDestination页面信息入栈。})}}.title('NavIndex')}
}
// PageOne.ets
import { BusinessError } from '@kit.BasicServicesKit';class TmpClass{count:number = 10
}class ParamWithOp {operation: number = 1count: number = 10
}@Builder
export function PageOneBuilder(name: string, param: Object) {PageOne()
}@Component
export struct PageOne {pageInfo: NavPathStack = new NavPathStack();@State message: string = 'Hello World'build() {NavDestination() {Column() {Text(this.message).width('80%').height(50).margin(10)Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(()=>{this.pageInfo.pushPath({name: 'pageTwo', param: new ParamWithOp(), onPop: (popInfo: PopInfo)=>{this.message = '[pushPath]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result);}}); // 将name指定的NavDestination页面信息入栈，传递的数据为param，添加接收处理结果的onPop回调。})Button('pushPathByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(() => {let tmp = new TmpClass()this.pageInfo.pushPathByName('pageTwo', tmp, (popInfo)=>{this.message = '[pushPathByName]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result);}); // 将name指定的NavDestination页面信息入栈，传递的数据为param，添加接收处理结果的onPop回调。})Button('pushDestination', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(()=>{let tmp = new TmpClass()// 将name指定的NavDestination页面信息入栈，传递的数据为param，添加接收处理结果的onPop回调。this.pageInfo.pushDestination({name: 'pageTwo', param: new ParamWithOp(), onPop: (popInfo: PopInfo)=>{this.message = '[pushDestination]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result);}}).catch((error: BusinessError)=>{console.error(`[pushDestination]failed, error code = ${error.code}, error.message = ${error.message}.`);}).then(()=>{console.error('[pushDestination]success.');});})Button('pushDestinationByName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(()=>{let tmp = new TmpClass()// 将name指定的NavDestination页面信息入栈，传递的数据为param，添加接收处理结果的onPop回调。this.pageInfo.pushDestinationByName('pageTwo', tmp, (popInfo)=>{this.message = '[pushDestinationByName]last page is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result);}).catch((error: BusinessError)=>{console.error(`[pushDestinationByName]failed, error code = ${error.code}, error.message = ${error.message}.`);}).then(()=>{console.error('[pushDestinationByName]success.');});})Button('pushPathWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(()=>{this.pageInfo.pushPath({name: 'pageTwo', param: new ParamWithOp()}); // 将name指定的NavDestination页面信息入栈。})Button('pushPathByNameWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(() => {let tmp = new TmpClass()this.pageInfo.pushPathByName('pageTwo', tmp); // 将name指定的NavDestination页面信息入栈，传递的数据为param。})Button('pushDestinationWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(()=>{let tmp = new TmpClass()// 将name指定的NavDestination页面信息入栈，传递的数据为param，添加接收处理结果的onPop回调。this.pageInfo.pushDestination({name: 'pageTwo', param: new ParamWithOp()}).catch((error: BusinessError)=>{console.error(`[pushDestinationWithoutOnPop]failed, error code = ${error.code}, error.message = ${error.message}.`);}).then(()=>{console.error('[pushDestinationWithoutOnPop]success.');});})Button('pushDestinationByNameWithoutOnPop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(() => {let tmp = new TmpClass()// 将name指定的NavDestination页面信息入栈，传递的数据为param。this.pageInfo.pushDestinationByName('pageTwo', tmp).catch((error: BusinessError)=>{console.error(`[pushDestinationByNameWithoutOnPop]failed, error code = ${error.code}, error.message = ${error.message}.`);}).then(()=>{console.error('[pushDestinationByNameWithoutOnPop]success.');});})Button('clear', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(10).onClick(() => {this.pageInfo.clear(); // 清除栈中所有页面。})}.width('100%').height('100%')}.title('pageOne').onBackPressed(() => {this.pageInfo.pop({number: 1}) // 弹出路由栈栈顶元素。return true}).onReady((context: NavDestinationContext) => {this.pageInfo = context.pathStack;})}
}
// PageTwo.etsclass resultClass {constructor(count: number) {this.count = count;}count: number = 10
}@Builder
export function PageTwoBuilder() {PageTwo()
}@Component
export struct PageTwo {pathStack: NavPathStack = new NavPathStack()build() {NavDestination() {Column() {Button('pop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.pop(new resultClass(1)); // 回退到上一个页面，将处理结果传入push的onPop回调中。})Button('popToName', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.popToName('pageOne', new resultClass(11)); // 将第一个名为name的NavDestination页面移到栈顶，将处理结果传入push的onPop回调中。})Button('popToIndex', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.popToIndex(0, new resultClass(111)); // 将index指定的NavDestination页面移到栈顶，将处理结果传入push的onPop回调中。})Button('popWithoutResult', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.pop();})Button('popToNameWithoutResult', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.popToName('pageOne');})Button('popToIndexWithoutResult', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.pathStack.popToIndex(0);})}.width('100%').height('100%')}.title('pageTwo').onBackPressed(() => {this.pathStack.pop(new resultClass(0)); // 回退到上一个页面，将处理结果传入push的onPop回调。return true;}).onReady((context: NavDestinationContext) => {this.pathStack = context.pathStack})}
}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/PageOne.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}},{"name": "pageTwo","pageSourceFile": "src/main/ets/pages/PageTwo.ets","buildFunction": "PageTwoBuilder"}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例5

// 该示例主要演示设置Navigation主页的标题栏、工具栏和
// NavDestination页面的标题栏的背景颜色和背景模糊效果。
let COLOR1: string = "#80004AAF";
let COLOR2: string = "#802787D9";
let BLUR_STYLE_1: BlurStyle = BlurStyle.BACKGROUND_THIN;
let BLUR_STYLE_2: BlurStyle = BlurStyle.BACKGROUND_THICK;@Component
struct BackComponent {build() {Row() {Column() {}.height('100%').backgroundColor("#3D9DB4").layoutWeight(9)Column() {}.height('100%').backgroundColor("17A98D").layoutWeight(9)Column() {}.height('100%').backgroundColor("FFC000").layoutWeight(9)}.height('100%').width('100%')}
}@Component
struct ColorAndBlur {@State useColor1: boolean = true;@State useBlur1: boolean = true;build() {NavDestination() {Stack({alignContent: Alignment.Center}) {BackComponent().width('100%').height('100%')Column() {Stack({alignContent: Alignment.Center}) {Button("switch color").onClick(() => {this.useColor1 = !this.useColor1;})}.width('100%').layoutWeight(1)Stack({alignContent: Alignment.Center}) {Button("switch blur").onClick(() => {this.useBlur1 = !this.useBlur1;})}.width('100%').layoutWeight(1)}.width('100%').height('100%')}.width('100%').height('100%')}.width('100%').height('100%')// 开发者可以设置标题栏的背景颜色和背景模糊效果.title("switch titlebar color and blur", {backgroundColor: this.useColor1 ? COLOR1 : COLOR2,backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2,barStyle: BarStyle.STACK})}
}@Entry
@Component
struct Index {private stack: NavPathStack = new NavPathStack();@State useColor1: boolean = true;@State useBlur1: boolean = true;@BuilderPageBuilder(name: string) {ColorAndBlur()}build() {Navigation(this.stack) {Stack({alignContent: Alignment.Center}) {BackComponent().width('100%').height('100%')Column() {Stack({alignContent: Alignment.Center}) {Button("switch color").onClick(() => {this.useColor1 = !this.useColor1;})}.width('100%').layoutWeight(1)Stack({alignContent: Alignment.Center}) {Button("switch blur").onClick(() => {this.useBlur1 = !this.useBlur1;})}.width('100%').layoutWeight(1)Stack({alignContent: Alignment.Center}) {Button("push page").onClick(() => {this.stack.pushPath({name: "page"})})}.width('100%').layoutWeight(1)}.width('100%').height('80%')}.width('100%').height('100%')}.width('100%').height('100%').navDestination(this.PageBuilder)// 开发者可以设置标题栏的背景颜色和背景模糊效果.title("NavTitle", {backgroundColor: this.useColor1 ? COLOR1 : COLOR2,backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2,barStyle: BarStyle.STACK})// 开发者可以设置工具栏的背景颜色和背景模糊效果.toolbarConfiguration([{value: "a"},{value: "b"},{value: "c"}], {backgroundColor: this.useColor1 ? COLOR1 : COLOR2,backgroundBlurStyle: this.useBlur1 ? BLUR_STYLE_1 : BLUR_STYLE_2})}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例6

// 该示例主要演示在嵌套Navigation场景下，如何获取父NavPathStack。
@Entry
@Component
struct NavigationExample1 {@State childNavStack: NavPathStack = new NavPathStack();build() {Navigation() {Stack({alignContent: Alignment.Center}) {Navigation(this.childNavStack) {Button('push Path to parent Navigation', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {// 可以获取父NavPathStacklet parentStack = this.childNavStack.getParent();parentStack?.pushPath({ name: "pageOne"})})}.clip(true).backgroundColor(Color.Orange).width('80%').height('80%').title('ChildNavigation')}.width('100%').height('100%')}.backgroundColor(Color.Green).width('100%').height('100%').title('ParentNavigation')}
}
// PageOne.ets@Builderexport function PageOneBuilder(name: string) {NavDestination() {Text("this is " + name)}.title(name)}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/PageOne.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例7

// 该示例主要演示如下两点功能：
// 1. NavPathStack无需声明为状态变量，也可以实现页面栈操作功能；
// 2. NavDestination通过onReady事件能够拿到对应的NavPathInfo和所属的NavPathStack。
class PageParam {constructor(num_: number) {this.num = num_;}num: number = 0;
}@Builder
export function PageOneBuilder(name: string, param: Object) {PageOne()
}@Component
struct PageOne {private stack: NavPathStack | null = null;private name: string = "";private paramNum: number = 0;build() {NavDestination() {Column() {Text("NavPathInfo: name: " + this.name + ", paramNum: " + this.paramNum)Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {if (this.stack) {let p = new PageParam(this.paramNum + 1);this.stack.pushPath({name: "pageOne", param: p});}})Button('pop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.stack?.pop()})}.width('100%').height('100%')}.title('pageOne').onReady((ctx: NavDestinationContext) => {// 在NavDestination中能够拿到传来的NavPathInfo和当前所处的NavPathStacktry {this.name = ctx?.pathInfo?.name;this.paramNum = (ctx?.pathInfo?.param as PageParam)?.num;this.stack = ctx.pathStack;} catch (e) {console.log(`testTag onReady catch exception: ${JSON.stringify(e)}`)}})}
}@Entry
@Component
struct NavigationExample2 {private stack : NavPathStack = new NavPathStack();build() {Navigation(this.stack) {Stack({alignContent: Alignment.Center}) {Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {let p = new PageParam(1);this.stack.pushPath({ name: "pageOne", param: p })})}.width('100%').height('100%')}.width('100%').height('100%').title('Navigation')}
}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/Index.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例8

// 该示例演示NavDestination的生命周期时序。
@Builder
export function PageOneBuilder(name: string, param: Object) {PageOneComponent()
}@Component
struct PageOneComponent {private stack: NavPathStack | null = null;@State eventStr: string = "";build() {NavDestination() {Column() {Text("event: " + this.eventStr)Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {if (this.stack) {this.stack.pushPath({name: "pageOne"});}})Button('pop', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.stack?.pop()})}.width('100%').height('100%')}.title('pageOne').onAppear(() => { this.eventStr += "<onAppear>"; }).onDisAppear(() => { this.eventStr += "<onDisAppear>"; }).onShown(() => { this.eventStr += "<onShown>"; }).onHidden(() => { this.eventStr += "<onHidden>"; }).onWillAppear(() => { this.eventStr += "<onWillAppear>"; }).onWillDisappear(() => { this.eventStr += "<onWillDisappear>"; }).onWillShow(() => { this.eventStr += "<onWillShow>"; }).onWillHide(() => { this.eventStr += "<onWillHide>"; })// onReady会在onAppear之前调用.onReady((ctx: NavDestinationContext) => {try {this.eventStr += "<onReady>";this.stack = ctx.pathStack;} catch (e) {console.log(`testTag onReady catch exception: ${JSON.stringify(e)}`)}})}
}@Entry
@Component
struct NavigationExample3 {private stack : NavPathStack = new NavPathStack();build() {Navigation(this.stack) {Stack({alignContent: Alignment.Center}) {Button('pushPath', { stateEffect: true, type: ButtonType.Capsule }).width('80%').height(40).margin(20).onClick(() => {this.stack.pushPath({ name: "pageOne" })})}.width('100%').height('100%')}.width('100%').height('100%').title('Navigation')}
}
// 工程配置文件module.json5中配置 {"routerMap": "$profile:route_map"}
// route_map.json
{"routerMap": [{"name": "pageOne","pageSourceFile": "src/main/ets/pages/Index.ets","buildFunction": "PageOneBuilder","data": {"description": "this is pageOne"}}]
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例9

// 该示例演示Navigation标题栏STACK布局效果。
@Entry
@Component
struct NavigationExample {private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];private scrollerForScroll: Scroller = new Scroller();@State barStyle: BarStyle = BarStyle.STANDARD;build() {Column() {Navigation() {Column() {Scroll(this.scrollerForScroll) {Column() {Image($r('app.media.image_1'))// 设置与标题栏高度一致，以便观察STACK效果.height(138).width('100%')Button('BarStyle.STANDARD').height('50vp').onClick(() => {this.barStyle = BarStyle.STANDARD;})Button('BarStyle.STACK').height('50vp').margin({ top: 12 }).onClick(() => {this.barStyle = BarStyle.STACK;})ForEach(this.arr, (item: number) => {ListItem() {Text('' + item).width('100%').height(100).fontSize(16).textAlign(TextAlign.Center).borderRadius(10).backgroundColor(Color.Orange).margin({ top: 12 })}}, (item: string) => item)}}}.width('100%').height('100%').backgroundColor(0xDCDCDC)}.title({main: 'NavTitle',sub: 'subtitle'},{backgroundBlurStyle: BlurStyle.COMPONENT_THICK,barStyle: this.barStyle,}).titleMode(NavigationTitleMode.Free).hideTitleBar(false)}.width('100%').height('100%').backgroundColor('#F1F3F5')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例10

// 该示例主要演示如下两点功能
// 1. 如何定义NavPathStack的派生类
// 2. 派生类在Navigation中的基本用法
class DerivedNavPathStack extends NavPathStack {// usr defined property 'id'id: string = "__default__"// new function in derived classsetId(id: string) {this.id = id;}// new function in derived classgetInfo(): string {return "this page used Derived NavPathStack, id: " + this.id}// overwrite function of NavPathStackpushPath(info: NavPathInfo, animated?: boolean): void {console.log('[derive-test] reached DerivedNavPathStack\'s pushPath');super.pushPath(info, animated);}// overwrite and overload function of NavPathStackpop(animated?: boolean | undefined): NavPathInfo | undefinedpop(result: Object, animated?: boolean | undefined): NavPathInfo | undefinedpop(result?: Object, animated?: boolean | undefined): NavPathInfo | undefined {console.log('[derive-test] reached DerivedNavPathStack\'s pop');return super.pop(result, animated);}// other function of base class...
}class param {info: string = "__default_param__";constructor(info: string) { this.info = info }
}@Entry
@Component
struct Index {derivedStack: DerivedNavPathStack = new DerivedNavPathStack();aboutToAppear(): void {this.derivedStack.setId('origin stack');}@BuilderpageMap(name: string) {PageOne()}build() {Navigation(this.derivedStack) {Button('to Page One').margin(20).onClick(() => {this.derivedStack.pushPath({name: 'pageOne',param: new param('push pageOne in homePage')});})}.navDestination(this.pageMap).title('Home Page')}
}@Component
struct PageOne {derivedStack: DerivedNavPathStack = new DerivedNavPathStack();curStringifyParam: string = "NA";build() {NavDestination() {Column() {Text(this.derivedStack.getInfo()).margin(10).fontSize(25).fontWeight(FontWeight.Bold).textAlign(TextAlign.Start)Text('current page param info:').margin(10).fontSize(25).fontWeight(FontWeight.Bold).textAlign(TextAlign.Start)Text(this.curStringifyParam).margin(20).fontSize(20).textAlign(TextAlign.Start)}.backgroundColor(Color.Pink)Button('push Page One').margin(20).onClick(() => {this.derivedStack.pushPath({name: 'pageOne',param: new param('push pageOne in pageOne when stack size: ' + this.derivedStack.size())});})}.onReady((context: NavDestinationContext) => {console.log('[derive-test] reached PageOne\'s onReady');// get derived stack from navdestinationContextthis.derivedStack = context.pathStack as DerivedNavPathStack;console.log('[derive-test] -- got derivedStack: ' + this.derivedStack.id);this.curStringifyParam = JSON.stringify(context.pathInfo.param);console.log('[derive-test] -- got param: ' + this.curStringifyParam);})}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例11

// 该示例主要演示Navigation和NavDestination如何使用Symbol组件@Entry
@Component
struct NavigationExample {@Provide('navPathStack') navPathStack:NavPathStack = new NavPathStack();@State menuItems:Array<NavigationMenuItem> = [{value:'menuItem1',icon:'resources/base/media/ic_public_ok.svg'},{value:'menuItem2',icon:'resources/base/media/ic_public_ok.svg',symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red,Color.Green]).renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR),},{value:'menuItem3',symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')),},]@State toolItems:Array<ToolbarItem>= [{value:'toolItem1',icon:'resources/base/media/ic_public_ok.svg',symbolIcon:new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')),status:ToolbarItemStatus.ACTIVE,activeSymbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red,Color.Green]).renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR),action:()=>{}},{value:'toolItem2',symbolIcon:new SymbolGlyphModifier($r('sys.symbol.ohos_star')),status:ToolbarItemStatus.ACTIVE,activeIcon: 'resources/base/media/ic_public_more.svg',action:()=>{}},{value:'toolItem3',symbolIcon:new SymbolGlyphModifier($r('sys.symbol.ohos_star')),status:ToolbarItemStatus.ACTIVE,activeSymbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_lungs')),action:()=>{}}]@BuildermyRouter(name:string,param?:Object) {if(name === 'NavigationMenu') {NavigationMenu();}}build() {Navigation(this.navPathStack) {Column() {Button('跳转').onClick(()=> {this.navPathStack.pushPathByName('NavigationMenu', null);})}}.backButtonIcon(new SymbolGlyphModifier($r('sys.symbol.ohos_wifi'))).titleMode(NavigationTitleMode.Mini).menus(this.menuItems).toolbarConfiguration(this.toolItems).title('一级页面').navDestination(this.myRouter)}
}@Component
export struct NavigationMenu{@Consume('navPathStack') navPathStack:NavPathStack;@State menuItems:Array<NavigationMenuItem> = [{value:'menuItem1',icon:'resources/base/media/ic_public_ok.svg',action:()=>{}},{value:'menuItem2',symbolIcon: new SymbolGlyphModifier($r('sys.symbol.ohos_folder_badge_plus')).fontColor([Color.Red,Color.Green]).renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR),action:()=>{}},{value:'menuItem3',symbolIcon: new SymbolGlyphModifier($r('sys.symbol.repeat_1')),action:()=>{}},]build() {NavDestination(){Row() {Column(){}.width('100%')}.height('100%')}.hideTitleBar(false).title('NavDestination title').backgroundColor($r('sys.color.ohos_id_color_titlebar_sub_bg')).backButtonIcon(new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Blue])).menus(this.menuItems)}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例12

// 该示例主要演示Navigation和NavDestination如何自定义设置标题栏边距。
import { LengthMetrics } from '@kit.ArkUI';@Entry
@Component
struct NavigationExample {@Provide('navPathStack') navPathStack: NavPathStack = new NavPathStack();// 初始化标题栏起始端内间距@State paddingStart: LengthMetrics = LengthMetrics.vp(0);// 初始化标题栏结束端内间距@State paddingEnd: LengthMetrics = LengthMetrics.vp(0);@State menuItems: Array<NavigationMenuItem> = [{value: 'menuItem1',icon: 'resources/base/media/ic_public_ok.svg', // 图标资源路径action: () => {}}]@BuildermyRouter(name: string, param?: Object) {if (name === 'NavDestinationExample') {NavDestinationExample();}}build() {Navigation(this.navPathStack) {Column() {// 标题栏内间距切换Button('切换标题栏内间距为16vp').onClick(() => {this.paddingStart = LengthMetrics.vp(16);this.paddingEnd = LengthMetrics.vp(16);}).margin({ top: 5 })Button('切换标题栏内间距为24vp').onClick(() => {this.paddingStart = LengthMetrics.vp(24);this.paddingEnd = LengthMetrics.vp(24);}).margin({ top: 5 })Button('跳转').onClick(() => {this.navPathStack.pushPathByName('NavDestinationExample', null);}).margin({ top: 5 })}}.titleMode(NavigationTitleMode.Mini).title('一级页面', {paddingStart: this.paddingStart,paddingEnd: this.paddingEnd,}).menus(this.menuItems).navDestination(this.myRouter)}
}@Component
export struct NavDestinationExample {@Consume('navPathStack') navPathStack: NavPathStack;@State menuItems: Array<NavigationMenuItem> = [{value: 'menuItem1',icon: 'resources/base/media/ic_public_ok.svg', // 图标资源路径action: () => {}}]@State paddingStart: LengthMetrics = LengthMetrics.vp(0);@State paddingEnd: LengthMetrics = LengthMetrics.vp(0);build() {NavDestination() {Row() {Column() {// 标题栏内间距切换Button('切换标题栏内间距为32vp').onClick(() => {this.paddingStart = LengthMetrics.vp(32);this.paddingEnd = LengthMetrics.vp(32);}).margin({ top: 5 })Button('切换标题栏内间距为20vp').onClick(() => {this.paddingStart = LengthMetrics.vp(20);this.paddingEnd = LengthMetrics.vp(20);}).margin({ top: 5 })}.width('100%')}.height('100%')}.hideTitleBar(false).title('NavDestination title', {paddingStart: this.paddingStart,paddingEnd: this.paddingEnd,}).menus(this.menuItems)}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

NavRouter

导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。

必须包含两个子组件，其中第二个子组件必须为NavDestination。

参数：

参数名	参数类型	必填	参数描述
value	RouteInfo	否	路由信息

属性

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

mode

mode(mode: NavRouteMode)

设置指定点击NavRouter跳转到NavDestination页面时，使用的路由模式。

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

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

参数：

参数名	类型	必填	描述
mode	NavRouteMode	是	指定点击NavRouter跳转到NavDestination页面时，使用的路由模式。默认值：NavRouteMode.PUSH_WITH_RECREATE

RouteInfo10+对象说明

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

名称	参数类型	必填	描述
name	string	是	点击NavRouter跳转到的NavDestination页面的名称。
param	unknown	否	点击NavRouter跳转到NavDestination页面时，传递的参数。

NavRouteMode枚举类型说明

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

名称	描述
PUSH_WITH_RECREATE	跳转到新的NavDestination页面时，替换当前显示的NavDestination页面，页面销毁，但该页面信息仍保留在路由栈中。
PUSH	跳转到新的NavDestination页面时，覆盖当前显示的NavDestination页面，该页面不销毁，且页面信息保留在路由栈中。
REPLACE	跳转到新的NavDestination页面时，替换当前显示的NavDestination页面，页面销毁，且该页面信息从路由栈中清除。

事件

onStateChange

onStateChange(callback: (isActivated: boolean) => void)

组件激活状态切换时触发该回调。开发者点击激活NavRouter，加载对应的NavDestination子组件时，回调onStateChange(true)。NavRouter对应的NavDestination子组件不再显示时，回调onStateChange(false)。

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

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

参数：

参数名	类型	必填	描述
isActivated	boolean	是	isActivated为true时表示激活，为false时表示未激活。

示例

// xxx.ets
@Entry
@Component
struct NavRouterExample {@State isActiveWLAN: boolean = false@State isActiveBluetooth: boolean = falsebuild() {Navigation() {NavRouter() {Row() {Row().width(30).height(30).borderRadius(30).margin({ left: 3, right: 10 }).backgroundColor(Color.Pink)Text(`WLAN`).fontSize(22).fontWeight(500).textAlign(TextAlign.Center)}.width('90%').height(60)NavDestination() {Flex({ direction: FlexDirection.Row }) {Text('未找到可用WLAN').fontSize(30).padding({ left: 15 })}}.title("WLAN")}.margin({ top: 10, bottom: 10 }).backgroundColor(this.isActiveWLAN ? '#ccc' : '#fff').borderRadius(20).mode(NavRouteMode.PUSH_WITH_RECREATE).onStateChange((isActivated: boolean) => {this.isActiveWLAN = isActivated})NavRouter() {Row() {Row().width(30).height(30).borderRadius(30).margin({ left: 3, right: 10 }).backgroundColor(Color.Pink)Text(`蓝牙`).fontSize(22).fontWeight(500).textAlign(TextAlign.Center)}.width('90%').height(60)NavDestination() {Flex({ direction: FlexDirection.Row }) {Text('未找到可用蓝牙').fontSize(30).padding({ left: 15 })}}.title("蓝牙")}.margin({ top: 10, bottom: 10 }).backgroundColor(this.isActiveBluetooth ? '#ccc' : '#fff').borderRadius(20).mode(NavRouteMode.REPLACE).onStateChange((isActivated: boolean) => {this.isActiveBluetooth = isActivated})}.height('100%').width('100%').title('设置').backgroundColor("#F2F3F5").titleMode(NavigationTitleMode.Free).mode(NavigationMode.Auto)}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

NavDestination

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

title

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

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

参数：

参数名	类型	必填	说明
value	string \| CustomBuilder \| NavigationCommonTitle \| NavigationCustomTitle	是	页面标题。
options12+	NavigationTitleOptions	否	标题栏选项。

hideTitleBar

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

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

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

参数：

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

mode 11+

mode(value: NavDestinationMode)

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

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

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

参数：

参数名	类型	必填	说明
value	NavDestinationMode	是	NavDestination类型。默认值: NavDestinationMode.STANDARD

backButtonIcon11+

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

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

设置标题栏返回键图标。

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

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

参数：

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

menus12+

menus(value: Array | CustomBuilder)

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

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

参数：

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

ignoreLayoutSafeArea12+

ignoreLayoutSafeArea(types?: Array, edges?: Array)

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

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

参数：

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

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

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

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

systemBarStyle12+

systemBarStyle(style: Optional)

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

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

参数：

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

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

NavDestinationMode枚举说明 11+

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

名称	描述
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)

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

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

onWillShow12+

onWillShow(callback: Callback)

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

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

onWillHide12+

onWillHide(callback: Callback)

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

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

onWillDisappear12+

onWillDisappear(callback: Callback)

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

系统能力： 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

NavDestinationContext11+类型说明

名称	类型	必填	描述
pathInfo	NavPathInfo	是	跳转NavDestination时指定的参数。元服务API：从API version 11开始，该接口支持在元服务中使用。
pathStack	NavPathStack	是	当前NavDestination所处的页面栈。元服务API：从API version 11开始，该接口支持在元服务中使用。
navDestinationId12+	string	否	当前NavDestination的唯一ID，由系统自动生成，和组件通用属性id无关。

getConfigInRouteMap12+

getConfigInRouteMap(): RouteMapConfig |undefined

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

返回值

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

RouteMapConfig12+类型说明

名称	类型	描述
name	string	页面名称。
pageSourceFile	string	页面在当前包中的路径。
data	object	页面自定义字段信息。

NodeContainer

基础组件，不支持尾随添加子节点。组件接受一个NodeController的实例接口。需要NodeController组合使用。

参数：

参数名	参数类型	必填	参数描述
controller	NodeController	是	NodeController用于控制NodeContainer中的节点的上树和下树，反映NodeContainer容器的生命周期。

示例

import { NodeController, BuilderNode, FrameNode, UIContext } from '@kit.ArkUI';declare class Params {text: string
}@Builder
function buttonBuilder(params: Params) {Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceEvenly }) {Text(params.text).fontSize(12)Button(`This is a Button`, { type: ButtonType.Normal, stateEffect: true }).fontSize(12).borderRadius(8).backgroundColor(0x317aff)}.height(100).width(200)
}class MyNodeController extends NodeController {private rootNode: BuilderNode<[Params]> | null = null;private wrapBuilder: WrappedBuilder<[Params]> = wrapBuilder(buttonBuilder);makeNode(uiContext: UIContext): FrameNode | null {if (this.rootNode === null) {this.rootNode = new BuilderNode(uiContext);this.rootNode.build(this.wrapBuilder, { text: "This is a Text" })}return this.rootNode.getFrameNode();}
}@Entry
@Component
struct Index {private baseNode: MyNodeController = new MyNodeController()build() {Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceEvenly }) {Text("This is a NodeContainer contains a text and a button ").fontSize(9).fontColor(0xCCCCCC)NodeContainer(this.baseNode).borderWidth(1).onClick(() => {console.log("click event");})}.padding({ left: 35, right: 35, top: 35 }).height(200).width(300)}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

PatternLock

图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。

参数：

参数名	参数类型	必填	描述
controller	PatternLockController	否	设置PatternLock组件控制器，可用于控制组件状态重置。

属性

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

sideLength

sideLength(value: Length)

设置组件的宽度和高度（宽高相同）。设置为0或负数时组件不显示。

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

参数：

参数名	类型	必填	说明
value	Length	是	组件的宽度和高度。默认值：288vp

circleRadius

circleRadius(value: Length)

设置宫格中圆点的半径。设置为0或负数时取默认值。

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

参数：

参数名	类型	必填	说明
value	Length	是	宫格中圆点的半径。默认值：6vp

regularColor

regularColor(value: ResourceColor)

设置宫格圆点在“未选中”状态的填充颜色。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	宫格圆点在“未选中”状态的填充颜色。默认值：‘#ff182431’

selectedColor

selectedColor(value: ResourceColor)

设置宫格圆点在“选中“状态的填充颜色。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	宫格圆点在“选中”状态的填充颜色。默认值：‘#ff182431’

activeColor

activeColor(value: ResourceColor)

设置宫格圆点在“激活”状态的填充颜色，“激活”状态为手指经过圆点但还未选中的状态。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	宫格圆点在“激活”状态的填充颜色。默认值：‘#ff182431’

pathColor

pathColor(value: ResourceColor)

设置连线的颜色。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	连线的颜色。默认值：‘#33182431’

pathStrokeWidth

pathStrokeWidth(value: number | string)

设置连线的宽度。设置为0或负数时连线不显示。

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

参数：

参数名	类型	必填	说明
value	number \| string	是	连线的宽度。默认值：12vp

autoReset

autoReset(value: boolean)

设置在完成密码输入后再次在组件区域按下时是否重置组件状态。

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

参数：

参数名	类型	必填	说明
value	boolean	是	在完成密码输入后再次在组件区域按下时是否重置组件状态。为true时，完成密码输入后再次在组件区域按下时会重置组件状态（即清除之前输入的密码）；为false时，不会重置组件状态。默认值：true

activateCircleStyle12+

activateCircleStyle(options: Optional)

设置宫格圆点在“激活”状态的背景圆环样式。

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

参数：

参数名	类型	必填	说明
options	CircleStyleOptions	是	宫格圆点在“激活”状态的背景圆环样式。

CircleStyleOptions12+对象说明

名称	参数类型	必填	描述
color	ResourceColor	否	背景圆环颜色。默认值：与pathColor值相同
radius	LengthMetrics	否	背景圆环的半径。默认值：circleRadius的11/6
enableWaveEffect	boolean	否	波浪效果开关。默认值：true

事件

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

onPatternComplete

onPatternComplete(callback: (input: Array) => void)

密码输入结束时触发该回调。

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

参数：

参数名	类型	必填	说明
input	Array	是	与选中宫格圆点顺序一致的数字数组，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。

onDotConnect11+

onDotConnect(callback: CallBack)

密码输入选中宫格圆点时触发该回调。

回调参数为选中宫格圆点顺序的数字，数字为选中宫格圆点的索引值（第一行圆点从左往右依次为0、1、2，第二行圆点依次为3、4、5，第三行圆点依次为6、7、8）。

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

PatternLockController

PatternLock组件的控制器，可以通过它进行组件状态重置。

导入对象

let patternLockController: PatternLockController = new PatternLockController()

reset

reset(): void

重置组件状态。

setChallengeResult11+

setChallengeResult(result: PatternLockChallengeResult): void

用于设置图案密码正确或错误状态。

参数	参数类型	必填	参数描述
result	PatternLockChallengeResult	是	图案密码状态。

PatternLockChallengeResult11+枚举说明

名称	描述
CORRECT	图案密码正确。
WRONG	图案密码错误。

示例

// xxx.ets
import { LengthUnit } from '@kit.ArkUI'@Entry
@Component
struct PatternLockExample {@State passwords: Number[] = []@State message: string = 'please input password!'private patternLockController: PatternLockController = new PatternLockController()build() {Column() {Text(this.message).textAlign(TextAlign.Center).margin(20).fontSize(20)PatternLock(this.patternLockController).sideLength(200).circleRadius(9).pathStrokeWidth(18).activeColor('#B0C4DE').selectedColor('#228B22').pathColor('#90EE90').backgroundColor('#F5F5F5').autoReset(true).activateCircleStyle({color: '#90EE90',radius: { value: 16, unit: LengthUnit.VP },enableWaveEffect: true}).onDotConnect((index: number) => {console.log("onDotConnect index: " + index)}).onPatternComplete((input: Array<number>) => {// 输入的密码长度小于5时，提示重新输入if (input === null || input === undefined || input.length < 5) {this.message = 'The password length needs to be greater than 5, please enter again.'return}// 判断密码长度是否大于0if (this.passwords.length > 0) {// 判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入if (this.passwords.toString() === input.toString()) {this.passwords = inputthis.message = 'Set password successfully: ' + this.passwords.toString()this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)} else {this.message = 'Inconsistent passwords, please enter again.'this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)}} else {// 提示第二次输入密码this.passwords = inputthis.message = "Please enter again."}})Button('Reset PatternLock').margin(30).onClick(() => {// 重置密码锁this.patternLockController.reset()this.passwords = []this.message = 'Please input password'})}.width('100%').height('100%')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Progress

进度条组件，用于显示内容加载或操作处理等进度。

参数：

参数名	参数类型	必填	参数描述
options	ProgressOptions	是	进度条组件参数。

ProgressOptions对象说明

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

参数名	参数类型	必填	参数描述
value	number	是	指定当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。默认值：0卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。
total	number	否	指定进度总长。设置小于等于0的数值时置为100。默认值：100卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。
type8+	ProgressType	否	指定进度条类型。默认值：ProgressType.Linear卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。
style(deprecated)	ProgressStyle	否	指定进度条样式。该参数从API version8开始废弃，建议使用type替代。默认值：ProgressStyle.Linear

ProgressType8+枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

名称	描述
Linear	线性样式。从API version9开始，高度大于宽度的时候自适应垂直显示。
Ring	环形无刻度样式，环形圆环逐渐显示至完全填充效果。
Eclipse	圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。
ScaleRing	环形有刻度样式，显示类似时钟刻度形式的进度展示效果。从API version9开始，刻度外圈出现重叠的时候自动转换为环形无刻度进度条。
Capsule	胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同；中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。

ProgressStyle枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

名称	描述
Linear	线性样式。
Ring8+	环形无刻度样式，环形圆环逐渐显示至完全填充效果。
Eclipse	圆形样式，显示类似月圆月缺的进度展示效果，从月牙逐渐变化至满月。
ScaleRing8+	环形有刻度样式，显示类似时钟刻度形式的进度展示效果。
Capsule8+	胶囊样式，头尾两端圆弧处的进度展示效果与Eclipse相同；中段处的进度展示效果与Linear相同。高度大于宽度的时候自适应垂直显示。

属性

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

value

value(value: number)

设置当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。非法数值不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	number	是	当前进度值。默认值：0

color

color(value: ResourceColor | LinearGradient)

设置进度条前景色。

从API version 10开始支持利用LinearGradient设置Ring样式的渐变色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用，暂不支持LinearGradient。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor \| LinearGradient10+	是	进度条前景色。默认值：- Capsule：API version 9及以下：‘#ff007dff’API version 10：’#33006cde’API version 11及以上：‘#33007dff’- Ring：API version 9及以下：‘#ff007dff’API version 10及以上：起始端：’#ff86c1ff’，结束端：‘#ff254ff7’- 其他样式：‘#ff007dff’

backgroundColor

backgroundColor(value: ResourceColor)

设置进度条底色。当设置通用属性backgroundColor时，生效的是进度条的底色，而不是整个Progress组件的背景色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	进度条底色。默认值：- Capsule：API version 9及以下：‘#19182431’API version 10及以上：’#33ffffff’- Ring：API version 9及以下：‘#19182431’API version 10：’#08182431’API version 11及以上：‘#0c182431’- 其他样式：‘#19182431’

style8+

设置组件的样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	ProgressStyleOptions8+ \| CapsuleStyleOptions10+ \|RingStyleOptions10+ \| LinearStyleOptions10+ \|ScaleRingStyleOptions10+ \| EclipseStyleOptions10+	是	组件的样式。- CapsuleStyleOptions：设置Capsule的样式。- RingStyleOptions：设置Ring的样式。- LinearStyleOptions：设置Linear的样式。- ScaleRingStyleOptions：设置ScaleRing的样式。- EclipseStyleOptions：设置Eclipse的样式。- ProgressStyleOptions：仅可设置各类型进度条的基本样式。ProgressStyleOptions，暂不支持其它的参数类型。

contentModifier12+

contentModifier(modifier:ContentModifier)

定制progress内容区的方法。

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

参数：

参数名	类型	必填	说明
modifier	ContentModifier	是	在progress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

privacySensitive12+

privacySensitive(isPrivacySensitiveMode: Optional)

设置隐私敏感。

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

参数：

参数名	类型	必填	说明
isPrivacySensitiveMode	[Optional]	是	设置隐私敏感，隐私模式下进度清零，文字将被遮罩。说明：设置null则不敏感。需要卡片框架支持。

ProgressConfiguration12+

名称	参数类型	描述
value	number	当前进度值。
total	number	进度总长。

ProgressStyleOptions8+

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

名称	参数类型	必填	描述
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。默认值：4.0vp
scaleCount	number	否	设置环形进度条总刻度数。默认值：120
scaleWidth	Length	否	设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。默认值：2.0vp
enableSmoothEffect10+	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

CapsuleStyleOptions10+

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

名称	参数类型	必填	描述
borderColor	ResourceColor	否	内描边颜色。默认值：API version 10：‘#33006cde’API version 11及以上：’#33007dff’
borderWidth	Length	否	内描边宽度（不支持百分比设置）。默认值：1vp
content	string	否	文本内容，应用可自定义。
font	Font	否	文本样式。默认值：- 文本大小（不支持百分比设置）：12fp其他文本参数跟随text组件的主题值。
fontColor	ResourceColor	否	文本颜色。默认值：‘#ff182431’
enableScanEffect	boolean	否	扫光效果的开关。默认值：false
showDefaultPercentage	boolean	否	显示百分比文本的开关，开启后会在进度条上显示当前进度的百分比。设置了content属性时该属性不生效。默认值：false
enableSmoothEffect	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

RingStyleOptions10+

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

名称	参数类型	必填	描述
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置），宽度大于等于半径时，默认修改宽度至半径值的二分之一。默认值：4.0vp
shadow	boolean	否	进度条阴影开关。默认值：false
status	ProgressStatus10+	否	进度条状态，当设置为LOADING时会开启检查更新动效，此时设置进度值不生效。当从LOADING设置为PROGRESSING，检查更新动效会执行到终点再停止。默认值： ProgressStatus.PROGRESSING
enableScanEffect	boolean	否	进度条扫光效果的开关。默认值： false
enableSmoothEffect	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

LinearStyleOptions10+

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

名称	参数类型	必填	描述
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。默认值：4.0vp
strokeRadius	PX \| VP \| LPX \| Resource	否	设置线性进度条圆角半径。取值范围[0, strokeWidth / 2]。默认值：strokeWidth / 2。
enableScanEffect	boolean	否	进度条扫光效果的开关。默认值： false
enableSmoothEffect	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

ScaleRingStyleOptions10+

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

名称	参数类型	必填	描述
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。默认值：4.0vp
scaleCount	number	否	设置环形进度条总刻度数。默认值：120
scaleWidth	Length	否	设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。默认值：2.0vp
enableSmoothEffect	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

EclipseStyleOptions10+

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

名称	参数类型	必填	描述
enableSmoothEffect	boolean	否	进度平滑动效的开关。开启平滑动效后设置进度，进度会从当前值渐变至设定值，否则进度从当前值突变至设定值。默认值：true

ProgressStatus10+枚举说明

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

名称	描述
LOADING	加载中。
PROGRESSING	进度更新中。

示例1

各进度条基础属性效果。

// xxx.ets
@Entry
@Component
struct ProgressExample {build() {Column({ space: 15 }) {Text('Linear Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')Progress({ value: 10, type: ProgressType.Linear }).width(200)Progress({ value: 20, total: 150, type: ProgressType.Linear }).color(Color.Grey).value(50).width(200)Text('Eclipse Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')Row({ space: 40 }) {Progress({ value: 10, type: ProgressType.Eclipse }).width(100)Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).value(50).width(100)}Text('ScaleRing Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')Row({ space: 40 }) {Progress({ value: 10, type: ProgressType.ScaleRing }).width(100)Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).color(Color.Grey).value(50).width(100).style({ strokeWidth: 15, scaleCount: 15, scaleWidth: 5 })}// scaleCount和scaleWidth效果对比Row({ space: 40 }) {Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).color(Color.Grey).value(50).width(100).style({ strokeWidth: 20, scaleCount: 20, scaleWidth: 5 })Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).color(Color.Grey).value(50).width(100).style({ strokeWidth: 20, scaleCount: 30, scaleWidth: 3 })}Text('Ring Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')Row({ space: 40 }) {Progress({ value: 10, type: ProgressType.Ring }).width(100)Progress({ value: 20, total: 150, type: ProgressType.Ring }).color(Color.Grey).value(50).width(100).style({ strokeWidth: 20 })}Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%')Row({ space: 40 }) {Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50)Progress({ value: 20, total: 150, type: ProgressType.Capsule }).color(Color.Grey).value(50).width(100).height(50)}}.width('100%').margin({ top: 30 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2

环形进度条视觉属性。

// xxx.ets
@Entry
@Component
struct ProgressExample {private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 },{ color: Color.Orange, offset: 1.0 }])build() {Column({ space: 15 }) {Text('Gradient Color').fontSize(9).fontColor(0xCCCCCC).width('90%')Progress({ value: 70, total: 100, type: ProgressType.Ring }).width(100).style({ strokeWidth: 20 }).color(this.gradientColor)Text('Shadow').fontSize(9).fontColor(0xCCCCCC).width('90%')Progress({ value: 70, total: 100, type: ProgressType.Ring }).width(120).color(Color.Orange).style({ strokeWidth: 20, shadow: true })}.width('100%').padding({ top: 5 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例3

环形进度条动效。

// xxx.ets
@Entry
@Component
struct ProgressExample {private gradientColor: LinearGradient = new LinearGradient([{ color: Color.Yellow, offset: 0.5 },{ color: Color.Orange, offset: 1.0 }])build() {Column({ space: 15 }) {Text('Loading Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')Progress({ value: 0, total: 100, type: ProgressType.Ring }).width(100).color(Color.Blue).style({ strokeWidth: 20, status: ProgressStatus.LOADING })Text('Scan Effect').fontSize(9).fontColor(0xCCCCCC).width('90%')Progress({ value: 30, total: 100, type: ProgressType.Ring }).width(100).color(Color.Orange).style({ strokeWidth: 20, enableScanEffect: true })}.width('100%').padding({ top: 5 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例4

胶囊形进度条视觉属性。

// xxx.ets
@Entry
@Component
struct ProgressExample {build() {Column({ space: 15 }) {Row({ space: 40 }) {Progress({ value: 100, total: 100,type: ProgressType.Capsule }).width(100).height(50).style({borderColor: Color.Blue, borderWidth: 1, content: 'Installing...',font: {size: 13, style: FontStyle.Normal}, fontColor: Color.Gray,enableScanEffect: false, showDefaultPercentage: false})}}.width('100%').padding({ top: 5 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例5

进度平滑动效。

// xxx.ets
@Entry
@Component
struct Index {@State value: number = 0build() {Column({space: 10}) {Text('enableSmoothEffect: true').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5).margin({top: 20})Progress({value: this.value, total: 100, type:ProgressType.Linear}).style({strokeWidth: 10, enableSmoothEffect: true})Text('enableSmoothEffect: false').fontSize(9).fontColor(0xCCCCCC).width('90%').margin(5)Progress({value: this.value, total: 100, type:ProgressType.Linear}).style({strokeWidth: 10, enableSmoothEffect: false})Button('value +10').onClick(() => {this.value += 10}).width(75).height(15).fontSize(9)}.width('50%').height('100%').margin({left:20})}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例6

该示例实现了自定义进度条的功能，自定义实现星形，其中总进度为3，且当前值可通过按钮进行增减，达到的进度被填充自定义颜色。

// xxx.ets
class MyProgressModifier implements ContentModifier<ProgressConfiguration> {color: Color = Color.Whiteconstructor(color:Color) {this.color = color}applyContent() : WrappedBuilder<[ProgressConfiguration]>{return wrapBuilder(myProgress)}
}@Builder function myProgress(config: ProgressConfiguration ) {Column({space:30}) {Text("当前进度：" + config.value + "/" + config.total).fontSize(20)Row() {Flex({ justifyContent: FlexAlign.SpaceBetween }) {Path().width('30%').height('30%').commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z').fill(config.enabled && config.value >=1 ? (config.contentModifier as MyProgressModifier).color : Color.White).stroke(Color.Black).strokeWidth(3)Path().width('30%').height('30%').commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z').fill(config.enabled && config.value >=2 ? (config.contentModifier as MyProgressModifier).color : Color.White).stroke(Color.Black).strokeWidth(3)Path().width('30%').height('30%').commands('M108 0 L141 70 L218 78.3 L162 131 L175 205 L108 170 L41.2 205 L55 131 L1 78 L75 68 L108 0 Z').fill(config.enabled && config.value >=3 ? (config.contentModifier as MyProgressModifier).color : Color.White).stroke(Color.Black).strokeWidth(3)}.width('100%')}}.margin({bottom:100})
}@Entry
@Component
struct Index {@State currentValue: number = 0modifier = new MyProgressModifier(Color.Red)@State myModifier:(MyProgressModifier | undefined)  = this.modifierbuild() {Column() {Progress({ value: this.currentValue, total: 3, type: ProgressType.Ring}).contentModifier(this.modifier)Button('Progress++').onClick(()=>{if (this.currentValue < 3) {this.currentValue += 1}}).width('30%')Button('addProgress--').onClick(()=>{if (this.currentValue > 0) {this.currentValue -= 1}}).width('30%')}.width('100%').height('100%')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例7

该示例展示了如何配置隐私隐藏，效果展示需要卡片框架支持

@Entry
@Component
struct ProgressExample {build() {Scroll() {Column({ space: 15 }) {Row() {Progress({ value: 50, total: 100, type: ProgressType.Capsule }).width(100).height(50).style({borderColor: Color.Blue,borderWidth: 1,content: 'Installing...',font: { size: 13, style: FontStyle.Normal },fontColor: Color.Gray,enableScanEffect: false,showDefaultPercentage: true}).privacySensitive(true)}}}}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

QRCode

用于显示单个二维码的组件。

参数：

参数名	参数类型	必填	参数描述
value	string	是	二维码内容字符串。最大支持256个字符，若超出，则截取前256个字符。说明：该字符串内容确保有效，不支持null、undefined以及空内容。

属性

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

color

color(value: ResourceColor)

设置二维码颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	二维码颜色。默认值：‘#ff182431’

backgroundColor

backgroundColor(value: ResourceColor)

设置二维码背景颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	二维码背景颜色。默认值：Color.White从API version 11开始，默认值改为’#ffffffff’。

contentOpacity11+

contentOpacity(value: number | Resource)

设置二维码内容颜色的不透明度。不透明度最小值为0，最大值为1。

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

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

参数：

参数名	类型	必填	说明
value	number \| Resource	是	二维码内容颜色的不透明度。默认值：1

事件

通用事件支持点击事件、触摸事件、挂载卸载事件。

示例

// xxx.ets
@Entry
@Component
struct QRCodeExample {private value: string = 'hello world'build() {Column({ space: 5 }) {Text('normal').fontSize(9).width('90%').fontColor(0xCCCCCC).fontSize(30)QRCode(this.value).width(140).height(140)// 设置二维码颜色Text('color').fontSize(9).width('90%').fontColor(0xCCCCCC).fontSize(30)QRCode(this.value).color(0xF7CE00).width(140).height(140)// 设置二维码背景色Text('backgroundColor').fontSize(9).width('90%').fontColor(0xCCCCCC).fontSize(30)QRCode(this.value).width(140).height(140).backgroundColor(Color.Orange)// 设置二维码不透明度Text('contentOpacity').fontSize(9).width('90%').fontColor(0xCCCCCC).fontSize(30)QRCode(this.value).width(140).height(140).color(Color.Black).contentOpacity(0.1)}.width('100%').margin({ top: 5 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Radio

单选框，提供相应的用户交互选择项。

参数：

参数名	类型	必填	描述
options	RadioOptions	是	配置单选框的参数。

RadioOptions对象说明

名称	类型	必填	说明
value	string	是	当前单选框的值。元服务API：从API version 11开始，该接口支持在元服务中使用。
group	string	是	当前单选框的所属群组名称，相同group的Radio只能有一个被选中。元服务API：从API version 11开始，该接口支持在元服务中使用。
indicatorType12+	RadioIndicatorType	否	配置单选框的选中样式。未设置时按照RadioIndicatorType.TICK进行显示。
indicatorBuilder12+	CustomBuilder	否	配置单选框的选中样式为自定义组件。自定义组件与Radio组件为中心点对齐显示。indicatorBuilder设置为undefined时，按照RadioIndicatorType.TICK进行显示。

RadioIndicatorType12+枚举说明

名称	描述
TICK	选中样式为系统默认TICK图标。
DOT	选中样式为系统默认DOT图标。
CUSTOM	选中样式为indicatorBuilder中的内容。

属性

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

checked

checked(value: boolean)

设置单选框的选中状态。

从API version 10开始，该属性支持$$双向绑定变量。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	单选框的选中状态。默认值：false

radioStyle10+

radioStyle(value?: RadioStyle)

设置单选框选中状态和非选中状态的样式。

从API version 10开始，该接口支持在ArkTS组件中使用。

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

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

参数：

参数名	类型	必填	说明
value	RadioStyle	否	单选框选中状态和非选中状态的样式。

contentModifier12+

contentModifier(modifier: ContentModifier)

定制Radio内容区的方法。

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

参数：

参数名	类型	必填	说明
modifier	ContentModifier	是	在Radio组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

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

onChange

onChange(callback: (isChecked: boolean) => void)

单选框选中状态改变时触发回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
isChecked	boolean	是	单选框的状态。为true时，表示从未选中变为选中。为false时，表示从选中变为未选中。

RadioStyle10+对象说明

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

名称	类型	必填	默认值	描述
checkedBackgroundColor	ResourceColor	否	#007DFF	开启状态底板颜色。
uncheckedBorderColor	ResourceColor	否	#182431	关闭状态描边颜色。
indicatorColor	ResourceColor	否	#FFFFFF	开启状态内部圆饼颜色。从API version 12开始，indicatorType设置为RadioIndicatorType.TICK和RadioIndicatorType.DOT时，支持修改内部颜色。indicatorType设置为RadioIndicatorType.CUSTOM时，不支持修改内部颜色。

RadioConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	默认值	说明
value	string	-	当前单选框的值。
checked	boolean	false	设置单选框的选中状态。
triggerChange	Callback	-	触发单选框选中状态变化。

示例1

设置开启状态底板颜色。

// xxx.ets
@Entry
@Component
struct RadioExample {build() {Flex({ direction: FlexDirection.Row, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {Column() {Text('Radio1')Radio({ value: 'Radio1', group: 'radioGroup' }).checked(true).radioStyle({checkedBackgroundColor: Color.Pink}).height(50).width(50).onChange((isChecked: boolean) => {console.log('Radio1 status is ' + isChecked)})}Column() {Text('Radio2')Radio({ value: 'Radio2', group: 'radioGroup' }).checked(false).radioStyle({checkedBackgroundColor: Color.Pink}).height(50).width(50).onChange((isChecked: boolean) => {console.log('Radio2 status is ' + isChecked)})}Column() {Text('Radio3')Radio({ value: 'Radio3', group: 'radioGroup' }).checked(false).radioStyle({checkedBackgroundColor: Color.Pink}).height(50).width(50).onChange((isChecked: boolean) => {console.log('Radio3 status is ' + isChecked)})}}.padding({ top: 30 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2

设置选中样式为图片。

// xxx.ets
@Entry
@Component
struct RadioExample {@Builder indicatorBuilder() {Image($r("app.media.star"))}build() {Flex({ direction: FlexDirection.Row, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {Column() {Text('Radio1')Radio({ value: 'Radio1', group: 'radioGroup',indicatorType:RadioIndicatorType.TICK}).checked(true).height(50).width(80).onChange((isChecked: boolean) => {console.log('Radio1 status is ' + isChecked)})}Column() {Text('Radio2')Radio({ value: 'Radio2', group: 'radioGroup',indicatorType:RadioIndicatorType.DOT}).checked(false).height(50).width(80).onChange((isChecked: boolean) => {console.log('Radio2 status is ' + isChecked)})}Column() {Text('Radio3')Radio({ value: 'Radio3', group: 'radioGroup',indicatorType:RadioIndicatorType.CUSTOM,indicatorBuilder:()=>{this.indicatorBuilder()}}).checked(false).height(50).width(80).onChange((isChecked: boolean) => {console.log('Radio3 status is ' + isChecked)})}}.padding({ top: 30 })}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例3

设置自定义单选样式

class MyRadioStyle implements ContentModifier<RadioConfiguration> {type: number = 0selectedColor:Color = Color.Blackconstructor(numberType: number, colorType:Color) {this.type = numberTypethis.selectedColor = colorType}applyContent() : WrappedBuilder<[RadioConfiguration]>{return wrapBuilder(buildRadio)}
}@Builder function buildRadio(config: RadioConfiguration) {Row({ space:30 }) {Circle({ width: 50, height: 50 }).stroke(Color.Black).fill(config.checked ? (config.contentModifier as MyRadioStyle).selectedColor : Color.White)Button(config.checked ? "off" : "on").width(100).type(config.checked ? (config.contentModifier as MyRadioStyle).type : ButtonType.Normal).backgroundColor(0xAABBCC).onClick(()=>{if (config.checked) {config.triggerChange(false)} else {config.triggerChange(true)}})}
}@Entry
@Component
struct refreshExample {build() {Column({ space: 50 }) {Row() {Radio({ value: 'Radio1', group: 'radioGroup' }).contentModifier(new MyRadioStyle(1, Color.Red)).checked(false).width(300).height(100)}Row() {Radio({ value: 'Radio2', group: 'radioGroup' }).checked(true).width(300).height(60).contentModifier(new MyRadioStyle(2, Color.Red))}}}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Rating

提供在给定范围内选择评分的组件。

参数：

参数名	参数类型	必填	参数描述
rating	number	是	设置并接收评分值。默认值：0取值范围： [0, stars]小于0取0，大于stars取最大值stars。从API version 10开始，该参数支持$$双向绑定变量。
indicator	boolean	否	设置评分组件作为指示器使用，不可改变评分。默认值：false, 可进行评分说明：indicator=true时，默认组件高度height=12.0vp，组件width=height * stars。indicator=false时，默认组件高度height=28.0vp，组件width=height * stars。

属性

stars

stars(value: number)

设置评分总数。设置为小于等于0的值时，按默认值显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	number	是	设置评分总数。默认值：5

stepSize

stepSize(value: number)

设置操作评级的步长。设置为小于0.1的值时，按默认值显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	number	是	操作评级的步长。默认值：0.5取值范围：[0.1, stars]

starStyle

starStyle(value: { backgroundUri: string, foregroundUri: string, secondaryUri?: string })

设置评分的样式。该属性所支持的图片类型能力参考Image组件。

支持加载本地图片和网络图片，暂不支持PixelMap类型和Resource资源。

默认图片加载方式为异步，暂不支持同步加载。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	{backgroundUri: string,foregroundUri: string,secondaryUri?: string}	是	backgroundUri：未选中的星级的图片链接，可由用户自定义或使用系统默认图片。foregroundUri：选中的星级的图片路径，可由用户自定义或使用系统默认图片。secondaryUri：部分选中的星级的图片路径，可由用户自定义或使用系统默认图片。说明：backgroundUri或者foregroundUri或者secondaryUri设置的图片路径错误时，图片不显示。backgroundUri或者foregroundUri设置为undefined或者空字符串时，rating会选择加载系统默认星型图源。secondaryUri不设置或者设置的值为undefined或者空字符串时，优先设置为backgroundUri，效果上等同于只设置了foregroundUri、backgroundUri。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

rating宽高为[width, height]时，单个图片的绘制区域为[width / stars, height]。

为了指定绘制区域为方形，建议自定义宽高时采取[height * stars, height], width = height * stars的方式。

contentModifier12+

contentModifier(modifier: ContentModifier)

定制Rating内容区的方法。

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

参数：

参数名	类型	必填	说明
modifier	ContentModifier	是	在Rating组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

onChange

onChange(callback:(value: number) => void)

操作评分条的评星发生改变时触发该回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	number	是	评分条的评分。

键盘走焦规格

按键	功能描述
Tab	组件间切换焦点。
左右方向键	评分预览增加/减少（步长为step），不改变实际分值。
Home	移动到第一个星星，不改变实际分值。
End	移动到最后一个星星，不改变实际分值。
Space/Enter	根据当前评分提交评分结果。

RatingConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	默认值	说明
rating	number	0	评分条当前评分数。
indicator	boolean	false	评分条是否作为一个指示器。
stars	number	5	评分条的星级总数。
stepSize	number	0.5	评分条的评分步长。
triggerChange	Callback	-	触发评分数量变化。

示例1

// xxx.ets
@Entry
@Component
struct RatingExample {@State rating: number = 3.5build() {Column() {Column() {Rating({ rating: this.rating, indicator: false }).stars(5).stepSize(0.5).margin({ top: 24 }).onChange((value: number) => {this.rating = value})Text('current score is ' + this.rating).fontSize(16).fontColor('rgba(24,36,49,0.60)').margin({ top: 16 })}.width(360).height(113).backgroundColor('#FFFFFF').margin({ top: 68 })Row() {Image('common/testImage.jpg').width(40).height(40).borderRadius(20).margin({ left: 24 })Column() {Text('Yue').fontSize(16).fontColor('#182431').fontWeight(500)Row() {Rating({ rating: 3.5, indicator: false }).margin({ top: 1, right: 8 })Text('2021/06/02').fontSize(10).fontColor('#182431')}}.margin({ left: 12 }).alignItems(HorizontalAlign.Start)Text('1st Floor').fontSize(10).fontColor('#182431').position({ x: 295, y: 8 })}.width(360).height(56).backgroundColor('#FFFFFF').margin({ top: 64 })}.width('100%').height('100%').backgroundColor('#F1F3F5')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2

// xxx.ets
@Entry
@Component
struct RatingExample {@State rating: number = 3.5build() {Column() {Rating({ rating: this.rating, indicator: false }).stars(5).stepSize(0.5).starStyle({backgroundUri: '/common/imag1.png', // common目录与pages同级foregroundUri: '/common/imag2.png',secondaryUri: '/common/imag3.png'}).margin({ top: 24 }).onChange((value: number) => {this.rating = value})Text('current score is ' + this.rating).fontSize(16).fontColor('rgba(24,36,49,0.60)').margin({ top: 16 })}.width('100%').height('100%').backgroundColor('#F1F3F5')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例3

该示例实现了自定义评分条的功能，每个圆圈表示0.5分。ratingIndicator为true时表示评分条作为一个指示器不可改变评分；

为false时可以进行评分。ratingStars可改变评分总数。ratingStepsize可改变评分步长。

// xxx.ets
class MyRatingStyle implements ContentModifier<RatingConfiguration> {name: string = ""style: number = 0constructor(value1: string, value2: number) {this.name = value1this.style = value2}applyContent() : WrappedBuilder<[RatingConfiguration]> {return wrapBuilder(buildRating)}
}@Builder function buildRating(config: RatingConfiguration) {Column() {Row() {Circle({ width: 25, height: 25 }).fill(config.rating >= 0.4 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {if (config.stepSize = 0.5) {config.triggerChange(0.5);return}if (config.stepSize = 1) {config.triggerChange(1);return}}}).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden)Circle({ width: 25, height: 25 }).fill(config.rating >= 0.9 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {config.triggerChange(1);}}).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden)Circle({ width: 25, height: 25 }).fill(config.rating >= 1.4 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {if (config.stepSize = 0.5) {config.triggerChange(1.5);return}if (config.stepSize = 1) {config.triggerChange(2);return}}}).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden).margin({left:10})Circle({ width: 25, height: 25 }).fill(config.rating >= 1.9 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {config.triggerChange(2);}}).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden)Circle({ width: 25, height: 25 }).fill(config.rating >= 2.4 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {if (config.stepSize = 0.5) {config.triggerChange(2.5);return}if (config.stepSize = 1) {config.triggerChange(3);return}}}).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden).margin({left:10})Circle({ width: 25, height: 25 }).fill(config.rating >= 2.9 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {config.triggerChange(3);}}).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden)Circle({ width: 25, height: 25 }).fill(config.rating >= 3.4 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {if (config.stepSize = 0.5) {config.triggerChange(3.5);return}if (config.stepSize = 1) {config.triggerChange(4);return}}}).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden).margin({left:10})Circle({ width: 25, height: 25 }).fill(config.rating >= 3.9 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {config.triggerChange(4);}}).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden)Circle({ width: 25, height: 25 }).fill(config.rating >= 4.4 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {if (config.stepSize = 0.5) {config.triggerChange(4.5);return}if (config.stepSize = 1) {config.triggerChange(5);return}}}).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden).margin({left:10})Circle({ width: 25, height: 25 }).fill(config.rating >= 4.9 ? Color.Black : Color.Red).onClick((event: ClickEvent) => {if (!config.indicator) {config.triggerChange(5);}}).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden)}Text("分值：" + config.rating)}
}@Entry
@Component
struct ratingExample {@State rating: number = 0;@State ratingIndicator: boolean = true;@State ratingStars: number = 0;@State ratingStepsize: number = 0.5;@State ratingEnabled: boolean = true;build() {Row() {Column() {Rating({rating: 0,indicator: this.ratingIndicator}).stepSize(this.ratingStepsize).stars(this.ratingStars).backgroundColor(Color.Transparent).width('100%').height(50).onChange((value: number) => {console.info('Rating change is'+ value);this.rating = value}).contentModifier(new MyRatingStyle("hello", 3))Button(this.ratingIndicator ? "ratingIndicator : true" : "ratingIndicator : false").onClick((event) => {if (this.ratingIndicator) {this.ratingIndicator = false} else {this.ratingIndicator = true}}).margin({top : 5})Button(this.ratingStars < 5 ? "ratingStars + 1, ratingStars =" + this.ratingStars : "ratingStars最大值为5").onClick((event) => {if (this.ratingStars < 5) {this.ratingStars += 1}}).margin({top : 5})Button(this.ratingStars > 0 ? "ratingStars - 1, ratingStars =" + this.ratingStars : "ratingStars小于等于0时默认等于5").onClick((event) => {if (this.ratingStars > 0) {this.ratingStars -= 1}}).margin({top : 5})Button(this.ratingStepsize == 0.5 ? "ratingStepsize : 0.5" : "ratingStepsize : 1").onClick((event) => {if (this.ratingStepsize == 0.5) {this.ratingStepsize = 1} else {this.ratingStepsize = 0.5}}).margin({top : 5})}.width('100%').height('100%').justifyContent(FlexAlign.Center)}.height('100%')}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

RichEditor

支持图文混排和文本交互式编辑的组件。

参数：

参数名	类型	必填	说明
value	RichEditorOptions	是	富文本组件初始化选项。

RichEditor(value: RichEditorStyledStringOptions)12+

参数：

参数名	类型	必填	说明
value	RichEditorStyledStringOptions	是	富文本组件初始化选项。

属性

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

align属性只支持上方丶中间和下方位置的对齐方式。

customKeyboard

customKeyboard(value: CustomBuilder, options?: KeyboardOptions)

设置自定义键盘。

当设置自定义键盘时，输入框激活后不会打开系统输入法，而是加载指定的自定义组件。

自定义键盘的高度可以通过自定义组件根节点的height属性设置，宽度不可设置，使用系统默认值。

自定义键盘采用覆盖原始界面的方式呈现，不会对应用原始界面产生压缩或者上提。

自定义键盘无法获取焦点，但是会拦截手势事件。

默认在输入控件失去焦点时，关闭自定义键盘。

如果设备支持拍摄输入，设置自定义键盘后，该输入框会不支持拍摄输入。

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

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

参数：

参数名	类型	必填	说明
value	CustomBuilder	是	自定义键盘。元服务API：从API version 11开始，该接口支持在元服务中使用。
options12+	KeyboardOptions	否	设置自定义键盘是否支持避让功能。

bindSelectionMenu

bindSelectionMenu(spanType: RichEditorSpanType, content: CustomBuilder, responseType: ResponseType | RichEditorResponseType,

options?: SelectionMenuOptions)

设置自定义选择菜单。自定义菜单超长时，建议内部嵌套Scroll组件使用，避免键盘被遮挡。

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

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

参数：

参数名	类型	必填	说明
spanType	RichEditorSpanType	是	菜单的类型。默认值：RichEditorSpanType.TEXT
content	CustomBuilder	是	菜单的内容。
responseType	ResponseType \| RichEditorResponseType11+	是	菜单的响应类型。默认值：ResponseType.LongPress
options	SelectionMenuOptions	否	菜单的选项。

copyOptions

copyOptions(value: CopyOptions)

设置组件是否支持文本内容可复制粘贴。

copyOptions不为CopyOptions.None时，长按组件内容，会弹出文本选择弹框。如果通过bindSelectionMenu等方式自定义文本选择菜单，则会弹出自定义的菜单。

设置copyOptions为CopyOptions.None，复制、剪切功能不生效。

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

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

参数：

参数名	类型	必填	说明
value	CopyOptions	是	组件支持文本内容是否可复制粘贴。默认值：CopyOptions.LocalDevice

enableDataDetector11+

enableDataDetector(enable: boolean)

设置使能文本识别。

所识别实体的fontColor和decoration会被更改为如下样式：

fontColor：Color.Blue

decoration: {

type: TextDecorationType.Underline,

color: Color.Blue

}

该接口依赖设备底层应具有文本识别能力，否则设置不会生效。

当enableDataDetector设置为true，同时不设置dataDetectorConfig属性时，默认识别所有类型的实体。

当copyOptions设置为CopyOptions.None时，该功能不会生效。

对addBuilderSpan的节点文本，该功能不会生效。

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

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

参数：

参数名	类型	必填	说明
enable	boolean	是	使能文本识别。默认值： false

dataDetectorConfig11+

dataDetectorConfig(config: TextDataDetectorConfig)

设置文本识别配置。需配合enableDataDetector一起使用，设置enableDataDetector为true时，dataDetectorConfig的配置才能生效。

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

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

参数：

参数名	类型	必填	说明
config	TextDataDetectorConfig	是	文本识别配置。默认值：{types: [ ],onDetectResultUpdate: null}

enablePreviewText12+

enablePreviewText(enable: boolean)

设置是否开启预上屏功能。

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

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

参数：

参数名	类型	必填	说明
enable	boolean	是	使能预上屏功能。默认值： true

placeholder12+

placeholder(value: ResourceStr, style?: PlaceholderStyle)

设置无输入时的提示文本。

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

参数：

参数名	类型	必填	说明
value	ResourceStr	是	无输入时的提示文本。
style	PlaceholderStyle	否	添加提示文本的字体样式。style缺省时默认跟随主题。

caretColor12+

caretColor(value: ResourceColor)

设置输入框光标、手柄颜色。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	输入框光标、手柄颜色。默认值：‘#007DFF’

selectedBackgroundColor12+

selectedBackgroundColor(value: ResourceColor)

设置文本选中底板颜色。如果未设置不透明度，默认为20%不透明度。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	文本选中底板颜色。默认为20%不透明度。

enterKeyType12+

enterKeyType(vaule: EnterKeyType)

设置软键盘输入法回车键类型。

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

参数：

参数名	类型	必填	说明
vaule	EnterKeyType	是	键盘输入法回车键类型。默认为EnterKeyType.NEW_LINE。

事件

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

onReady

onReady(callback: () => void)

富文本组件初始化完成后，触发回调。

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

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

onSelect

onSelect(callback: (value: RichEditorSelection) => void)

鼠标左键按下选择，松开左键后触发回调。

用手指选择时，松开手指触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

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

参数：

参数名	类型	必填	说明
value	RichEditorSelection	是	选中的所有span信息。

aboutToIMEInput

aboutToIMEInput(callback: (value: RichEditorInsertValue) => boolean)

输入法输入内容前，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

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

参数：

参数名	类型	必填	说明
value	RichEditorInsertValue	是	输入法将要输入内容信息。

返回值：

类型	说明
boolean	组件是否执行添加内容操作。

onIMEInputComplete

onIMEInputComplete(callback: (value: RichEditorTextSpanResult) => void)

输入法完成输入后，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

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

参数：

参数名	类型	必填	说明
value	RichEditorTextSpanResult	是	输入法完成输入后的文本Span信息。

aboutToDelete

aboutToDelete(callback: (value: RichEditorDeleteValue) => boolean)

输入法删除内容前，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

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

参数：

参数名	类型	必填	说明
value	RichEditorDeleteValue	是	准备删除的内容所在的文本或者图片Span信息。

返回值：

类型	说明
boolean	组件是否执行删除操作。

onDeleteComplete

onDeleteComplete(callback: () => void)

输入法完成删除后，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

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

onPaste11+

onPaste(callback: (event?: PasteEvent) => void)

完成粘贴前，触发回调。系统的默认粘贴，只支持纯文本的粘贴。开发者可以通过该方法，覆盖系统默认行为，实现图文的粘贴。

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

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

参数：

参数名	类型	必填	说明
event	PasteEvent	否	定义用户粘贴事件。

onSelectionChange12+

onSelectionChange(callback: (value: RichEditorRange) => void)

文本选择区域发生变化或编辑状态下光标位置发生变化时触发该回调。光标位置发生变化回调时，选择区域的起始位置等于终止位置。

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

参数：

参数名	类型	必填	说明
value	RichEditorRange	否	文本选择区域起始和终止位置。

onEditingChange12+

onEditingChange(callback: Callback)

文本编辑状态发生改变时触发该回调函数。

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

参数：

参数名	类型	必填	说明
callback	Callback	是	true表示编辑态，false表示非编辑态。

onSubmit12+

onSubmit(callback: SubmitCallback)

按下软键盘输入法回车键触发该回调。

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

参数：

参数名	类型	必填	说明
callback	SubmitCallback	是	侦听事件的回调。

onWillChange12+

onWillChange(callback: Callback<RichEditorChangeValue, boolean>)

文本变化前，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

参数：

参数名	类型	必填	说明
callback	Callback<RichEditorChangeValue , boolean>	是	RichEditorChangeValue为文本变化信息；boolean表示当前文本是否允许被更改，true：允许文本被更改。false：不允许文本被更改。

onDidChange12+

onDidChange(callback: Callback)

文本变化后，触发回调。

使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调。

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

参数：

参数名	类型	必填	说明
callback	Callback<OnDidChangeCallback>	是	文本变化前后的内容范围。

onCut12+

onCut(callback: Callback)

完成剪切前，触发回调。系统的默认剪切行为，只支持纯文本的剪切。开发者可以通过该方法，覆盖系统默认行为，实现图文的剪切。

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

参数：

参数名	类型	必填	说明
callback	Callback<CutEvent>	是	定义用户剪切事件。

onCopy12+

onCopy(callback: Callback)

完成复制前，触发回调。系统的默认复制行为，只支持纯文本的复制。开发者可以通过该方法，覆盖系统默认行为，实现图文的复制。

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

参数：

参数名	类型	必填	说明
callback	Callback<CopyEvent>	是	定义用户复制事件。

RichEditorInsertValue

插入文本信息。

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

名称	类型	必填	说明
insertOffset	number	是	插入的文本偏移位置。元服务API：从API version 11开始，该接口支持在元服务中使用。
insertValue	string	是	插入的文本内容。元服务API：从API version 11开始，该接口支持在元服务中使用。
previewText12+	string	否	插入的预上屏文本内容。元服务API：从API version 12开始，该接口支持在元服务中使用。

RichEditorDeleteValue

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

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

名称	类型	必填	说明
offset	number	是	删除内容的偏移位置。
direction	RichEditorDeleteDirection	是	删除操作的方向。
length	number	是	删除内容长度。
richEditorDeleteSpans	Array<RichEditorTextSpanResult \| RichEditorImageSpanResult>	是	删除的文本或者图片Span的具体信息。

RichEditorDeleteDirection

删除操作的方向。

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

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

名称	描述
BACKWARD	向后删除。
FORWARD	向前删除。

RichEditorTextSpanResult

文本Span信息。

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

名称	类型	必填	说明
spanPosition	RichEditorSpanPosition	是	Span位置。元服务API：从API version 11开始，该接口支持在元服务中使用。
value	string	是	文本Span内容。元服务API：从API version 11开始，该接口支持在元服务中使用。
textStyle	RichEditorTextStyleResult	是	文本Span样式信息。元服务API：从API version 11开始，该接口支持在元服务中使用。
offsetInSpan	[number, number]	是	文本Span内容里有效内容的起始和结束位置。元服务API：从API version 11开始，该接口支持在元服务中使用。
valueResource11+	Resource	否	组件SymbolSpan内容。
SymbolSpanStyle11+	RichEditorSymbolSpanStyle	否	组件SymbolSpan样式信息。元服务API：从API version 12开始，该接口支持在元服务中使用。
paragraphStyle12+	RichEditorParagraphStyle	否	段落样式。元服务API：从API version 12开始，该接口支持在元服务中使用。
previewText12+	string	否	文本Span预上屏内容。元服务API：从API version 12开始，该接口支持在元服务中使用。

RichEditorSpanPosition

Span位置信息。

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

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

名称	类型	必填	说明
spanIndex	number	是	Span索引值。
spanRange	[number, number]	是	Span内容在RichEditor内的起始和结束位置。

RichEditorSpanType

Span类型信息。

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

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

名称	值	描述
TEXT	0	Span为文字类型。
IMAGE	1	Span为图像类型。
MIXED	2	Span为图文混合类型。

RichEditorTextStyleResult

后端返回的文本样式信息。

名称	类型	必填	说明
fontColor	ResourceColor	是	文本颜色。元服务API：从API version 11开始，该接口支持在元服务中使用。
fontSize	number	是	字体大小，默认单位为fp。元服务API：从API version 11开始，该接口支持在元服务中使用。
fontStyle	FontStyle	是	字体样式。元服务API：从API version 11开始，该接口支持在元服务中使用。
fontWeight	number	是	字体粗细。元服务API：从API version 11开始，该接口支持在元服务中使用。
fontFamily	string	是	字体列表。元服务API：从API version 11开始，该接口支持在元服务中使用。
decoration	{type: TextDecorationType,color: ResourceColor}	是	文本装饰线样式及其颜色。元服务API：从API version 11开始，该接口支持在元服务中使用。
lineHeight12+	number	否	文本行高，默认单位为fp。
letterSpacing12+	number	否	文本字符间距，默认单位为fp。
fontFeature12+	string	否	文字特性效果。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

在RichEditorTextStyle中，fontWeight是设置字体粗细的输入参数。

而在RichEditorTextStyleResult中，会将之前设置的字体粗细转换为数字后返回。

转换关系如下：

RichEditorTextStyle中的fontWeight	RichEditorTextStyleResult中的fontWeight
100	0
200	1
300	2
400	3
500	4
600	5
700	6
800	7
900	8
Lighter	12
Normal	10
Regular	14
Medium	13
Bold	9
Bolder	11

RichEditorSymbolSpanStyle和RichEditorSymbolSpanStyleResult中fontWeight的转换关系，

与RichEditorTextStyle和RichEditorTextStyleResult中fontWeight的转换关系一致。

RichEditorSymbolSpanStyleResult11+

后端返回的SymbolSpan样式信息。

名称	类型	必填	说明
fontColor	Array<ResourceColor>	否	SymbolSpan组件颜色。默认值：不同渲染策略下默认值不同。
fontSize	number \| string \| Resource	否	SymbolSpan组件大小，默认单位为fp。默认值：跟随主题。
fontWeight	FontWeight \| number \| string	否	SymbolSpan组件粗细。number类型取值[100,900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular” 、“medium”分别对应FontWeight中相应的枚举值。默认值：FontWeight.Normal。
renderingStrategy	SymbolRenderingStrategy	否	SymbolSpan组件渲染策略。默认值：SymbolRenderingStrategy.SINGLE。说明：$r(‘sys.symbol.ohos_*’)中引用的资源仅ohos_folder_badge_plus支持分层与多色模式。
effectStrategy	SymbolEffectStrategy	否	SymbolSpan组件动效策略。默认值：SymbolEffectStrategy.NONE。说明：$r(‘sys.symbol.ohos_*’)中引用的资源仅ohos_wifi支持层级动效模式。

RichEditorImageSpanResult

后端返回的图片信息。

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

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

名称	类型	必填	说明
spanPosition	RichEditorSpanPosition	是	Span位置。
valuePixelMap	PixelMap	否	图片内容。
valueResourceStr	ResourceStr	否	图片资源id。
imageStyle	RichEditorImageSpanStyleResult	是	图片样式。
offsetInSpan	[number, number]	是	Span里图片的起始和结束位置。

RichEditorImageSpanStyleResult

后端返回的图片样式信息。

名称	类型	必填	说明
size	[number, number]	是	图片的宽度和高度，单位为px。默认值：size的默认值与objectFit的值有关，不同的objectFit值对应的size默认值也不同。objectFit的值为Cover时，图片高度为组件高度减去组件上下内边距，图片宽度为组件宽度减去组件左右内边距。元服务API：从API version 11开始，该接口支持在元服务中使用。
verticalAlign	ImageSpanAlignment	是	图片垂直对齐方式。元服务API：从API version 11开始，该接口支持在元服务中使用。
objectFit	ImageFit	是	图片缩放类型。元服务API：从API version 11开始，该接口支持在元服务中使用。
layoutStyle12+	RichEditorLayoutStyle	否	图片布局风格。

RichEditorLayoutStyle11+

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

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

名称	类型	必填	说明
margin	Dimension \| Margin	否	外边距类型，用于描述组件不同方向的外边距。参数为Dimension类型时，四个方向外边距同时生效。
borderRadius	Dimension \| BorderRadiuses	否	圆角类型，用于描述组件边框圆角半径。参数为Dimension类型时，不支持以Percentage形式设置。

RichEditorOptions

RichEditor初始化参数。

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

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

名称	类型	必填	说明
controller	RichEditorController	是	富文本控制器。

RichEditorStyledStringOptions12+

RichEditor初始化参数。

名称	类型	必填	说明
controller	RichEditorStyledStringController	是	富文本控制器。

SelectionOptions12+

setSelection的选择项配置。

名称	类型	必填	说明
menuPolicy	MenuPolicy	否	菜单弹出的策略。

TextDataDetectorConfig11+

文本识别配置参数。

名称	类型	必填	说明
types	TextDataDetectorType[]	是	文本识别的实体类型。设置types为null或者[]时，识别所有类型的实体，否则只识别指定类型的实体。
onDetectResultUpdate	(result: string) => void	否	文本识别成功后，触发onDetectResultUpdate回调。result：文本识别的结果，Json格式。

RichEditorChangeValue12+

名称	类型	必填	说明
rangeBefore	TextRange	是	替换前文本Span的具体信息。
replacedSpans	Array<RichEditorTextSpanResult>	是	替换后文本Span的具体信息。
replacedImageSpans	Array<RichEditorImageSpanResult>	是	替换后ImageSpan的具体信息。
replacedSymbolSpans	Array<RichEditorTextSpanResult>	是	替换后SymbolSpan的具体信息。

RichEditorController

RichEditor组件的控制器。

导入对象

controller: RichEditorController = new RichEditorController()

getCaretOffset

getCaretOffset(): number

返回当前光标所在位置。

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

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

返回值：

类型	说明
number	当前光标所在位置。

setCaretOffset

setCaretOffset(offset: number): boolean

设置光标位置。

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

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

参数：

参数名	类型	必填	说明
offset	number	是	光标偏移位置。超出文本范围时，设置失败。

返回值：

类型	说明
boolean	光标是否设置成功。

addTextSpan

addTextSpan(value: string, options?: RichEditorTextSpanOptions): number

添加文本内容，如果组件光标闪烁，插入后光标位置更新为新插入文本的后面。

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

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

参数：

参数名	类型	必填	说明
value	string	是	文本内容。
options	RichEditorTextSpanOptions	否	文本选项。

返回值：

类型	说明
number	添加完成的TextSpan所在的位置。

addImageSpan

addImageSpan(value: PixelMap | ResourceStr, options?: RichEditorImageSpanOptions): number

添加图片内容，如果组件光标闪烁，插入后光标位置更新为新插入图片的后面。

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

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

参数：

参数名	类型	必填	说明
value	PixelMap\|ResourceStr	是	图片内容。
options	RichEditorImageSpanOptions	否	图片选项。

返回值：

类型	说明
number	添加完成的ImageSpan所在的位置。

addBuilderSpan11+

addBuilderSpan(value: CustomBuilder, options?: RichEditorBuilderSpanOptions): number

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

RichEditor组件添加占位Span，占位Span调用系统的measure方法计算真实的长宽和位置。
可通过RichEditorBuilderSpanOptions设置此builder在RichEditor中的index（一个文字为一个单位）。
此占位Span不可获焦，支持拖拽，支持部分通用属性，占位、删除等能力等同于ImageSpan，长度视为一个文字。
不支持通过bindSelectionMenu设置自定义菜单。
不支持通过getSpans，getSelection，onSelect，aboutToDelete获取builderSpan信息。
不支持通过updateSpanStyle，updateParagraphStyle等方式更新builder。
对此builder节点进行复制或粘贴不生效。
builder的布局约束由RichEditor传入，如果builder里最外层组件不设置大小，则会用RichEditor的大小作为maxSize。
builder的手势相关事件机制与通用手势事件相同，如果builder中未设置透传，则仅有builder中的子组件响应。
如果组件光标闪烁，插入后光标位置更新为新插入builder的后面。

通用属性仅支持size、padding、margin、aspectRatio、borderStyle、borderWidth、borderColor、borderRadius、backgroundColor、backgroundBlurStyle、opacity、blur、backdropBlur、shadow、grayscale、brightness、saturate、

contrast、invert、sepia、hueRotate、colorBlend、linearGradientBlur、clip、mask、foregroundBlurStyle、accessibilityGroup、accessibilityText、accessibilityDescription、accessibilityLevel、sphericalEffect、lightUpEffect、pixelStretchEffect。

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

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

参数：

参数名	类型	必填	说明
value	CustomBuilder	是	自定义组件。
options	RichEditorBuilderSpanOptions	否	builder选项。

返回值：

类型	说明
number	添加完成的builderSpan所在的位置。

addSymbolSpan11+

addSymbolSpan(value: Resource, options?: RichEditorSymbolSpanOptions ): number

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

参数：

参数名	类型	必填	说明
offset	number	是	光标偏移位置。超出文本范围时，设置失败。

返回值：

类型	说明
boolean	光标是否设置成功。

addTextSpan

addTextSpan(value: string, options?: RichEditorTextSpanOptions): number

添加文本内容，如果组件光标闪烁，插入后光标位置更新为新插入文本的后面。

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

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

参数：

参数名	类型	必填	说明
value	string	是	文本内容。
options	RichEditorTextSpanOptions	否	文本选项。

返回值：

类型	说明
number	添加完成的TextSpan所在的位置。

addImageSpan

addImageSpan(value: PixelMap | ResourceStr, options?: RichEditorImageSpanOptions): number

添加图片内容