基础组件

AlphabetIndexer可以与容器组件联动用于按逻辑结构快速定位容器显示区域的组件。

组件	作用	参数名	参数类型	必填	描述
接口AlphabetIndexer		arrayValue	Array	是	字母索引字符串数组，不可设置为空。
		selected	number	是	初始选中项索引值，若超出索引值范围，则取默认值0。从API version 10开始，该参数支持$$双向绑定变量。
color	设置文字颜色。	value	ResourceColor	是	文字颜色。默认值：0x99182431。
selectedColor	设置选中项文字颜色。	value	ResourceColor	是	选中项文字颜色。默认值：0xFF007DFF。
popupColor	设置提示弹窗文字颜色。	value	ResourceColor	是	提示弹窗文字颜色。默认值：0xFF007DFF。
selectedBackgroundColor	设置选中项背景颜色。	value	ResourceColor	是	选中项背景颜色。默认值：0x1A007DFF。设置选中项背景颜色
popupBackground	设置提示弹窗背景色	value	ResourceColor	是	提示弹窗背景色。默认值：API version 11及以前：0xFFFFFFFF。API version 12及以后：#66808080。
usingPopup	设置是否使用提示弹窗。	value	boolean	是	是否使用提示弹窗。默认值：false
selectedFont	设置选中项文字样式。	value	Font	是	选中项文字样式。默认值：API version 11及以前：{size:‘12.0fp’,style:FontStyle.Normal,weight:FontWeight.Normal,family:‘HarmonyOS Sans’}API version 12及以后：{size:‘10.0vp’,style:FontStyle.Normal,weight:FontWeight.Medium,family:‘HarmonyOS Sans’}
popupFont	设置提示弹窗字体样式。	value	Font	是	提示弹窗字体样式。默认值：{size:‘24.0vp’,style:FontStyle.Normal,weight:FontWeight.Normal,family:‘HarmonyOS Sans’}
font	设置字母索引条默认字体样式。	value	Font	是	字母索引条默认字体样式。默认值：API version 11及以前：{size:‘12.0fp’,style:FontStyle.Normal,weight:FontWeight.Normal,family:‘HarmonyOS Sans’}API version 12及以后：{size:‘10.0vp’,style:FontStyle.Normal,weight:FontWeight.Medium,family:‘HarmonyOS Sans’}
itemSize	设置字母索引条字母区域大小。	value	string | number	是	字母索引条字母区域大小，字母区域为正方形，即正方形边长。不支持设置为百分比。默认值：16.0单位：vp
alignStyle	设置字母索引条弹框的对齐样式。	value	IndexerAlign	是	字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。默认值: IndexerAlign.END。
		offset10+	Length	否	提示弹窗与索引条之间间距，大于等于0为有效值，在不设置或设置为小于0的情况下间距与popupPosition.x相同。与popupPosition同时设置时，水平方向上offset生效，竖直方向上popupPosition.y生效。
selected	设置选中项索引值。	index	number	是	选中项索引值。默认值：0
popupPosition	设置弹出窗口相对于索引器条上边框中点的位置	value	Position	是	弹出窗口相对于索引器条上边框中点的位置。默认值：{x:60.0, y:48.0}
popupSelectedColor	设置提示弹窗非字母部分选中文字色	value	ResourceColor	是	提示弹窗非字母部分选中文字色。默认值：#FF182431
popupUnselectedColor	设置提示弹窗非字母部分未选中文字色	value	ResourceColor	是	提示弹窗非字母部分未选中文字色。默认值：#FF182431
popupItemFont	设置提示弹窗非字母部分字体样式	value	Font	是	提示弹窗非字母部分字体样式。默认值：{size:24,weight:FontWeight.Medium}
popupItemBackgroundColor	设置提示弹窗非字母部分背景色。	value	ResourceColor	是	提示弹窗非字母部分背景色。默认值：API version 11及以前：#FFFFFFFF。API version 12及以后：#00000000。
autoCollapse	设置是否使用自适应折叠模式	value	boolean	是	是否使用自适应折叠模式。默认值：false
popupItemBorderRadius	设置提示弹窗索引项背板圆角半径	value	number	是	设置提示弹窗索引项背板圆角半径。默认值：24vp。不支持百分比，小于0时按照0设置。提示弹窗背板圆角自适应变化（索引项圆角半径+4vp）。
itemBorderRadius	设置索引项背板圆角半径	value	number	是	设置索引项背板圆角半径。默认值：8vp不支持百分比，小于0时按照0设置。索引条背板圆角自适应变化（索引项圆角半径+4vp）。
popupBackgroundBlurStyle	设置提示弹窗的背景模糊材质	value	BlurStyle	是	设置提示弹窗的背景模糊材质。默认值：COMPONENT_REGULAR。
popupTitleBackground	设置提示弹窗首个索引项背板颜色	value	ResourceColor	是	设置提示弹窗首个索引项背板颜色。默认值：提示弹窗只有一个索引项：#00FFFFFF。提示弹窗有多个索引项：#0c182431。
enableHapticFeedback		enable	boolean	否	支持触控反馈。默认值：true。
IndexerAlign枚举说明		Left			弹框显示在索引条右侧。
		Right			弹框显示在索引条左侧。
		START12+			在LTR场景下，弹框显示在索引条右侧的位置。在RTL场景下，弹框显示在索引条左侧的位置。
		END12+			在LTR场景下，弹框显示在索引条左侧的位置。在RTL场景下，弹框显示在索引条右侧的位置

Blank空白填充组件

空白填充组件，在容器主轴方向上，空白填充组件具有自动填充容器空余部分的能力。仅当父组件为Row/Column/Flex时生效。

组件	作用	参数名	参数类型	必填	描述
接口Blank		min	number | string	否	空白填充组件在容器主轴上的最小大小。默认值：0**说明：**不支持设置百分比。负值使用默认值。当最小值大于容器可用空间时，使用最小值作为自身大小并超出容器
color	设置空白填充的填充颜色。	value	ResourceColor	是	空白填充的填充颜色。默认值：Color.Transparent

Button按钮组件，可快速创建不同样式的按钮。

组件	作用	参数名	参数类型	必填	描述
接口Button		options	ButtonOptions	是	配置按钮的显示样式。
Button	使用文本内容创建相应的按钮组件，此时Button无法包含子组件。	label	ResourceStr	是	按钮文本内容。
		options	ButtonOptions	否	配置按钮的显示样式。
ButtonOptions对象说明		type	ButtonType	否	描述按钮显示样式。默认值：ButtonType.Capsule元服务API： 从API version 11开始，该接口支持在元服务中使用。
		stateEffect	boolean	否	按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true**说明：**当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API： 从API version 11开始，该接口支持在元服务中使用。
		buttonStyle11+	ButtonStyleMode	否	描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED**说明：**按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API： 从API version 12开始，该接口支持在元服务中使用。
		controlSize11+	ControlSize	否	描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API： 从API version 12开始，该接口支持在元服务中使用。
		role12+	ButtonRole	否	描述按钮的角色。默认值：ButtonRole.NORMAL
type	设置Button样式。	value	ButtonType	是	Button样式。默认值：ButtonType.Capsule
fontSize	设置文本显示字号。	value	Length	是	文本显示字号。默认值：若controlSize的值为：controlSize.NORMAL，取’16fp’，若controlSize的值为：controlSize.SMALL，取’12fp’
fontColor	设置文本显示颜色。	value	ResourceColor	是	文本显示颜色。默认值：‘#ffffff’
fontWeight	设置文本的字体粗细。	value	FontWeight |number|string		文本的字体粗细，number类型取值[100, 900]，取值间隔为100，取值越大，字体越粗
fontStyle	设置文本的字体样式。	value	FontStyle	是	文本的字体样式。默认值：FontStyle.Normal。
stateEffect	设置是否开启按压态显示效果。	value	boolean	是	按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true
fontFamily	设置字体列表。	value	Resource | string	是	字体列表。默认字体’HarmonyOS Sans’，当前支持’HarmonyOS Sans’字体和注册自定义字体。
labelStyle	设置Button组件label文本和字体的样式。	value	LabelStyle	是	Button组件label文本和字体的样式。
buttonStyle	设置Button组件的样式和重要程度。	value	ButtonStyleMode	是	Button组件的样式和重要程度。默认值:ButtonStyleMode.EMPHASIZED
controlSize	设置Button组件的尺寸。	value	ControlSize	是	Button组件的尺寸。默认值:ControlSize.NORMAL
role	设置Button组件的角色	value	ButtonRole	是	设置Button组件的角色。默认值:ButtonRole.NORMAL
contentModifier	定制Button内容区的方法。	modifier	ContentModifier	是	在Button组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。
ButtonType枚举说明	Capsule	胶囊型按钮（圆角默认为高度的一半）。
	Circle	圆形按钮。
	Normal	普通按钮（默认不带圆角）。

CalendarPicker日历选择器组件，提供下拉日历弹窗，可以让用户选择日期

组件	作用	参数名	参数类型	必填	描述
接口CalendarPicker		options	CalendarOptions	否	配置日历选择器组件的参数。
edgeAlign	设置选择器与入口组件的对齐方式。	alignType	CalendarAlign	是	对齐方式类型。默认值：CalendarAlign .END
		offset	Offset	否	按照对齐类型对齐后，选择器相对入口组件的偏移量。默认值：{dx: 0, dy: 0}
textStyle	入口区的文本颜色、字号、字体粗细。	value	PickerTextStyle	是	设置入口区的文本颜色、字号、字体粗细。默认值：{color: ‘#ff182431’,font: {size: ‘16fp’,weight: FontWeight.Regular}}
onChange	选择日期时触发该事件。	value	Date	是	选中的日期值。
CalendarOptions对象说明		hintRadius	number | Resource	否	描述日期选中态底板样式。默认值：底板样式为圆形。**说明：**hintRadius为0，底板样式为直角矩形。hintRadius为0 ~ 16，底板样式为圆角矩形。hintRadius>=16，底板样式为圆形
		selected	Date	否	设置选中项的日期。选中的日期未设置或日期格式不符合规范则为默认值。默认值：当前系统日期。
CalendarAlign枚举说明		START	设置选择器与入口组件左对齐的对齐方式。
		CENTER	设置选择器与入口组件居中对齐的对齐方式。
		END	设置选择器与入口组件右对齐的对齐方式。

多选Checkbox

组件	参数名	参数类型	必填	描述	作用
	options	CheckboxOptions	否	配置复选框的参数。
CheckboxOptions对象说明	name	string	否	用于指定多选框名称。
	group	string	否	用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。**说明：**未配合使用CheckboxGroup组件时，此值无用。
	indicatorBuilder12+	CustomBuilder	否	配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。
select	value	boolean	是	多选框是否选中。默认值：false	设置多选框是否选中。
selectedColor	value	ResourceColor	是	多选框选中状态颜色。默认值：$r(‘sys.color.ohos_id_color_text_primary_activated’)。异常值按照默认值处理。	设置多选框选中状态颜色。
unselectedColor	value	ResourceColor	是	多选框非选中状态边框颜色。默认值：‘#33ffffff’。	设置多选框非选中状态边框颜色。
mark	value	MarkStyle	是	多选框内部图标样式。 从API version 12开始，设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。	设置多选框内部图标样式。
shape	value	CheckBoxShape	是	CheckBox组件形状, 包括圆形和圆角方形。默认值：CheckBoxShape.CIRCLE	设置CheckBox组件形状, 包括圆形和圆角方形
contentModifier	modifier	ContentModifier	是	在CheckBox组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。	定制CheckBox内容区的方法。

CheckboxGroup多选框群组，用于控制多选框全选或者不全选状态。

组件	作用	参数名	参数类型	必填	描述
接口CheckboxGroup		options	CheckboxGroupOptions	否	配置多选框群组参数。
CheckboxGroupOptions对象说明		group	string	否	群组名称。**说明：**多个相同群组名称的CheckboxGroup，仅第一个CheckboxGroup生效。
selectAll	设置是否全选。若同组的Checkbox显式设置了select属性，则Checkbox的优先级高	value	boolean	是	是否全选。默认值：false
selectedColor	设置被选中或部分选中状态的颜色。	value	ResourceColor	是	被选中或部分选中状态的颜色。默认值：$r(‘sys.color.ohos_id_color_text_primary_activated’)异常值按照默认值处理。
unselectedColor	设置非选中状态边框颜色。	value	ResourceColor	是	非选中状态边框颜色。默认值：‘#33ffffff’。
mark	设置多选框内部图标样式。	value	MarkStyle	是	多选框内部图标样式。
checkboxShape	设置CheckboxGroup组件形状， 包括圆形和圆角方形。	value	CheckBoxShape	是	设置CheckboxGroup组件形状， 包括圆形和圆角方形。默认值:CheckBoxShape.CIRCLE。说明：CheckboxGroup组件形状按照设置显示。CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。
onChange	CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。	event	CheckboxGroupResult	是	多选框群组的信息。

枚举	名称	类型	描述
CheckboxGroupResult对象说明	name	Array	群组内所有被选中的多选框名称。
	status	SelectStatus	选中状态。
SelectStatus枚举说明	All		群组多选择框全部选择。
	Part		群组多选择框部分选择
	None		群组多选择框全部没有选择

MarkStyle10+对象说明

名称	类型	必填	默认值	描述
strokeColor	ResourceColor	否	Color.White	内部图标颜色。
size	Length	否	-	内部图标大小，单位vp。默认大小与多选框群组组件宽度设置值一致。不支持百分比形式设置。当设置为非法值时，按照默认值处理。
strokeWidth	Length	否	2	内部图标粗细，单位vp。不支持百分比形式设置。当设置为非法值时，按照默认值处理。

ContainerSpanText组件的子组件，用于统一管理多个Span、ImageSpan的背景色及圆角弧度。

组件	参数名	类型	必填	说明
textBackgroundStyle	style	TextBackgroundStyle	是	文本背景样式。默认值：{color: Color.Transparent,radius: 0}

TextBackgroundStyle对象说明

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

名称	参数类型	必填	描述
color	ResourceColor	否	文本背景色。
radius	Dimension | BorderRadiuses	否	文本背景圆角。

DataPanel数据面板组件，用于将多个数据占比情况使用占比图进行展示

接口DataPanel

参数名	参数类型	必填	参数描述
options	DataPanelOptions	是	数据面板组件参数。

DataPanelOptions对象说明

参数名	参数类型	必填	参数描述
values	number[]	是	数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。
max	number	否	- max大于0，表示数据的最大值。- max小于等于0，max等于value数组各项的和，按比例显示。默认值：100
type8+	DataPanelType	否	数据面板的类型（不支持动态修改）。默认值：DataPanelType.Circle

DataPanelType8+枚举说明

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

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

名称	描述
Line	线型数据面板。
Circle	环形数据面板。

组件	作用	参数名	类型	必填	说明
closeEffect	设置关闭数据占比图表旋转动效和投影效果	value	boolean	是	关闭数据占比图表旋转动效和投影效果。默认值：false
valueColors	设置各数据段颜色	value	Array<ResourceColor | LinearGradient>	是	各数据段颜色，ResourceColor为纯色，LinearGradient为渐变色。
trackBackgroundColor	设置底板颜色。	value	ResourceColor	是	底板颜色。默认值：‘#08182431’，格式为十六进制ARGB值，前俩位代表透明度。
strokeWidth	设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。	value	Length	是	圆环粗细。默认值：24单位：vp**说明：**设置小于0的值时，按默认值显示。
trackShadow	设置投影样式。	value	DataPanelShadowOptions	是	投影样式。**说明：**设置null为不开启投影。
contentModifier	定制DataPanel内容区的方法	modifier	ContentModifier	是	在DataPanel组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

DatePicker日期选择器组件，用于根据指定日期范围创建日期滑动选择器。

接口DatePicker(options?: DatePickerOptions)

根据指定范围的Date创建可以选择日期的滑动选择器。

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

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

参数：

参数名	类型	必填	描述
options	DatePickerOptions	否	配置日期选择器组件的参数。

DatePickerOptions对象说明

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

名称	类型	必填	说明
start	Date	否	指定选择器的起始日期。默认值：Date(‘1970-1-1’)
end	Date	否	指定选择器的结束日期。默认值：Date(‘2100-12-31’)
selected	Date	否	设置选中项的日期。默认值：当前系统日期从API version 10开始，该参数支持$$双向绑定变量。

异常情形说明:

异常情形	对应结果
起始日期晚于结束日期，选中日期未设置	起始日期、结束日期和选中日期都为默认值
起始日期晚于结束日期，选中日期早于起始日期默认值	起始日期、结束日期都为默认值，选中日期为起始日期默认值
起始日期晚于结束日期，选中日期晚于结束日期默认值	起始日期、结束日期都为默认值，选中日期为结束日期默认值
起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内	起始日期、结束日期都为默认值，选中日期为设置的值
选中日期早于起始日期	选中日期为起始日期
选中日期晚于结束日期	选中日期为结束日期
起始日期晚于当前系统日期，选中日期未设置	选中日期为起始日期
结束日期早于当前系统日期，选中日期未设置	选中日期为结束日期
日期格式不符合规范，如‘1999-13-32’	取默认值
起始日期或结束日期早于系统有效范围	起始日期或结束日期取起始日期默认值
起始日期或结束日期晚于系统有效范围	起始日期或结束日期取结束日期默认值
起始日期与结束日期同时早于系统有效范围	起始日期与结束日期取系统有效范围最早日期
起始日期与结束日期同时晚于系统有效范围	起始日期与结束日期取系统有效范围最晚日期

系统日期范围：1900-1-31 ~ 2100-12-31

选中日期会在起始日期与结束日期异常处理完成后再进行异常情形判断处理

组件	作用	参数名	类型	必填	说明
lunar	设置弹窗的日期是否显示农历。	value	boolean	是	日期是否显示农历。- true：展示农历。- false：不展示农历。默认值：false
disappearTextStyle	设置所有选项中最上和最下两个选项的文本样式	value	PickerTextStyle	是	所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。默认值：{color: ‘#ff182431’,font: {size: ‘14fp’,weight: FontWeight.Regular}}
textStyle	设置所有选项中除了最上、最下及选中项以外的文本样式	value	PickerTextStyle	是	所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。默认值：{color: ‘#ff182431’,font: {size: ‘16fp’,weight: FontWeight.Regular}}
selectedTextStyle	设置选中项的文本样式。	value	PickerTextStyle	是	选中项的文本颜色、字号、字体粗细。默认值：{color: ‘#ff007dff’,font: {size: ‘20vp’,weight: FontWeight.Medium}}

PickerTextStyle10+类型说明

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

参数名	参数类型	必填	参数描述
color	ResourceColor	否	文本颜色。
font	Font	否	文本样式，picker只支持字号、字体粗细的设置。

事件

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

onChange(deprecated)

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

选择日期时触发该事件。

参数：

参数名	类型	必填	说明
value	DatePickerResult	是	返回选中的时间。

onDateChange10+

onDateChange(callback: (value: Date) => void)

选择日期时触发该事件。

参数名	类型	必填	说明
value	Date	是	返回选中的时间，年月日为选中的日期，时分取决于当前系统时间的时分，秒恒为00。

DatePickerResult对象说明

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

名称	参数类型	描述
year	number	选中日期的年。
month	number	选中日期的月(0~11)，0表示1月，11表示12月。
day	number	选中日期的日。

Divider提供分隔器组件，分隔不同内容块/内容元素。

组件	作用	参数名	类型	必填	说明
vertical	设置分割线的方向。	value	boolean	是	使用水平分割线还是垂直分割线。false：水平分割线；true：垂直分割线。默认值：false
color	设置分割线的颜色。	value	ResourceColor	是	分割线颜色。默认值：‘#33182431’
strokeWidth	设置分割线的宽度	value	number | string	是	分割线宽度。默认值：1px单位：vp**说明：**分割线的宽度不支持百分比设置。优先级低于通用属性height，超过通用属性设置大小时，按照通用属性进行裁切。
lineCap	设置分割线的端点样式。	value	LineCapStyle	是	分割线的端点样式。默认值：LineCapStyle.Butt

Gauge数据量规图表组件，用于将数据展示为环形图表。

接口

Gauge(options:{value: number, min?: number, max?: number})

创建数据量规图表组件。

参数：

参数名	类型	必填	说明
value	number	是	量规图的当前数据值，即图中指针指向位置。用于组件创建时量规图初始值的预置。**说明：**value不在min和max范围内时使用min作为默认值。
min	number	否	当前数据段最小值。默认值：0
max	number	否	当前数据段最大值。默认值：100**说明：**max小于min时使用默认值0和100。max和min支持负数。

组件	作用	参数名	类型	必填	说明
value	设置量规图的数据值。	value	number	是	量规图的数据值，可用于动态修改量规图的数据值。默认值：0
startAngle	设置起始角度位置	angle	number	是	起始角度位置，时钟0点为0度，顺时针方向为正角度。默认值：0
endAngle	设置终止角度位置	angle	number	是	终止角度位置，时钟0点为0度，顺时针方向为正角度。默认值：360
colors	设置量规图的颜色	colors	ResourceColor11+ | LinearGradient11+ | Array<[ResourceColor | LinearGradient11+ | number]>	是	量规图的颜色，支持分段颜色设置。API version 9 默认值：Color.BlackAPI version 11默认值：若不传颜色，或者数组为空，无法确定圆环类型及颜色，则圆环颜色为"0xFF64BB5C"、“0xFFF7CE00”、“0xFFE84026"的渐变环。若传入颜色，但颜色值有误，则该颜色为"0xFFE84026”。
strokeWidth	设置环形量规图的环形厚度。	length	Length	是	环形量规图的环形厚度。默认值：4单位：vp**说明：**设置小于0的值时，按默认值显示。不支持百分比。
description	设置说明内容	value	CustomBuilder	是	说明内容。说明：@Builder中的内容由开发者自定义，建议使用文本或者图片。若自定义部分的宽高为百分比形式，则基准范围为圆环直径的44.4%*25.4%的矩形（图片为28.6%*28.6%），距离圆环底部0vp，左右居中。设置null则不显示内容。不设置则依赖是否设置数据最大最小值。若设置最大最小值或者只设置其中一个，则显示最大最小值。若未设置最大最小值，则不显示内容。最大最小值显示在圆环底部，位置不可移动，若圆环开口角度设置不恰当，存在圆环遮挡文字的情况。
trackShadow	设置阴影样式	value	GaugeShadowOptions	是	阴影样式。**说明：**阴影颜色与圆环颜色一致。设置null为不开启投影。
indicator	设置指针样式	value	GaugeIndicatorOptions	是	指针样式。**说明：**设置null则不显示指针。
privacySensitive	设置隐私敏感。	isPrivacySensitiveMode	[Optional]	是	设置隐私敏感，隐私模式下Gauge指针指向0位置，最大值最小值文本将被遮罩，量程显示灰色或者底色。**说明：**设置null则不敏感。需要卡片框架支持。
contentModifier	定制Slider内容区的方法。	modifier	ContentModifier	是	在Gauge组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

GaugeShadowOptions11+对象说明

GaugeShadowOptions继承自MultiShadowOptions，具有MultiShadowOptions的全部属性。

GaugeIndicatorOptions11+对象说明

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

名称	参数类型	必填	描述
icon	Resource	否	图标资源路径。**说明：**不配置则使用默认的三角形样式指针。支持使用svg格式的图标，若使用其他格式，则使用默认的三角形样式指针。
space	Dimension	否	指针距离圆环外边的间距。(不支持百分比)默认值：8单位：vp**说明：**对于默认的三角形样式指针，间距为黑色三角形到圆环外边的间距。若设置值小于0，则使用默认值。若设置值大于圆环半径，则使用默认值。

GaugeConfiguration12+对象说明

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

参数名	类型	说明
value	number	当前数据值。
min	number	当前数据段最小值。
max	number	当前数据段最大值。

ImageImage为图片组件，常用于在应用中显示图片。

Image支持加载PixelMap、ResourceStr和DrawableDescriptor类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式。

组件	参数名	参数类型	必填	参数描述
Image	src	PixelMap | ResourceStr| DrawableDescriptor	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。1. PixelMap格式为像素图，常用于图片编辑的场景。2. ResourceStr包含Resource和string格式。string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image(“common/test.jpg”)，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。- 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file://路径前缀的字符串，应用沙箱URI：file:///。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。说明：- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 PixelMap类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。- 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。
Image	src	PixelMap | ResourceStr| DrawableDescriptor	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。1. PixelMap格式为像素图，常用于图片编辑的场景。2. ResourceStr包含Resource和string格式。string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image(“common/test.jpg”)，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。- 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file://路径前缀的字符串，应用沙箱URI：file:///。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。说明：- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 PixelMap类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。- 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。
	imageAIOptions	ImageAIOptions	是	给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。

属性

组件	参数名	类型	必填	说明
alt	value	string | Resource | PixelMap12+	是	加载时显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型）,支持PixelMap类型图片，不支持网络图片。默认值：null
objectFit	value	ImageFit	是	图片的填充效果。默认值：ImageFit.Cover
objectRepeat	value	ImageRepeat	是	图片的重复样式。默认值：ImageRepeat.NoRepeat
interpolation	value	ImageInterpolation	是	图片的插值效果。默认值：ImageInterpolation.Low
renderMode	value	ImageRenderMode	是	图片的渲染模式为原色或黑白。默认值：ImageRenderMode.Original
sourceSize	value	{width: number,height: number}	是	图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。单位：vp
matchTextDirection	value	boolean	是	图片是否跟随系统语言方向。默认值：false
fitOriginalSize	value	boolean	是	图片的显示尺寸是否跟随图源尺寸默认值：false
fillColor	value	ResourceColor	是	设置填充颜色。
autoResize	alue	boolean	是	图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会降采样解码到200x200的尺寸，大幅度节省图片占用的内存。默认值：false
syncLoad	value	boolean	是	是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。默认值：false
copyOption	value	CopyOptions	是	图片是否可复制。默认值：CopyOptions.None
colorFilter	value	ColorFilter | DrawingColorFilter12+	是	1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。当矩阵对角线值为1，其余值为0时，保持图片原有色彩。**计算规则：**如果输入的滤镜矩阵为：像素点为[R, G, B, A]则过滤后的颜色为 [R’, G’, B’, A’]2. 从API Version12开始支持@ohos.graphics.drawing的ColorFilter类型作为入参。**说明：**API Version 11及之前，svg类型图源不支持该属性。从API version 12开始，该接口中的DrawingColorfilter类型支持在元服务中使用。其中，svg类型的图源需具有stroke属性。
draggable	value	boolean	是	组件默认拖拽效果，设置为true时，组件可拖拽。API version 9及之前，默认值为false。API version 10及之后，默认值为true。
enableAnalyzer	enable	boolean	是	组件支持AI分析，设置为true时，组件可进行AI分析。默认值：false
resizable	value	ResizableOptions	是	图像拉伸时可调整大小的图像选项。
privacySensitive	supported	boolean	是	是否支持卡片敏感隐私信息。默认值为false，当设置为true时，隐私模式下图片将显示为半透明底板样式。**说明：**设置null则不敏感。进入隐私模式需要卡片框架支持。
dynamicRangeMode	value	DynamicRangeMode	是	图像显示的动态范围。默认值：dynamicRangeMode.Standard

ImageInterpolation

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

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

名称	描述
None	最近邻插值。
High	Cubic插值，插值质量最高，可能会影响图片渲染的速度。
Medium	MipMap插值。
Low	双线性插值。

ImageRenderMode

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

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

名称	描述
Original	原色渲染模式。
Template	黑白渲染模式。

ResizableOptions11+

图像拉伸时可调整大小的图像选项。

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

参数名	类型	说明
slice	EdgeWidths	边框宽度类型，用于描述组件边框不同方向的宽度。**说明：**只有当bottom和right同时大于0时，该属性生效。

EdgeWidths参数说明

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

名称	类型	必填	说明
top	Length	否	图片顶部拉伸时保持不变距离。默认值：0单位：vp
right	Length	否	图片右部拉伸时保持不变距离。默认值：0单位：vp
bottom	Length	否	图片底部拉伸时保持不变距离。默认值：0单位：vp
left	Length	否	图片左部拉伸时保持不变距离。默认值：0单位：vp

DynamicRangeMode12+

期望展示的图像动态范围。

名称	描述
High	不受限动态范围，最大限度进行图片提亮。
Constraint	受限动态范围，受限进行图片提亮。
Standard	标准动态范围，不进行图片提亮。

事件

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

onComplete

onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void)

图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

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

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

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

参数：

参数名	类型	必填	说明
width	number	是	图片的宽。单位：像素
height	number	是	图片的高。单位：像素
componentWidth	number	是	组件的宽。单位：像素
componentHeight	number	是	组件的高。单位：像素
loadingStatus	number	是	图片加载成功的状态值。**说明：**返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。
contentWidth10+	number	是	图片实际绘制的宽度。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentHeight10+	number	是	图片实际绘制的高度。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentOffsetX10+	number	是	实际绘制内容相对于组件自身的x轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentOffsetY10+	number	是	实际绘制内容相对于组件自身的y轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。

onError9+

onError(callback: ImageErrorCallback)

图片加载异常时触发该回调。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

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

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

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

参数：

参数名	类型	必填	说明
callback	ImageErrorCallback	是	图片加载异常时触发的回调。

onFinish

onFinish(event: () => void)

当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。

仅支持svg格式的图片。当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

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

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

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

ImageErrorCallback9+

type ImageErrorCallback = (error: ImageError) => void

图片加载异常时触发的回调。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

参数名	类型	必填	说明
error	ImageError	是	图片加载异常时触发回调的返回对象。

ImageError9+

图片加载异常时触发回调的返回对象。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

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

参数名	类型	必填	说明
componentWidth	number	是	组件的宽。单位：像素
componentHeight	number	是	组件的高。单位：像素
message	string	是	报错信息。

ImageAnimator提供帧动画组件来实现逐帧播放图片的能力，可以配置需要播放的图片列表，每张图片可以配置时长。

参数：

组件	参数名	类型	必填	说明
images	value	Array<ImageFrameInfo>	是	设置图片帧信息集合。每一帧的帧信息(ImageFrameInfo)包含图片路径、图片大小、图片位置和图片播放时长信息，详见ImageFrameInfo属性说明。默认值：[]
state	value	AnimationStatusvalue	是AnimationStatus	默认为初始状态，用于控制播放状态。默认值：AnimationStatus.Initial是
duration	value	number	是	播放时长。value为0时，不播放图片。value的改变只会在下一次循环开始时生效。单位：毫秒默认值：1000ms
reverse	value	boolean	是	播放方向。false表示从第1张图片播放到最后1张图片，true表示从最后1张图片播放到第1张图片。默认值：false
fixedSize	value	boolean	是	设置图片大小是否固定为组件大小。 true表示图片大小与组件大小一致，此时设置图片的width 、height 、top 和left属性是无效的。false表示每一张图片的width 、height 、top和left属性都要单独设置。默认值：true
preDecode	value	number	是	预解码的图片数量。例如该值设为2，则播放当前页时会提前加载后面两张图片至缓存以提升性能。默认值：0
fillMode	value	FillMode	是	当前播放方向下，动画开始前和结束后的状态。默认值：FillMode.Forwards
iterations	value	number	是	默认播放一次，设置为-1时表示无限次播放。默认值：1

ImageFrameInfo对象说明

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

参数名称	参数类型	必填	参数描述
src	string | Resource9+ | PixelMap12+	是	图片路径，图片格式为svg，png和jpg，从API Version9开始支持Resource类型的路径，从API version 12开始支持PixelMap类型。卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
width	number | string	否	图片宽度。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用
height	number | string	否	图片高度。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用
top	number | string	否	图片相对于组件左上角的纵向坐标。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用
left	number | string	否	图片相对于组件左上角的横向坐标。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用
duration	number	否	每一帧图片的播放时长，单位毫秒。默认值：0

事件

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

onStart

onStart(event: () => void)

状态回调，动画开始播放时触发。

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

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

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

onPause

onPause(event: () => void)

状态回调，动画暂停播放时触发。

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

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

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

onRepeat

onRepeat(event: () => void)

状态回调，动画重复播放时触发。

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

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

onCancel

onCancel(event: () => void)

状态回调，动画返回最初状态时触发。

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

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

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

onFinish

onFinish(event: () => void)

状态回调，动画播放完成时或者停止播放时触发。

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

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

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

ImageSpanText、ContainerSpan组件的子组件，用于显示行内图片

接口

ImageSpan(value: ResourceStr | PixelMap)

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

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

参数：

参数名	参数类型	必填	参数描述
value	ResourceStr | PixelMap	是	图片的数据源，支持本地图片和网络图片。当使用相对路径引用图片资源时，例如ImageSpan(“common/test.jpg”)，不支持跨包/跨模块调用该ImageSpan组件，建议使用$r方式来管理需全局使用的图片资源。- 支持的图片格式包括png、jpg、bmp、svg、gif和heif。- 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file:///data/storage路径前缀的字符串，用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。

参数：

组件	参数名	类型	必填	说明
alt12+	value	PixelMap	是	加载时显示的占位图，支持PixelMap类型。默认值：null
verticalAlign	value	ImageSpanAlignment	是	图片基于文本的对齐方式。默认值：ImageSpanAlignment.BOTTOM
objectFit	value	ImageFit	是	图片的缩放类型。默认值：ImageFit.Cover

ImageSpanAlignment

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

名称	描述
TOP	图片上边沿与行上边沿对齐。
CENTER	图片中间与行中间对齐。
BOTTOM	图片下边沿与行下边沿对齐。
BASELINE	图片下边沿与文本BaseLine对齐。

事件

通用事件仅支持点击事件。还支持以下事件：

onComplete12+

onComplete(callback: ImageCompleteCallback)

图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。

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

参数：

参数名	类型	必填	说明
callback	ImageCompleteCallback	是	图片数据加载成功和解码成功时触发的回调。

onError12+

onError(callback: ImageErrorCallback)

图片加载异常时触发该回调。

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

参数：

参数名	类型	必填	说明
callback	ImageErrorCallback	是	图片加载异常时触发的回调。

ImageCompleteCallback12+

type ImageCompleteCallback = (result: ImageLoadResult) => void

图片加载异常时触发的回调。

参数名	类型	必填	说明
result	ImageLoadResult	是	图片数据加载成功和解码成功触发回调时返回的对象。

ImageLoadResult12+

图片数据加载成功和解码成功触发回调时返回的对象。

参数名	类型	必填	说明
width	number	是	图片的宽。单位：像素
height	number	是	图片的高。单位：像素
componentWidth	number	是	组件的宽。单位：像素
componentHeight	number	是	组件的高。单位：像素
loadingStatus	number	是	图片加载成功的状态值。**说明：**返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。
contentWidth	number	是	图片实际绘制的宽度。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentHeight	number	是	图片实际绘制的高度。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentOffsetX	number	是	实际绘制内容相对于组件自身的x轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。
contentOffsetY	number	是	实际绘制内容相对于组件自身的y轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。

LoadingProgress用于显示加载动效的组件。

创建加载进展组件。

组件	参数名	类型	必填	说明
color	value	ResourceColor	是	加载进度条的前景色。默认值：API version 10及以下：‘#99666666’API version 11及以上：’#ff666666’
enableLoading	value	boolean	是	LoadingProgress动画是否显示。默认值：true
contentModifier	modifier	ContentModifier	是	在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

支持通用事件。

LoadingProgressConfiguration12+对象说明

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

参数名	类型	默认值	说明
enableloading	boolean	true	LoadingProgress动画是否显示。默认值：true

Marquee跑马灯组件，用于滚动展示一段单行文本

仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。

接口

Marquee(value: { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string })

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

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

参数：

参数名	参数类型	必填	参数描述
value	{ start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string }	是	配置跑马灯组件的参数。- start：控制跑马灯是否进入播放状态。**说明：有限的滚动次数播放完毕后，不可以通过改变start重置滚动次数重新开始播放。- step：滚动动画文本滚动步长，当step大于Marquee的文本宽度时，取默认值。默认值：6，单位vp- loop：设置重复滚动的次数，小于等于零时无限循环。默认值：-1说明：**ArkTS卡片上该参数设置任意值都仅在可见时滚动一次。- fromStart：设置文本从头开始滚动或反向滚动。默认值：true- src：需要滚动的文本。

属性

参数：

组件	参数名	类型	必填	说明
allowScale	value	boolean	是	是否允许文本缩放。默认值：false
marqueeUpdateStrategy	value	MarqueeUpdateStrategy	是	跑马灯组件属性更新后，跑马灯的滚动策略。默认值: MarqueeUpdateStrategy.DEFAULT

事件

onStart

onStart(event: () => void)

开始滚动时触发回调。

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

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

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

onBounce

onBounce(event: () => void)

完成一次滚动时触发，若循环次数不为1，则该事件会多次触发。

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

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

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

onFinish

onFinish(event: () => void)

滚动全部循环次数完成时触发回调。

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

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

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

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

subMenuExpandingMode12+枚举说明

Menu子菜单展开样式枚举。

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

属性

组件	参数名	类型	必填	说明
fontSize	value	Length	是	Menu中所有文本的尺寸，Length为number类型时，使用fp单位。
font	value	Font	是	Menu中所有文本的尺寸。
fontColor	value	ResourceColor	是	Menu中所有文本的颜色。
radius	value	Dimension | BorderRadiuses	是	Menu边框圆角半径。默认值跟随主题。从API version 12开始，当水平方向两个圆角半径之和的最大值大于菜单宽度，或垂直方向两个圆角半径之和的最大值大于菜单高度时，菜单四个圆角均采用菜单默认圆角半径值
width	value	Length	是	Menu边框宽度。
menuItemDivider	options	DividerStyleOptions | undefined	是	设置menuItem分割线样式。-strokeWidth:分割线的线宽。-color：分割线的颜色。-startMargin：分割线与menuItem侧边起端的距离。-endMargin：分割线与menuItem侧边
menuItemGroupDivider	options	DividerStyleOptions | undefined	是	设置menuItemGroup顶部和底部分割线样式。-strokeWidth:分割线的线宽, 默认值是1px。-color：分割线的颜色, 默认值是 #33000000。-startMargin：分割线与menuItemGroup侧边起端的距离, 默认值是16。-endMargin：分割线与menuItemGroup侧边结束端的距离, 默认值是16。
subMenuExpandingMode	mode	SubMenuExpandingMode	是	Menu子菜单展开样式。

示例1

@Entry
@Component
struct Index {
  @State select: boolean = true
  private iconStr: ResourceStr = $r("app.media.view_list_filled")
  private iconStr2: ResourceStr = $r("app.media.arrow_right_filled")

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({ content: "复制", labelInfo: "Ctrl+C" })
      MenuItem({ content: "粘贴", labelInfo: "Ctrl+V" })
    }
  }

  @Builder
  MyMenu(){
    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;

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({ content: "复制", labelInfo: "Ctrl+C" })
      MenuItem({ content: "粘贴", labelInfo: "Ctrl+V" })
    }
  }

  @Builder
  MyMenu() {
    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菜单项。

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

接口

MenuItem(value?: MenuItemOptions| CustomBuilder)

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

参数：

参数	类型	必填	参数描述
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	value	boolean	是	菜单项是否选中。默认值：false
selectIcon	value	boolean | ResourceStr10+| SymbolGlyphModifier12+	是	菜单项被选中时，是否显示被选中的图标。默认值：falsetrue: 菜单项被选中时，显示默认的对勾图标false: 即使菜单项被选中也不显示图标ResourceStr: 菜单项被选中时，显示指定的图标SymbolGlyphModifier: 菜单项被选中时，显示指定的HMSymbol图标。
contentFont	value	Font	是	菜单项中内容信息的字体样式。
contentFontColor	value	ResourceColor	是	菜单项中内容信息的字体颜色。
labelFont	value	Font	是	菜单项中标签信息的字体样式。
labelFontColor	value	ResourceColor	是	菜单项中标签信息的字体颜色。

事件

onChange

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

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

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

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

参数：

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

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

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

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

子组件

包含MenuItem子组件。

接口

MenuItemGroup(value?: MenuItemGroupOptions)

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

参数：

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

MenuItemGroupOptions类型说明

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

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

Navigation组件是路由导航的根视图容器

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

接口

Navigation

Navigation()

Navigation10+

Navigation(pathInfos: NavPathStack)

绑定路由栈到Navigation组件。

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

参数：

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

属性

组件	参数名	类型	必填	说明
title	value	ResourceStr10+ | CustomBuilder | NavigationCommonTitle9+ | NavigationCustomTitle9+	是	页面标题，使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行（2行）最后…截断。如果设置副标题，先缩小最后…截断。
	options	NavigationTitleOptions11+	否	标题栏选项。
subTitle	value	string	是	页面副标题。
menus	value	Array<NavigationMenuItem> | CustomBuilder	是	页面右上角菜单。
titleMode	value	NavigationTitleMode	是	页面标题栏显示模式。默认值：NavigationTitleMode.Free
toolBar	value	object | CustomBuilder	是	工具栏内容。
toolbarConfiguration	value	Array<ToolbarItem> | CustomBuilder	是	工具栏内容，使用Array<ToolbarItem>写法设置的工具栏有如下特性：工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后…截断。竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。横屏下必须配合menus属性的Array<NavigationMenuItem>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。使用CustomBuilder写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。
	options	NavigationToolbarOptions11+	否	工具栏选项。
hideToolBar	value	boolean	是	是否隐藏工具栏。默认值：falsetrue: 隐藏工具栏。false: 显示工具栏。
hideTitleBar	value	boolean	是	是否隐藏标题栏。默认值：falsetrue: 隐藏标题栏。false: 显示标题栏。
hideBackButton	value	boolean	是	是否隐藏标题栏中的返回键。默认值：falsetrue: 隐藏返回键。false: 显示返回键。
navBarWidth	value	Length	是	导航栏宽度。默认值：240单位：vpundefined：行为不做处理，导航栏宽度与默认值保持一致。
navBarPosition	value	NavBarPosition	是	导航栏位置。默认值：NavBarPosition.Start
mode	value	NavigationMode	是	导航栏的显示模式。默认值：NavigationMode.Auto自适应：基于组件宽度自适应单栏和双栏。
backButtonIcon	value	string | PixelMap | Resource | SymbolGlyphModifier12+	是	标题栏中返回键图标。
hideNavBar	value	boolean	是	是否隐藏导航栏。默认值：false
navDestination	builder	(name: string, param: unknown) => void	是	创建NavDestination组件。
navBarWidthRange	value	[Dimension, Dimension]	是	导航栏最小和最大宽度。默认值：最小默认值 240，最大默认值为组件宽度的40% ，且不大于 432，如果只设置一个值，则未设置的值按照默认值计算。单位：vp
minContentWidth	value	Dimension	是	导航栏内容区最小宽度。默认值：360单位：vpundefined：行为不做处理，导航栏内容区最小宽度与默认值保持一致。Auto模式断点计算：默认600vp，minNavBarWidth(240vp) + minContentWidth (360vp)
ignoreLayoutSafeArea	types	Array <LayoutSafeAreaType>	否	配置扩展安全区域的类型。默认值:[LayoutSafeAreaType.SYSTEM]
	edges	Array <LayoutSafeAreaEdge>	否	配置扩展安全区域的方向。默认值:[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。
systemBarStyle	style	Optional<SystemBarStyle>	是	系统状态栏样式。

object类型说明：

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

事件

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页面信息入栈，传递的数据为param
            this.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页面信息入栈，传递的数据为param
            this.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.PUSH

  static 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 = 1
  count: 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.ets

class 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;

  @Builder
  PageBuilder(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(() => {
              // 可以获取父NavPathStack
              let 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
  @Builder
  export 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和当前所处的NavPathStack
      try {
        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 class
  setId(id: string) {
    this.id = id;
  }

  // new function in derived class
  getInfo(): string {
    return "this page used Derived NavPathStack, id: " + this.id
  }

  // overwrite function of NavPathStack
  pushPath(info: NavPathInfo, animated?: boolean): void {
    console.log('[derive-test] reached DerivedNavPathStack\'s pushPath');
    super.pushPath(info, animated);
  }

  // overwrite and overload function of NavPathStack
  pop(animated?: boolean | undefined): NavPathInfo | undefined
  pop(result: Object, animated?: boolean | undefined): NavPathInfo | undefined
  pop(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');
  }

  @Builder
  pageMap(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 navdestinationContext
      this.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:()=>{}
    }
  ]

  @Builder
  myRouter(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: () => {
      }
    }
  ]

  @Builder
  myRouter(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导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。

接口

NavRouter

NavRouter()

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

NavRouter10+

NavRouter(value: RouteInfo)

提供路由信息，指定点击NavRouter时，要跳转的NavDestination页面。

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

参数：

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

属性

组件	参数名	类型	必填	描述
mode	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 = false

  build() {
    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	value	string | CustomBuilder | NavigationCommonTitle | NavigationCustomTitle	是	页面标题。
	options12+	NavigationTitleOptions	否	标题栏选项。
hideTitleBar	value	boolean	是	是否隐藏标题栏。默认值：falsetrue: 隐藏标题栏。false: 显示标题栏。
mode	value	NavDestinationMode	是	NavDestination类型。默认值: NavDestinationMode.STANDARD
backButtonIcon	value	ResourceStr | PixelMap | SymbolGlyphModifier12+	是	标题栏返回键图标。
menus	value	Array<NavigationMenuItem> | CustomBuilder	是	页面右上角菜单。
ignoreLayoutSafeArea	参数名	类型	必填	说明
	types	Array <LayoutSafeAreaType>	否	配置扩展安全区域的类型。默认值:[LayoutSafeAreaType.SYSTEM]
systemBarStyle	style	Optional<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	页面自定义字段信息。

示例

NavDestination用法可参考Navigation示例。

NodeContainer基础组件，不支持尾随添加子节点。

组件接受一个NodeController的实例接口。需要NodeController组合使用。

接口

NodeContainer

NodeContainer(controller: NodeController)

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

参数：

参数名	参数类型	必填	参数描述
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组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。

子组件

无

接口

PatternLock(controller?: PatternLockController)

参数：

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

组件	参数名	类型	必填	说明
sideLength	value	Length	是	组件的宽度和高度。默认值：288vp
circleRadius	value	Length	是	宫格中圆点的半径。默认值：6vp
regularColor	value	ResourceColor	是	宫格圆点在“未选中”状态的填充颜色。默认值：‘#ff182431’
selectedColor	value	ResourceColor	是	宫格圆点在“选中”状态的填充颜色。默认值：‘#ff182431’
activeColor	value	ResourceColor	是	宫格圆点在“激活”状态的填充颜色。默认值：‘#ff182431’
pathColor	value	ResourceColor	是	连线的颜色。默认值：‘#33182431’
pathStrokeWidth	value	number | string	是	连线的宽度。默认值：12vp
autoReset	value	boolean	是	在完成密码输入后再次在组件区域按下时是否重置组件状态。为true时，完成密码输入后再次在组件区域按下时会重置组件状态（即清除之前输入的密码）；为false时，不会重置组件状态。默认值：true
activateCircleStyle	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
          }
          // 判断密码长度是否大于0
          if (this.passwords.length > 0) {
            // 判断两次输入的密码是否相同，相同则提示密码设置成功，否则提示重新输入
            if (this.passwords.toString() === input.toString()) {
              this.passwords = input
              this.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 = input
            this.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进度条组件，用于显示内容加载或操作处理等进度。

接口

Progress(options: ProgressOptions)

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

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

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

参数：

参数名	参数类型	必填	参数描述
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+

style(value: ProgressStyleOptions | CapsuleStyleOptions | RingStyleOptions | LinearStyleOptions | ScaleRingStyleOptions | EclipseStyleOptions)

设置组件的样式。

卡片能力： 从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 = 0

  build() {
    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.White


  constructor(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 = 0
  modifier = new MyProgressModifier(Color.Red)
  @State myModifier:(MyProgressModifier | undefined)  = this.modifier
  build() {
    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用于显示单个二维码的组件。

接口

QRCode(value: string)

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

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

参数：

参数名	参数类型	必填	参数描述
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单选框，提供相应的用户交互选择项

接口

Radio(options: RadioOptions)

创建单选框组件。

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

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

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

参数：

参数名	类型	必填	描述
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 = 0
  selectedColor:Color = Color.Black

  constructor(numberType: number, colorType:Color) {
    this.type = numberType
    this.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(