ArkTs组件的学习

一. AlphabetIndexer

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

参数名	类型	必填	说明
arrayValue	Array<string>	是	字母索引字符串数组，不可设置为空
selected	number	是	初始选中项索引值若超出索引值范围则取默认值0

class Lxr{tImg:ResourceStrnames:stringconstructor(tImg: ResourceStr, names: string) {this.tImg = tImg;this.names = names;}
}
class Txl{key:stringlxr:Lxr[]constructor(key: string, lxr: Lxr[]) {this.key = key;this.lxr = lxr;}}@Entry
@Component
struct ComponentPage {@State message: string = 'Hello World';build() {Column(){this.test1()}.height('100%').width('100%').backgroundColor('#ccc')}@State strs:string[]=['A','B','C']@State txls:Txl[]=[new Txl('A',[new Lxr($r('app.media.1'),'哎'),new Lxr($r('app.media.2'),'哎呀'),new Lxr($r('app.media.3'),'奥运'),new Lxr($r('app.media.1'),'阿里'),new Lxr($r('app.media.1'),'阿里巴巴'),new Lxr($r('app.media.2'),'爱吃'),new Lxr($r('app.media.3'),'爱人')]),new Txl('B',[new Lxr($r('app.media.1'),'白色的'),new Lxr($r('app.media.2'),'部分'),new Lxr($r('app.media.3'),'博大精深'),new Lxr($r('app.media.3'),'把你的'),new Lxr($r('app.media.3'),'把你的'),new Lxr($r('app.media.3'),'不会'),new Lxr($r('app.media.3'),'部门')]),new Txl('C',[new Lxr($r('app.media.3'),'测试'),new Lxr($r('app.media.3'),'测定'),new Lxr($r('app.media.3'),'测得'),new Lxr($r('app.media.3'),'侧入'),new Lxr($r('app.media.3'),'测啊'),new Lxr($r('app.media.3'),'测温'),new Lxr($r('app.media.3'),'测试'),new Lxr($r('app.media.3'),'测定'),new Lxr($r('app.media.3'),'测得'),new Lxr($r('app.media.3'),'侧入'),new Lxr($r('app.media.3'),'测啊'),new Lxr($r('app.media.3'),'测温'),new Lxr($r('app.media.3'),'测试'),new Lxr($r('app.media.3'),'测定'),new Lxr($r('app.media.3'),'测得'),new Lxr($r('app.media.3'),'侧入'),new Lxr($r('app.media.3'),'测啊'),new Lxr($r('app.media.3'),'测温'),new Lxr($r('app.media.3'),'测试'),new Lxr($r('app.media.3'),'测定'),new Lxr($r('app.media.3'),'测得'),new Lxr($r('app.media.3'),'侧入'),new Lxr($r('app.media.3'),'测完')]),]@State selectIndex:number=0@State strs2:string[]=[] // 显示具体内容@Builder tou(str:string){Text(str).width('100%').backgroundColor('gray')}@Builder test1(){Stack(){List(){ForEach(this.txls,(txl:Txl,index)=>{ListItemGroup({header:this.tou(txl.key)}){ForEach(txl.lxr,(lxr:Lxr,i)=>{ListItem(){Row(){Image(lxr.tImg).width(30).height(30).borderRadius(100)Text(lxr.names)}.width('100%').backgroundColor(i%2==0?'#abc':'#faf')}})}})}.sticky(StickyStyle.Header).onScrollIndex((first)=>{this.selectIndex=first})AlphabetIndexer({arrayValue:this.strs,selected:0}).font({size:25}).selectedFont({size:30}).itemSize(60).selected(this.selectIndex).usingPopup(true).onRequestPopupData((index:number)=>{//1.清空数组this.strs2=[]for (let i=0;i<this.txls[index].lxr.length;i++){// 添加数据this.strs2.push(this.txls[index].lxr[i].names)}return this.strs2})}.height('100%').width('100%')}

（1）属性值

属性值
参数名	类型	必填	说明
color	ResourceColor	是	文字颜色
selectedColor	ResourceColor	是	选中项文字颜色
popupColor	ResourceColor	是	提示弹窗文字颜色
selectedBackgroundColor	ResourceColor	是	选中项背景颜色
popupBackground	ResourceColor	是	提示弹窗背景色。弹窗的背景模糊材质效果会对背景色产生影响，可通过设置popupBackgroundBlurStyle属性值为NONE关闭背景模糊材质效果
usingPopup	boolean	是	是否使用提示弹窗默认值：false
selectedFont	Font	是	选中项文字样式
popupFont	Font	是	提示弹窗字体样式
font	Font	是	字母索引条默认字体样式
itemSize	string\|number	是	字母索引条字母区域大小，字母区域为正方形，即正方形边长。不支持设置为百分比
alignStyle	IndexerAlign	是	字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。默认值：IndexerAlign.End
alignStyle	offset	否	提示弹窗与索引条之间间距，大于等于0为有效值，在不设置或设置为小于0的情况下间距与popupPosition.x相同。与popupPosition同时设置时，水平方向上offset生效，竖直方向上popupPosition.y生效。
selected	number	是	选中项索引值默认值：0
popupPosition	position	是	弹出窗口相对于索引器条上边框中点的位置
popupSelectedColor	ResourceColor	是	提示弹窗非字母部分选中文字色
popupUnselectedColor	ResourceColor	是	提示弹窗非字母部分未选中文字色
popupItemFont	Font	是	提示弹窗非字母部分字体样式
popupItemBackgroundColor	ResourceColor	是	提示弹窗非字母部分背景色
autoCollapse	boolean	是	是否使用自适应折叠模式
popupItemBorderRadius	number	是	设置提示弹窗索引项背板圆角半径。
itemBorderRadius	number	是	设置索引项背板圆角半径
popupBackgroundBlurStyle	BlurStyle	是	设置提示弹窗的背景模糊材质弹窗的背景模糊材质效果会对背景色popupBackground产生影响，可通过设置属性值为NONE关闭背景模糊材质效果。
popupTitleBackground	ResourceColor	是	设置提示弹窗首个索引项背板颜色
enbleHapticFeedback	boolean	否	支持触控反馈默认值：true

IndexAlign枚举说明
名称	说明
Left	弹窗显示在索引条右侧
Right	弹窗显示在索引条左侧
START	在LTR场景下，弹框显示在索引条右侧的位置。在RTL场景下，弹框显示在索引条左侧的位置。
END	在LTR场景下，弹框显示在索引条左侧的位置。在RTL场景下，弹框显示在索引条右侧的位置。

（2）事件

参数名	类型	必填	说明
onSelect	number	是	索引条选中回调，返回值为当前选中索引。
onRequestPopupData	number	是	选中字母索引后，请求索引提示弹窗显示内容回调。
onPopupSelect	number	是	字母索引提示弹窗字符串列表选中回调。

二. Blank

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

Blank在父容器Row、Column、Flex主轴方向上未设置大小时会自动拉伸、压缩，设置了大小或容器自适应子节点大小时不会自动拉伸、压缩。

Blank设置主轴方向大小（size）与min时约束关系为max(min, size)。

Blank在父容器交叉轴上设置大小时不会撑满父容器交叉轴，交叉轴不设置大小时alignSelf默认值为ItemAlign.Stretch，会撑满容器交叉轴。

@Builder test2(){Row(){Text('左边')Blank().color('red')Text('右边')}.width('100%').backgroundColor('#abcdef')Column(){Text('上边')Blank().color('red')Text('下边')}.height(100).width('100%').backgroundColor('#abc')}

三. CalendarPicker

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

 @State selectDate:Date=new Date('2023-09-08')now:Date=new Date('2023-08-09')@Builder CalendarTest(){Text('日期文本')CalendarPicker({hintRadius:10,// 底板的圆角0-16selected:this.now // 默认选中的日期})// .edgeAlign(CalendarAlign.CENTER,{dx:10,dy:20}).textStyle({color:'red',font:{size:30,weight:900}}).onChange(val=>{this.selectDate=val})Text('选中的日期'+this.selectDate)}

（1）属性

edgeAlign：设置选择器与入口组件的对齐方式
参数名	类型	必填	说明
alignType	CalendarAlign	是	对齐方式类型默认值：CalendarAlign .END
offset	Offset	否	按照对齐类型对齐后，选择器相对入口组件的偏移量。默认值：{dx: 0, dy: 0}

CalendarAlign枚举
名称	描述
Start	设置选择器与入口组件左对齐的对齐方式
Center	设置选择器与入口组件居中对齐的对齐方式。
END	设置选择器与入口组件右对齐的对齐方式。

textStyle：入口区的文本颜色、字号、字体粗细。
参数名	类型	必填	说明
value	PickerTextStyle	是	设置入口区的文本颜色、字号、字体粗细

CalendarOptions对象说明

名称

类型

必填

说明

hintRadius

number|Resource

否

描述日期选中态底板样式。

默认值：底板样式为圆形。

selected

Date

否

设置选中项的日期。选中的日期未设置或日期格式不符合规范则为默认值。

默认值：当前系统日期。

（2）事件

onChange：选择日期时触发该事件。
参数名	类型	必填	说明
value	Date	是	选中的日期值

四. Checkbox

提供多选框组件，通常用于某选项的打开或关闭。

（1）属性

CheckboxOptions对象说明

名称

类型

必填

说明

name

string

否

用于指定多选框名称。

group

string

否

用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。

说明：

未配合使用CheckboxGroup组件时，此值无用。

indicatorBuilder

CustomBuilder

否

配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。

参数名	类型	必填	说明
select	boolean	是	多选框是否选中
selectedColor	ResourceColor	是	多选框选中状态颜色
unselectedColor	ResourceColor	是	多选框非选中状态边框颜色
mark	MarkStyle	是	设置多选框内部图标样式
shape	CheckBoxShape	是	CheckBox组件形状, 包括圆形和圆角方形。
contentModifier	ContentModifier<CheckBoxConfiguration>	是	在CheckBox组件上，定制内容区的方法。 modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

CheckBoxShape11+枚举类型说明
名称	值	说明
CIRCLE	0	圆形
ROUNDED_SQUARE	1	圆角方形

CheckBoxConfiguration对象说明

开发者需要自定义class实现ContentModifier接口。
名称	类型	只读	可选	说明
name	string	否	否	当前多选框名称。
selected	boolean	否	否	指示多选框是否被选中。如果select属性没有设置默认值是false。如果设置select属性，此值与设置select属性的值相同。
triggerChange	Callback<boolean>	否	否	触发多选框选中状态变化。

（2）事件

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

@Builder conStyleTest(){SymbolGlyph($r('sys.symbol.star_fill')).fontColor(['red'])}@Builder conStyleTest1(num:number){Text(num>99?'99+':num.toString()).fontSize(num>99?10:16)}@Builder cheakBoxTest(){Row(){Text('爱好:')Checkbox({name:'ah',group:'hobby'}).select(true).selectedColor('red').unselectedColor('blue').mark({strokeColor:'green',size:20,strokeWidth:100}).shape(CheckBoxShape.ROUNDED_SQUARE)Checkbox({name:'ah',group:'hobby',indicatorBuilder:()=>{this.conStyleTest()}})Checkbox({name:'ah',group:'hobby',indicatorBuilder:()=>{this.conStyleTest1(10)}})}Column(){Row(){Text('全选')CheckboxGroup({group:'ah'})}Row(){Checkbox({name:'c',group:'ah'})Text('唱')Checkbox({name:'c',group:'ah'})Text('跳')Checkbox({name:'c',group:'ah'})Text('rap')}}}

五. ContainerSpan

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

参数名

类型

必填

说明

textBackgroundStyle

TextBackgroundStyle

是

文本背景样式。

默认值：

{

color: Color.Transparent,

radius: 0

}

attributeModiffer

AttributeModifier<ContainerSpanAttribute>

是

设置组件的动态属性。

@Builder container(){Text(){SymbolSpan($r('sys.symbol.car_below_drop_3'))ContainerSpan(){Span('文字')ImageSpan($r('app.media.1')).height(30)}.textBackgroundStyle({color:'#abc',radius:5})}.width('100%')}

六. DataPanel

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

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

DataPanelType8+枚举说明
名称	说明
Line	线性数据面板
Circle	环形数据面板

参数名

类型

必填

说明

closeEffect

boolean

是

关闭数据占比图表旋转动效和投影效果。

默认值：false

valueColoes

Array<ResourceColor | LinearGradient>

是

设置各数据段颜色

trackBackgroundColor

ResourceColor

是

底板颜色。

默认值：'#08182431'，格式为十六进制ARGB值，前俩位代表透明度。

strokeWidth

length

是

设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。

trackShadow

DataPanelShadowOptions

是

投影样式。

说明：

设置null为不开启投影。

contentModiffer

ContentModifier<DataPanelConfiguration>

是

在DataPanel组件上，定制内容区的方法。

modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

DatePanelShadowOptions

Array<ResourceColor | LinearGradient>

否

各数据段投影的颜色。

默认值：与valueColors值相同

说明：

若设置的投影颜色的个数少于数据段个数时，则显示的投影颜色的个数和设置的投影颜色个数一致。

若设置的投影颜色的个数多于数据段个数时，则显示的投影颜色的个数和数据段个数一致。

LinearGradient

ColorStop[]

是

存储渐变颜色和渐变点。

ColorStop对象说明：颜色断点类型，用于描述渐进色颜色断点。
名称	类型	必填	说明
color	ResourceColor	是	颜色值
offset	length	是	渐变色断点（0~1之间的比例值，若数据值小于0则置为0，若数据值大于1则置为1）。说明：若传入字符串类型且内容为数字，则转换为对应的数值。例如'10vp'转换为10，'10%'转换为0.1。

DataPanelConfiguration1对象说明

开发者需要自定义class实现ContentModifier接口。
名称	类型	必填	说明
values	number[]	是	当前DataPanel的数据值，最大长度为9。
maxValue	number	是	DataPanel显示的最大值。默认值：100。

@State ages:number[]=[18,19,18,19,27,40,30,10,20]@Builder DatePanelTest(){DataPanel({values:this.ages,max:300,type:DataPanelType.Circle})// .width(200).closeEffect(false).valueColors([Color.Black,Color.Blue,Color.Brown,Color.Gray,Color.Green,Color.Orange,Color.Pink]).trackBackgroundColor('#03ff1f').strokeWidth(50)DataPanel({values:this.ages,max:300,type:DataPanelType.Line})}

七. DatePicker

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

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

（2）异常情形说明:

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

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

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

（3）属性

参数名	类型	必填	说明
lunar	boolean	是	日期是否显示农历。 - true：展示农历。 - false：不展示农历。默认值：false
disappearTextStyle	PickerTextStyle	是	所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。
textStyle	PickerTextStyle	是	所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。
selectedTextStyle	PickerTextStyle	是	选中项的文本颜色、字号、字体粗细。

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

（4）事件

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

DatePickerResult对象说明
名称	类型	只读	可选	说明
year	number	否	否	选中日期的年
month	number	否	否	选中日期的月(0~11)，0表示1月，11表示12月。
day	number	否	否	选中日期的日。

@Builder datePickerTest(){DatePicker({start:new Date('2020-01-01'),end:new Date(),selected:new Date()}).lunar(true).disappearTextStyle({color:'red',font:{size:16,weight:700}}).textStyle({color:'green',font:{size:20,weight:700}}).selectedTextStyle({color:Color.Pink,font:{size:30,weight:700}})}

八. Divider

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

（1）属性

参数名	类型	必填	说明
vertical	boolean	是	使用水平分割线还是垂直分割线。 false：水平分割线；true：垂直分割线。默认值：false
color	ResourceColor	是	分割线颜色。
storkWidth	number\|string	是	分割线宽度。默认值：1px 单位：vp 说明：分割线的宽度不支持百分比设置。优先级低于通用属性height，超过通用属性设置大小时，按照通用属性进行裁切。部分设备硬件中存在1像素取整后分割线不显示问题，建议使用2像素。
lineCap	LineCapStyle	是	分割线的端点样式。默认值：LineCapStyle.Butt

 Divider().width(100).height(100).vertical(true).color('red').strokeWidth(10).lineCap(LineCapStyle.Square)

九.Gauge

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

（1）接口

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支持负数。

（2）属性

参数名	类型	必填	说明
value	number	是	量规图的数据值，可用于动态修改量规图的数据值。默认值：0
angle	number	是	起始角度位置，时钟0点为0度，顺时针方向为正角度。默认值：0
engAngle	number	是	终止角度位置，时钟0点为0度，顺时针方向为正角度。默认值：360
colors	ResourceColor\| LinearGradient\| Array<[ResourceColor \| LinearGradient, number]>	是	量规图的颜色，支持分段颜色设置
strokeWidth	Length	是	环形量规图的环形厚度。默认值：4 单位：vp 说明：设置小于0的值时，按默认值显示。不支持百分比。
description	CustomBuilder	是	说明内容。说明： @Builder中的内容由开发者自定义，建议使用文本或者图片。若自定义部分的宽高为百分比形式，则基准范围为圆环直径的44.4%25.4%的矩形（图片为28.6%28.6%），距离圆环底部0vp，左右居中。
trackShadow	GaugeShadowOptions	是	阴影样式。说明：阴影颜色与圆环颜色一致。设置null为不开启投影。
indicator	GaugeShadowOptions	是	指针样式。说明：设置null则不显示指针。
privacySensitive	[Optional<boolean>]	是	设置隐私敏感，隐私模式下Gauge指针指向0位置，最大值最小值文本将被遮罩，量程显示灰色或者底色。说明：设置null则不敏感。需要卡片框架支持。
contentModiffer	ContentModifier<GaugeConfiguration>	是	在Gauge组件上，定制内容区的方法。 modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

GaugeIndicatorOptions对象说明
名称	类型	必填	说明
icon	ResourceStr	否	图标资源路径。说明：不配置则使用默认的三角形样式指针。支持使用svg格式的图标，若使用其他格式，则使用默认的三角形样式指针。
space	Dimension	否	指针距离圆环外边的间距。(不支持百分比)

GaugeConfiguration对象说明
名称	类型	必填	说明
value	number	是	当前数据值
min	number	是	当前数据段最小值
max	number	是	当前数据段最大值

@Builder
function cuss(arrs_0:GaugeConfiguration){Column(){Text(arrs_0.value+'%').textAlign(TextAlign.Center).fontSize(20)Gauge({value:arrs_0.value,min:arrs_0.min,max:arrs_0.max})}.width('100%')}class myTest implements ContentModifier<GaugeConfiguration>{value:numbermax:numbermin:numberconstructor(value: number, max: number, min: number) {this.value = valuethis.max = maxthis.min = min}applyContent(): WrappedBuilder<[GaugeConfiguration]> {return wrapBuilder(cuss)}}@Entry
@Component
struct Component2Page {@State message: string = 'Hello World';build() {Column(){// this.container()// this.DatePanelTest()// this.datePickerTest()this.gaugeTest()// this.imageTest()// this.loadTest()// this.marqueeTest()}.height('100%').width('100%')}@Builder datePickerTest(){DatePicker({start:new Date('2020-01-01'),end:new Date(),selected:new Date()}).lunar(true).disappearTextStyle({color:'red',font:{size:16,weight:700}}).textStyle({color:'green',font:{size:20,weight:700}}).selectedTextStyle({color:Color.Pink,font:{size:30,weight:700}})Divider().width(100).height(100).vertical(true).color('red').strokeWidth(10).lineCap(LineCapStyle.Square)}@State num:number=50lColor:LinearGradient=new LinearGradient([{color:'red',offset:0},{color:'blue',offset:1}])@Builder cus(num:number){Row(){Text('0'+'%').textAlign(TextAlign.Center).fontSize(20)Text('50'+'%').textAlign(TextAlign.Center).fontSize(20)Text('100'+'%').textAlign(TextAlign.Center).fontSize(20)}.width('100%')}@Builder gaugeTest(){Gauge({value:this.num,max:100,min:0}){Text(this.num+'%').textAlign(TextAlign.Center).fontSize(30)}.value(this.num).startAngle(270) //开始的角度.endAngle(90) // 结束的角度.colors(this.lColor).strokeWidth(20).description(this.cus(this.num)).trackShadow({radius:50,offsetX:10,offsetY:20}).indicator({icon:$r('sys.symbol.paperplane'),space:5})Gauge({value:this.num,max:100,min:0}).contentModifier(new myTest(this.num,100,0))Button('增加').onClick(()=>{this.num+=10})Button('减少').onClick(()=>{this.num-=10})}}

十. ImageAnimator

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

(1) 属性

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

ImageFrameInfo对象说明
名称	类型	必填	说明
src	string \| Resource\| PixelMap	是	图片路径，图片格式为jpg、jpeg、svg、png、bmp、webp、ico和heif，从API Version9开始支持Resource类型的路径，从API version 12开始支持PixelMap类型。
width	number\|string	否	图片宽度。默认值：0
height	number\|string	否	图片高度。默认值：0
Top	number\|string	否	图片相对于组件左上角的纵向坐标。默认值：0
left	number\|string	否	图片相对于组件左上角的横向坐标。默认值：0
duration	number	否	每一帧图片的播放时长，单位毫秒。

（2）事件

事件名	说明
onStart	状态回调，动画开始播放时触发。
onPause	状态回调，动画暂停播放时触发。
onRepeat	状态回调，动画重复播放时触发。
onCancel	状态回调，动画返回最初状态时触发。
onFinish	状态回调，动画播放完成时或者停止播放时触发。

@State state:AnimationStatus=AnimationStatus.Initial@Builder imageTest(){ImageAnimator().images([{src:$r('app.media.1'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.2'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.3'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.1'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.2'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.3'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.1'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.2'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.3'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.1'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.2'),width:200,height:200,duration:1000,left:60,top:20},{src:$r('app.media.3'),width:200,height:200,duration:1000,left:60,top:20}]).width('100%').state(this.state) //是否开启播放.reverse(true) //播放的方向.fixedSize(false).fillMode(FillMode.Both).iterations(1) // 播放的次数.onStart(()=>{console.log('开始了');}).onPause(()=>{console.log('暂停了');}).onRepeat(()=>{console.log('重复播放')}).onCancel(()=>{console.log('返回最初状态')}).onFinish(()=>{console.log('播放完成')})Button('初始').onClick(()=>{this.state=AnimationStatus.Initial})Button('开始').onClick(()=>{this.state=AnimationStatus.Running})Button('暂停').onClick(()=>{this.state=AnimationStatus.Paused})Button('停止').onClick(()=>{this.state=AnimationStatus.Stopped})}

十一. LoadingProgress

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

（1）属性

参数名	类型	必填	说明
color	ResourceColor	是	加载进度条的前景色
enableLoading	boolean	是	LoadingProgress动画是否显示。默认值：true
contentModdifier	ContentModifier<LoadingProgressConfiguration>	是	在LoadingProgress组件上，定制内容区的方法。 modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

@Builder loadTest(){LoadingProgress().color('red').width(100).enableLoading(true) // 是否开启动画显示Text('donghua ')}

十二. Marquee

跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。

（1）接口

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

参数名	类型	必填	说明
value	start：boolean	是	start：控制跑马灯是否进入播放状态。
value	step?:number	是	step：滚动动画文本滚动步长，当step大于Marquee的文本宽度时，取默认值。
value	loop?:number	是	loop：设置重复滚动的次数，小于等于零时无限循环。默认值：-1
value	fromStart?:boolean	是	fromStart：设置文本从头开始滚动或反向滚动。默认值：true
value	src:string	是	src：需要滚动的文本。

（2）属性

参数名	类型	必填	说明
fontColor	ResourceColor	是	字体颜色
fontSize	Length	是	字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。
fontWeight	number \| FontWeight \| string	是	文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式
fontFamily	string\|Resource	是	字体列表。默认字体'HarmonyOS Sans'。
allowScale	boolean	是	是否允许文本缩放。默认值：false 说明：仅当fontSize为fp单位时生效。
marqueeUpdateStrategy	MarqueeUpdateStrategy	是	跑马灯组件属性更新后，跑马灯的滚动策略。默认值: MarqueeUpdateStrategy.DEFAULT

（3）事件

参数	说明
onStart	当滚动的文本内容变化或者开始滚动时触发回调
onBounce	完成一次滚动时触发，若循环次数不为1，则该事件会多次触发。
onFinish	滚动全部循环次数完成时触发回调。

@Builder marqueeTest(){Marquee({start:true,step:6,loop:-1,fromStart:true,src:'这是滚动的文字不得不哈睡觉哦到时间到死u都i饿啊的就的就哦啊司机哦啊'}).width(100).backgroundColor('#abcdef').marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)}

十三.Menu

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

Menu组件需和bindMenu或bindContextMenu方法配合使用，不支持作为普通组件单独使用。

Menu的子组件包含MenuItem、MenuItemGroup

菜单和菜单项宽度计算规则：

布局过程中，期望每个菜单项的宽度一致。若子组件设置了宽度，则以尺寸计算规则为准。

不设置宽度的情况：菜单组件会对子组件MenuItem、MenuItemGroup设置默认2栅格的宽度，若菜单项内容区比2栅格宽，则会自适应撑开。

设置宽度的情况：菜单组件会对子组件MenuItem、MenuItemGroup设置减去padding后的固定宽度。

1.Menu属性

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

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

2. MenuItem

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

（1）接口

MenuItem(value?: MenuItemOptions| CustomBuilder)

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

（2）MenuItem属性

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

（3）MenuItem事件

参数名

类型

必填

说明

onChange

boolean

是

选中状态发生变化时，触发该回调。

返回值为true时，表示已选中，为false时，表示未选中。

3. MenuItemGrop

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

子组件包含MenuItem子组件

（1）MenuItemGrop接口

MenuItemGroup(value?: MenuItemGroupOptions)

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

@Entry
@Component
struct Component3Page {@State message: string = 'Hello World';build() {Column(){}.height('100%').width('100%').bindMenu(this.menuTest())}
// 自定义图标sIcon:SymbolGlyphModifier= new SymbolGlyphModifier($r('sys.symbol.car'))eIcon:SymbolGlyphModifier= new SymbolGlyphModifier($r('sys.symbol.person_crop_circle_fill_1'))// Menu菜单组件@Builder menuTest(){Menu(){MenuItem({startIcon:$r('app.media.1'),content:'首页',endIcon:$r('app.media.2'),builder:():void=>this.subMenuTest()}).selected(true) //默认选中.selectIcon(this.sIcon).contentFont({size:16,style:FontStyle.Normal,weight:900}).contentFontColor('blue').contentFont({size:16,style:FontStyle.Normal}).labelFontColor('red')MenuItem({symbolStartIcon:this.sIcon,content:'图标选项',symbolEndIcon:this.eIcon})// 分组MenuItemGroup({header:'头',footer:'底部'}){MenuItem({symbolStartIcon:this.sIcon,content:'图标选项',symbolEndIcon:this.eIcon})MenuItem({symbolStartIcon:this.sIcon,content:'图标选项',symbolEndIcon:this.eIcon})}}.backgroundColor('#ccc').height(300).font({size:20,weight:700,style:FontStyle.Italic}).fontColor('red').radius(10).width(200).menuItemDivider({strokeWidth:LengthMetrics.vp(2),color:'red',startMargin:LengthMetrics.vp(10),endMargin:LengthMetrics.vp(10)})// .subMenuExpandingMode(SubMenuExpandingMode.STACK_EXPAND)}//菜单子菜单@Builder subMenuTest(){Menu(){MenuItem({content:'子菜单'})MenuItem({content:'子菜单'})MenuItem({content:'子菜单'})}}}

十四. Navigation

1.Navigation

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

（1）Navigation接口

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

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

（2）Navigation所有属性

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


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

NavigationCommonTitle

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

NavigationCustomTitle

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

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

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

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

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

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

参数名

类型

必填

说明

value

NavigationTitleMode

是

页面标题栏显示模式。

默认值：NavigationTitleMode.Free

NavigationTitleMode枚举说明

名称

说明

Free

当内容为满一屏的可滚动组件时，标题随着内容向上滚动而缩小（子标题的大小不变、淡出）。向下滚动内容到顶时则恢复原样。

说明：

标题随着内容滚动大小联动的动效在title设置为ResourceStr和NavigationCommonTitle时生效，设置成其余自定义节点类型时字体样式无法变化，下拉时只影响标题栏偏移。

可滚动组件不满一屏时，如果想使用联动效果，就要使用滚动组件提供的edgeEffect接口将options参数设置为true。未滚动状态，标题栏高度与Full模式一致；滚动时，标题栏的最小高度与Mini模式一致。

Mini

固定为小标题模式。

默认值：API version 12之前，只有主标题时，标题栏高度为56vp；同时有主标题和副标题时，标题栏高度为82vp。从API version 12开始，该模式下标题栏高度为56vp。

Full

固定为大标题模式。

默认值：只有主标题时，标题栏高度为112vp；同时有主标题和副标题时，标题栏高度为138vp。

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

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

参数名

类型

必填

说明

value

Array<ToolbarItem> | CustomBuilder

是

工具栏内容，使用Array<ToolbarItem>写法设置的工具栏有如下特性：

工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。

文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后...截断。

竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。横屏时，如果为Split模式，仍按照竖屏规则显示，如果为Stack模式需配合menus属性的Array<NavigationMenuItem>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。

使用CustomBuilder写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。

options

NavigationToolbarOptions1

否

工具栏选项。

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

参数名

类型

必填

说明

value

Boolean

是

是否隐藏工具栏。

默认值：false

true: 隐藏工具栏。

false: 显示工具栏。

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

参数名

类型

必填

说明

value

Boolean

是

是否隐藏标题栏。

默认值：false

true: 隐藏标题栏。

false: 显示标题栏。

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

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

参数名

类型

必填

说明

value

Boolean

是

是否隐藏标题栏中的返回键。

默认值：false

true: 隐藏返回键。

false: 显示返回键。

8.navBarWidth：设置导航栏宽度

仅在Navigation组件分栏时生效。

参数名

类型

必填

说明

value

Length

是

导航栏宽度。

默认值：240

单位：vp

undefined：行为不做处理，导航栏宽度与默认值保持一致。

9.navBarPosition：设置导航栏位置

仅在Navigation组件分栏时生效。

参数名

类型

必填

说明

value

NavBarPosition

是

导航栏位置。

默认值：NavBarPosition.Start

NavBarPosition枚举说明

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

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

支持Stack、Split与Auto模式。

参数名

类型

必填

说明

value

NavigationMode

是

导航栏的显示模式。

默认值：NavigationMode.Auto

自适应：基于组件宽度自适应单栏和双栏。

NavigationMode枚举说明

名称

说明

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)。

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

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

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

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

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

参数名

类型

必填

说明

value

boolean

是

是否隐藏导航栏。

默认值：false

13.navDestination属性：创建NavDestination组件

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

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

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

参数名

类型

必填

说明

value

[Dimension, Dimension]

是

导航栏最小和最大宽度。

默认值：最小默认值 240，最大默认值为组件宽度的40% ，且不大于 432，如果只设置一个值，则未设置的值按照默认值计算。

单位：vp

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

参数名

类型

必填

说明

value

Dimension

是

导航栏内容区最小宽度。

默认值：360

单位：vp

undefined：行为不做处理，导航栏内容区最小宽度与默认值保持一致。

Auto模式断点计算：默认600vp，minNavBarWidth(240vp) + minContentWidth (360vp)

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

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

参数名

类型

必填

说明

types

Array <LayoutSafeAreaType>

否

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

默认值:

[LayoutSafeAreaType.SYSTEM]

edges

Array <LayoutSafeAreaEdge>

否

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

默认值:

[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

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

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

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

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

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

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

（3）Navigation事件

1.onTitleModeChange

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

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

2.onNavBarStateChange

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

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

3.onNavigationModeChange

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

参数名

类型

必填

说明

mode

NavigationMode

是

NavigationMode.Split: 当前Navigation显示为双栏;

NavigationMode.Stack: 当前Navigation显示为单栏。

4.customNavContentTransition

自定义转场动画回调。

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

返回值：

类型

说明

NavigationAnimatedTransition | undefined

自定义转场动画协议。

undefined: 返回未定义，执行默认转场动效。

5.NavPathStack

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

6.pushPath

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

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

7.pushPathByName

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

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

8.pushDestination

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

参数：

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

返回值：

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

错误码：

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

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

9.pushDestinationByName

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

参数：

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

返回值：

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

错误码：

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

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

10.replacePath

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

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

11.replacePathByName

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

参数：

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

12.removeByIndexes

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

参数：

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

返回值：

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

13.removeByName

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

参数：

参数名	类型	必填	说明
name	string	是	删除的NavDestination页面的名字。

返回值：

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

14.removeByNavDestinationId

将页面栈内指定navDestinationId的NavDestination页面删除。navDestinationId可以在NavDestination的onReady回调中获取，也可以在NavDestinationInfo中获取。

参数：

参数名	类型	必填	说明
navDestinationId	string	是	删除的NavDestination页面的唯一标识符navDestinationId。

返回值：

类型	说明
boolean	返回是否成功删除该页面，true为删除成功。

15.pop

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

参数：

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

返回值：

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

16.popToName

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

参数：

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

返回值：

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

17.popToIndex

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

参数：

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

18.moveToTop

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

参数：

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

返回值：

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

19.moveIndexToTop

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

参数：

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

20.clear

清除栈中所有页面。

参数：

参数名	类型	必填	说明
animated11+	boolean	否	是否支持转场动画，默认值：true。

21.getAllPathName

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

返回值：

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

22.getParamByIndex

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

参数：

参数名	类型	必填	说明
index	number	是	NavDestination页面的位置索引。

返回值：

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

23.getParamByName

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

参数：

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。

返回值：

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

24.getIndexByName

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

参数：

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。

返回值：

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

25.size

获取栈大小。

返回值：

类型	说明
number	返回栈大小。

26.disableAnimation

参数：

参数名	类型	必填	说明
value	boolean	是	是否关闭转场动画，默认值：false。

27.getParent

获取父NavPathStack

返回值：

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

28.setInterception

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

参数：

参数名	类型	必填	说明
interception	NavigationInterception	是	设置Navigation跳转拦截对象。

29.NavPathInfo

路由页面信息。

30.constructor

constructor(name: string, param: unknown, onPop?: Callback<PopInfo>, isEntry?: boolean)

参数名	类型	必填	说明
name	string	是	NavDestination页面名称。
param	unknown	否	NavDestination页面详细参数。
onPop11+	Callback<PopInfo>	否	NavDestination页面触发pop时返回的回调。
isEntry12+	boolean	否	标记NavDestination是否为入口页面。默认值：false 标记清理时机：1、在当前navDestination页面触发一次全局back事件。2、应用退至后台。说明：入口NavDestination不响应应用内的全局back事件，直接触发应用间的全局back事件

31.PopInfo

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

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

32.NavContentInfo

跳转Destination信息

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

33.NavigationAnimatedTransition

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

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

34.NavigationTransitionProxy

自定义转场动画代理对象

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

35.finishTransition

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

36.cancelTransition

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

37.updateTransition

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

参数：

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

38.NavigationInterception

Navigation跳转拦截对象。

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

39.InterceptionShowCallback

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

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

40.InterceptionModeCallback

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

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

41.NavBar

Navigation首页名字

类型	说明
'navBar'	Navigation首页。

42.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）。元服务API：从API version 12开始，该接口支持在元服务中使用。

43.ToolbarItem

名称	类型	必填	说明
value	ResourceStr	是	工具栏单个选项的显示文本。
icon	ResourceStr	否	工具栏单个选项的图标资源路径。
action	() => void	否	当前选项被选中的事件回调。
status	ToolbarItemStatus	否	工具栏单个选项的状态。默认值：ToolbarItemStatus.NORMAL
activeIcon	ResourceStr	否	工具栏单个选项处于ACTIVE态时的图标资源路径。
symbolIcon12+	SymbolGlyphModifier	否	工具栏单个选项的symbol资源（优先级高于icon）。元服务API：从API version 12开始，该接口支持在元服务中使用。
activeSymbolIcon12+	SymbolGlyphModifier	否	工具栏单个选项处于ACTIVE态时的symbol资源（优先级高于activeIcon）。元服务API：从API version 12开始，该接口支持在元服务中使用。

ToolbarItemStatus枚举说明

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

44.NavigationOperation枚举说明

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

45.BarStyle枚举说明

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

46.NavigationTitleOptions

名称	类型	必填	说明
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<NavigationMenuItem>； 2. 没有右上角菜单，且使用非自定义标题，即标题value类型为ResourceStr或NavigationCommonTitle。默认值： LengthMetrics.resource($r('sys.float.margin_right'))。元服务API：从API version 12开始，该接口支持在元服务中使用。
mainTitleModifier13+	TextModifier	否	主标题属性修改器。有如下几点使用规则： 1. 通过Modifier设置的属性会覆盖系统默认的属性（如果Modifier设置了fontSize, maxFontSize, minFontSize任一属性，则系统设置的大小相关属性不生效，以开发者的设置为准）； 2. 不设该属性或者设置了异常值，则恢复系统默认设置； 3. Free模式下设置字体大小时，原有滑动改变标题大小的效果失效。元服务API：从API version 13开始，该接口支持在元服务中使用。
subTitleModifier13+	TextModifier	否	子标题属性修改器。有如下几点使用规则： 1. 通过Modifier设置的属性会覆盖系统默认的属性（如果Modifier设置了fontSize, maxFontSize, minFontSize任一属性，则系统设置的大小相关属性不生效，以开发者的设置为准）； 2. 不设该属性或者设置了异常值，则恢复系统默认设置。元服务API：从API version 13开始，该接口支持在元服务中使用。

47.NavigationToolbarOptions

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

48.LaunchMode枚举说明

名称	说明
STANDARD	系统默认的栈操作模式。 push操作会将指定的NavDestination入栈；replace操作会将当前栈顶NavDestination替换。
MOVE_TO_TOP_SINGLETON	从栈底向栈顶查找，如果指定的名称已经存在，则将对应的NavDestination页面移到栈顶（replace操作会将最后的栈顶替换成指定的NavDestination），否则行为和STANDARD一致。
POP_TO_SINGLETON	从栈底向栈顶查找，如果指定的名称已经存在，则将其上方的NavDestination页面全部移除（replace操作会将最后的栈顶替换成指定的NavDestination），否则行为和STANDARD一致。
NEW_INSTANCE	创建新的NavDestination实例。与STANDARD模式相比，该方法不会复用栈中同名实例。

49.NavigationOptions

名称

类型

必填

说明

launchMode

LaunchMode

否

页面栈的操作模式。

默认值：LaunchMode.STANDARD

animated

boolean

否

是否支持转场动画。

默认值：true。

2.NavRouter

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

子组件

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

子组件个数异常时：

有且仅有1个时，触发路由到NavDestination的能力失效。
有且仅有1个时，且使用NavDestination场景下，不进行路由。
大于2个时，后续的子组件不显示。
第二个子组件不为NavDestination时，触发路由功能失效。

（1）NavRouter所有属性

1.mode属性：设置指定点击NavRouter跳转到NavDestination页面时，使用的路由模式。

参数：

参数名

类型

必填

说明

mode

NavRouteMode

是

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

默认值：NavRouteMode.PUSH_WITH_RECREATE

NavRouteMode枚举类型说明

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

2.RouteInfo对象说明

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

（2）事件

onStateChange

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

参数：

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

3.NavDestination

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

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

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

（1）子组件

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

子组件个数：多个

（2）NavDestination所有属性

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

1.title

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

参数：

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

NavDestinationCommonTitle

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

NavDestinationCustomTitle

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

2.hideTitleBar

设置是否隐藏标题栏

参数：

参数名

类型

必填

说明

value

boolean

是

是否隐藏标题栏。

默认值：false

true: 隐藏标题栏。

false: 显示标题栏。

3.mode

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

参数：

参数名

类型

必填

说明

value

NavDestinationMode

是

NavDestination类型。

默认值: NavDestinationMode.STANDARD

NavDestinationMode枚举说明

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

4.backButtinIcon

设置标题栏返回键图标

参数：

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

5.Menus

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

参数：

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

6.ignoreLayoutSafeArea

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

参数名

类型

必填

说明

types

Array <LayoutSafeAreaType>

否

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

默认值:

[LayoutSafeAreaType.SYSTEM]

edges

Array <LayoutSafeAreaEdge>

否

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

默认值:

[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

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

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

7.sysTemBarStyle

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

参数：

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

说明：

1.必须配合Navigation使用，作为其Navigation目的页面的根节点时才能生效。

（3）NavDestination事件

事件名	说明
onShown	当该NavDestination页面显示时触发此回调
onHidden	当该NavDestination页面隐藏时触发此回调
onWillAppear	当该Destination挂载之前触发此回调，在该回调中允许修改页面栈，当前帧生效
onWillShow	当该Destination显示之前触发此回调
onWillHide	当该Destination隐藏之前触发此回调
onWillDisappear	当该Destination卸载之前触发的生命周期（有转场动画时，在转场动画开始之前触发）
onBackPressed	当与Navigation绑定的页面栈中存在内容时，此回调生效。当点击返回键时，触发该回调返回值为true时，表示重写返回键逻辑，返回值为false时，表示回退到上一个页面。
onReady	当NavDestination即将构建子组件之前会触发此回调

（4）NavDestination接口

1.NavDestinationContext

名称

类型

必填

说明

pathInfo

NavPathInfo

是

跳转NavDestination时指定的参数。

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

pathStack

NavPathStack

是

当前NavDestination所处的页面栈。

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

navDestinationId12+

string

否

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

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

2.getConfigInRouteMap

返回值

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

3.RouteMapConfig

名称	类型	必填	说明
name	string	是	页面名称。
pageSourceFile	string	是	页面在当前包中的路径。
data	Object	是	页面自定义字段信息。

十五. NodeContainer

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

说明：

该组件下仅支持挂载自定义节点FrameNode或者是BuilderNode中获取的根节点FrameNode。

不支持挂载查询获得的原生系统组件代理节点。

当前不支持使用动态属性设置

不支持子组件

1.NodeContainer接口

参数：

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

十六. PatternLock

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

1.接口

PatternLock(controller?: PatternLockController)

参数：

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

2.属性

参数名	类型	必填	说明
sideLength	Length	是	组件的宽度和高度
circleRadius	Length	是	设置宫格中圆点的半径。设置为0或负数时取默认值。
backgroundColor	ResourceColor	是	背景颜色
regularColor	ResourceColor	是	宫格圆点在“未选中”状态的填充颜色。
selectedColor	ResourceColor	是	宫格圆点在“选中”状态的填充颜色。
activeColor	ResourceColor	是	宫格圆点在“激活”状态的填充颜色。
pathColor	ResourceColor	是	连线的颜色。
PathStrokeWidth	number\|string	是	连线的宽度。
autoReset	boolean	是	在完成密码输入后再次在组件区域按下时是否重置组件状态。为true时，完成密码输入后再次在组件区域按下时会重置组件状态（即清除之前输入的密码）；为false时，不会重置组件状态。默认值：true
activateCircleStyle	CircleStyleOptions	是	宫格圆点在“激活”状态的背景圆环样式。

CirleStyleOptions对象

名称

类型

必填

说明

color

ResourceColor

否

背景圆环颜色。

默认值：与pathColor值相同

radius

LengthMetrics

否

背景圆环的半径。

默认值：circleRadius的11/6

enableWaveEffect

boolean

否

波浪效果开关。

默认值：true

3.事件

（1）onPatternComplete

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

参数：

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

（2）onDotConnect

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

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

1.PatternLockController

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

导入对象

let patternLockController: PatternLockController = new PatternLockController()

2.constructor

constructor()

PatternLockController的构造函数。

3.reset

reset()

重置组件状态。

4.setChallengeResult

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

名称	类型	必填	说明
result	PatternLockChallengeResult	是	图案密码状态。

PatternLockChallengeResult枚举说明

名称	说明
CORRECT	图案密码正确。
WRONG	图案密码错误。