ArkTS组件Navigation

 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)

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

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

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

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

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

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

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

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

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

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

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

（3）Navigation事件

1.onTitleModeChange

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

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

2.onNavBarStateChange

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

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

3.onNavigationModeChange

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

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

4.customNavContentTransition

自定义转场动画回调。

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

返回值：

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

5.NavPathStack

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

6.pushPath

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

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

7.pushPathByName

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

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

8.pushDestination

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

参数：

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

返回值：

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

错误码：

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

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

9.pushDestinationByName

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

参数：

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

返回值：

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

错误码：

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

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

10.replacePath

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

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

11.replacePathByName

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

参数：

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

12.removeByIndexes

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

参数：

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

返回值：

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

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. 有且仅有1个时，触发路由到NavDestination的能力失效。
2. 有且仅有1个时，且使用NavDestination场景下，不进行路由。
3. 大于2个时，后续的子组件不显示。
4. 第二个子组件不为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之后生效的条件为：

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

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

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	图案密码错误。

1. @State onPattern:number[]=[]

2. @State pwdMsg:string='请设置密码'

3. patternLockController: PatternLockController = new PatternLockController() // 控制器

4. acs:LengthMetrics=new LengthMetrics(10)

5. @Builder PatternLockTest(){

6. Text(this.pwdMsg).fontSize(30)

7. Text(this.onPattern.toString())

8. PatternLock(this.patternLockController)

9. .sideLength('100%')

10. .circleRadius(10) // 圆点半径

11. .regularColor('#ccc') // 未选中的颜色

12. .selectedColor('red') //选中的颜色

13. .activeColor('blue') // 激活状态的颜色

14. .pathColor('blue') // 连线的颜色

15. .pathStrokeWidth(5) // 连线的宽度

16. .autoReset(true) // 自动重置

17. .activateCircleStyle({color:'green',radius:this.acs,enableWaveEffect:true})

18. .onPatternComplete((input:Array<number>)=>{ //input: 输入的数字的数组

19. // 输入完成后重置

20. this.patternLockController.reset()

21. if (input.length<5){

22. this.pwdMsg='最少连接5个'

23. return // 结束函数

24. }

25. if (this.onPattern.length==0) {

26. this.onPattern=input

27. this.pwdMsg='请确认密码'

28. }else {

29. if (this.onPattern.toString()==input.toString()) {

30. this.pwdMsg='两次密码一致'

31. this.patternLockController.setChallengeResult(PatternLockChallengeResult.CORRECT)

32. // todo 密码一致后跳转新页面

33. }else {

34. this.pwdMsg='两次密码不一致'

35. this.patternLockController.setChallengeResult(PatternLockChallengeResult.WRONG)

37. }

39. }

40. })

41. .onDotConnect((num)=>{ // num:输入的单个数字

42. console.log('选中的数字:'+num)

43. })

44. }

未设置密码样式

 

设置密码时的样式

第一次密码设置

 

两次密码设置不一致的效果

两次密码一致时的样式

 

最少连接五个

十七.Progress

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

1.Progress接口

Progress(options: ProgressOptions)

参数名	类型	必填	说明
options	ProgressOptions	是	按进度条类型不同，设置不同属性的进度条组件参数。

ProgressOptions<Type>对象说明

名称	类型	必填	说明
value	number	是	指定当前进度值。设置小于0的数值时置为0，设置大于total的数值时置为total。 默认值：0
total	number	否	指定进度总长。设置小于等于0的数值时置为100。 默认值：100
type	ProgressType	否	指定进度条类型。 默认值：ProgressType.Linear

ProgressType枚举说明

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

2.属性

（1）value

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

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

（2）color

设置进度条前景色。

参数名	类型	必填	说明
value	ResourceColor | LinearGradient10+	是	进度条前景色。

（3）style

设置组件的样式

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

1.ProgressStyleOptions：仅可设置各类型进度条的基本样式

名称	类型	必填	说明
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。 默认值：4.0vp
scaleCount	number	否	设置环形进度条总刻度数。 默认值：120
scaleWidth	Length	否	设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。 默认值：2.0vp

2.CapsuleStyleOptions：设置Capsule（胶囊样式）的样式

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

3.RingStyleOptions：设置Ring（环形无刻度样式）的样式

名称	类型	必填	说明
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置），宽度大于等于半径时，默认修改宽度至半径值的二分之一。 默认值：4.0vp
shadow	boolean	否	进度条阴影开关。 默认值：false
status	ProgressStatus	否	进度条状态，当设置为LOADING时会开启检查更新动效，此时设置进度值不生效。当从LOADING设置为PROGRESSING，检查更新动效会执行到终点再停止。 默认值： ProgressStatus.PROGRESSING

ProgressStatus枚举说明

名称	说明
LOADING	加载中。
PROGRESSING	进度更新中。

4.LinearStyleOptions：设置Linear（线性样式）的样式

名称	类型	必填	说明
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。 默认值：4.0vp
strokeRadius	PX | VP | LPX | Resource	否	设置线性进度条圆角半径。 取值范围[0, strokeWidth / 2]。默认值：strokeWidth / 2。

5.ScaleRingStyleOptions：设置ScaleRing（环形有刻度样式）的样式。

名称	类型	必填	说明
strokeWidth	Length	否	设置进度条宽度（不支持百分比设置）。 默认值：4.0vp
scaleCount	number	否	设置环形进度条总刻度数。 默认值：120
scaleWidth	Length	否	设置环形进度条刻度粗细（不支持百分比设置），刻度粗细大于进度条宽度时，为系统默认粗细。 默认值：2.0vp

（4）privacySensitive

设置隐私敏感。

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

（5）ProgressConfiguration

名称	类型	必填	说明
value	number	是	当前进度值。
total	number	是	进度总长。

（6）CommonProgressStyleOptions

进度平滑动效的开关

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

（7）ScanEffectOptions

扫光效果的开关

名称	类型	必填	说明
enableScanEffect	boolean	否	扫光效果的开关。 默认值：false

1. @State ProValue:number=30

2. @Builder ProgressTest(){

3. Scroll(){

4. Column({space:10}){

5. Progress({value:50,total:100,type:ProgressType.Linear}) // 线性样式

6. Progress({value:50,total:100,type:ProgressType.Ring}) //环形无刻度样式

7. .height(200)

8. .style({

9. strokeWidth:10,

10. shadow:true,

11. status:ProgressStatus.PROGRESSING

13. })

14. Progress({value:50,total:100,type:ProgressType.Eclipse}) //圆形样式

16. Progress({value:50,total:100,type:ProgressType.ScaleRing}) //环形有刻度样式

17. Progress({value:50,total:100,type:ProgressType.Capsule}) //胶囊型样式

18. .value(this.ProValue) // 默认值

19. // .color('blue') //进度条颜色

20. .backgroundColor('#ccc') // 进度条底色

21. .style({

22. borderColor:'red', //边框颜色

23. borderWidth:1, // 边框宽度

24. // content:`下载进度${this.ProValue}%`,

25. font:({size:14,style:FontStyle.Italic}),

26. fontColor:'white',

27. enableScanEffect:true, //扫光效果

28. showDefaultPercentage:true, //显示百分比,和content后无效

29. enableSmoothEffect:true

30. })

31. Progress({value:50,total:100,type:ProgressType.ScaleRing}) //环形有刻度样式

32. .height(300)

33. .value(this.ProValue)

34. .style({

35. strokeWidth:10,

36. scaleCount:100, //总刻数

37. scaleWidth:5, // 刻度线宽度

38. enableSmoothEffect:true //平滑进度开关

39. })

40. .onClick(()=>{

41. this.ProValue+=10

42. })

44. }

45. }

46. }

进度条效果

3. 自定义样式

1. class MyProgressModifier implements ContentModifier<ProgressConfiguration> {

2. color: Color = Color.White

5. constructor(color:Color) {

6. this.color = color

7. }

8. applyContent() : WrappedBuilder<[ProgressConfiguration]>

9. {

10. return wrapBuilder(myProgress)

11. }

12. }

13. @Builder function myProgress(config: ProgressConfiguration ) {

15. Column({space:30}) {

16. Text("当前进度：" + config.value + "/" + config.total).fontSize(20)

17. Row() {

18. Flex({ justifyContent: FlexAlign.SpaceBetween }) {

19. Path()

20. .width('20%')

21. .height('20%')

22. .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')

23. .fill(config.enabled && config.value >=1 ? (config.contentModifier as MyProgressModifier).color : Color.White)

24. .stroke(Color.Black)

25. .strokeWidth(5)

26. Path()

27. .width('20%')

28. .height('20%')

29. .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')

30. .fill(config.enabled && config.value >=2 ? (config.contentModifier as MyProgressModifier).color : Color.White)

31. .stroke(Color.Black)

32. .strokeWidth(5)

33. Path()

34. .width('20%')

35. .height('20%')

36. .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')

37. .fill(config.enabled && config.value >=3 ? (config.contentModifier as MyProgressModifier).color : Color.White)

38. .stroke(Color.Black)

39. .strokeWidth(5)

40. Path()

41. .width('20%')

42. .height('20%')

43. .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')

44. .fill(config.enabled && config.value >=4 ? (config.contentModifier as MyProgressModifier).color : Color.White)

45. .stroke(Color.Black)

46. .strokeWidth(5)

47. Path()

48. .width('20%')

49. .height('20%')

50. .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')

51. .fill(config.enabled && config.value >=5 ? (config.contentModifier as MyProgressModifier).color : Color.White)

52. .stroke(Color.Black)

53. .strokeWidth(5)

54. }.width('100%')

55. }

56. }.margin({bottom:100})

57. }

59. @Entry

60. @Component

61. struct Component4Page {

62. @State message: string = 'Hello World';

64. build() {

65. Column(){

66. this.ProgressTest2()

67. }

69. .height('100%')

70. .width('100%')

71. }

73. @State wjx:number=0

74. myModifer:MyProgressModifier=new MyProgressModifier(Color.Green)

75. @Builder ProgressTest2(){

76. Progress({value:this.wjx,total:5,type:ProgressType.Ring})

77. .contentModifier(this.myModifer)

79. Button('++').onClick(()=>{

80. if (this.wjx<5) {

81. this.wjx++

82. }

83. })

84. Button('--').onClick(()=>{

85. if (this.wjx>0) {

86. this.wjx--

87. }

88. })

89. }

93. }

无操作时样式

 

一星

十八. QRCode二维码

1.QRCode接口

QRCode(value: string)

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

2. 属性

参数名	类型	必填	说明
color	ResourceColor	是	二维码颜色
backgroundColor	ResourceColor	是	二维码背景颜色。
contentOpactiy	number|Resource	是	二维码内容颜色的不透明度。

1. @Builder QrCodeTest(){

2. QRCode('hello world!')

3. .color('green')

4. .backgroundColor('#fdf')

5. .contentOpacity(0.5)

6. }

hello word！二维码

十九. Radio

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

1. Radio接口

Radio(options: RadioOptions)：创建单选框组件。

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

RadioOptions对象说明

名称	类型	必填	说明
value	string	是	当前单选框的值。
group	string	是	当前单选框的所属群组名称，相同group的Radio只能有一个被选中。
indicatorType12+	RadioIndicatorType	否	配置单选框的选中样式。未设置时按照RadioIndicatorType.TICK进行显示。
indicatorBuilder12+	CustomBuilder	否	配置单选框的选中样式为自定义组件。自定义组件与Radio组件为中心点对齐显示。indicatorBuilder设置为undefined时，按照RadioIndicatorType.TICK进行显示。

RadioIndicatorType枚举说明

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

2.属性

参数名	类型	必填	说明
checked	boolean	是	单选框的选中状态。 默认值：false
radioStyle	RadioStyle	否	单选框选中状态和非选中状态的样式。
contentModiffer	ContentModifier<RadioConfiguration>	是	在Radio组件上，定制内容区的方法。 modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

RadioStyle对象说明

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

RadioConfiguration对象说明

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

名称	类型	只读	可选	说明
value	string	否	否	当前单选框的值。
checked	boolean	否	否	设置单选框的选中状态。 默认值：false
triggerChange	Callback<boolean>	否	否	触发单选框选中状态变化。

3. 事件

onChange

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

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

1. class MyRadio implements ContentModifier<RadioConfiguration>{

2. type: number = 0

3. selectedColor:Color = Color.Black

5. constructor(numberType: number, colorType:Color) {

6. this.type = numberType

7. this.selectedColor = colorType

8. }

9. applyContent(): WrappedBuilder<[RadioConfiguration]> {

10. return wrapBuilder(a)

11. }

12. }

13. @Builder function a(config:RadioConfiguration){

14. SymbolGlyph($r('sys.symbol.heart_fill'))

15. .fontColor(config.checked?[(config.contentModifier as MyRadio).selectedColor]:['gray'])

16. .onClick(()=>{

17. if (config.checked) {

18. config.triggerChange(false)

19. }else {

20. config.triggerChange(true)

21. }

22. })

23. }

25. @Entry

26. @Component

27. struct Component5Page {

28. @State message: string = 'Hello World';

30. build() {

31. Column(){

32. this.readioTest()

33. }

35. .height('100%')

36. .width('100%')

37. }

39. @Builder rs(){

40. Image($r('app.media.1'))

41. .borderRadius(100)

42. // SymbolGlyph($r('sys.symbol.camera_metering_spot'))

43. }

44. myRadio:MyRadio=new MyRadio(0,Color.Red)

45. @Builder readioTest(){

46. Row(){

47. Text('性别:')

48. Radio({value:'男',group:'sex',indicatorType:RadioIndicatorType.DOT})

49. .checked(true)

50. .radioStyle({

51. checkedBackgroundColor:Color.Green,

52. uncheckedBorderColor:Color.Brown,

53. indicatorColor:Color.Orange

54. })

55. Text('男')

56. Radio({value:'女',group:'sex',indicatorType:RadioIndicatorType.CUSTOM})

57. .radioStyle({

58. checkedBackgroundColor:Color.Green,

59. uncheckedBorderColor:Color.Brown,

60. indicatorColor:Color.Orange

61. })

62. Text('女')

63. Radio({value:'未知',group:'sex',indicatorType:RadioIndicatorType.CUSTOM,

64. indicatorBuilder:this.rs()

65. })

66. .radioStyle({

67. checkedBackgroundColor:Color.Green,

68. uncheckedBorderColor:Color.Brown,

69. indicatorColor:Color.Orange

70. })

71. Text('未知')

72. Radio({value:'未知',group:'sex' })

73. .contentModifier(this.myRadio)

76. }

77. .width('100%')

78. Row(){

79. Radio({value:'a',group:'a'})

80. .contentModifier(new MyRadio(1,Color.Red))

81. Radio({value:'a',group:'a'})

82. .contentModifier(new MyRadio(2,Color.Red))

83. }

84. }

85. }

二十.Rating

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

1.接口

Rating(options?: { rating: number, indicator?: boolean })

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

2. 属性

参数名	类型	必填	说明
stars	number	是	设置评分总数。 默认值：5
stepSize	number	是	操作评级的步长。 默认值：0.5 取值范围：[0.1, stars]
starStyle	{ backgroundUri: string, foregroundUri: string, secondaryUri?: string }	是	backgroundUri：未选中的星级的图片链接，可由用户自定义或使用系统默认图片。 foregroundUri：选中的星级的图片路径，可由用户自定义或使用系统默认图片。 secondaryUri：部分选中的星级的图片路径，可由用户自定义或使用系统默认图片。 说明： backgroundUri或者foregroundUri或者secondaryUri设置的图片路径错误时，图片不显示。 backgroundUri或者foregroundUri设置为undefined或者空字符串时，rating会选择加载系统默认星型图源。 secondaryUri不设置或者设置的值为undefined或者空字符串时，优先设置为backgroundUri，效果上等同于只设置了foregroundUri、backgroundUri。
contentModiffer	ContentModifier<RatingConfiguration>	是	在Rating组件上，定制内容区的方法。 modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

RatingConfiguration对象说明

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

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

3. 事件

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

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

键盘走焦规格

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

1. Rating({rating:0.5,indicator:true}) // 不可改变

2. Rating({rating:0.5,indicator:false}) // 可以改变

3. .stars(5) // 总数

4. .stepSize(0.5) // 步长

默认样式

1. Rating({rating:0.5,indicator:false})

2. .stars(5) // 总数

3. .stepSize(0.5) // 步长

4. .starStyle({

5. backgroundUri:'/img/1.jpg',

6. foregroundUri:'/img/2.jpg',

7. secondaryUri:'/img/3.jpg'

8. })

设置星级图片样式

1. class MyRating implements ContentModifier<RatingConfiguration>{

2. applyContent(): WrappedBuilder<[RatingConfiguration]> {

3. return wrapBuilder(rating)

4. }

6. }

7. @Builder function rating(config:RatingConfiguration){

8. Column(){

9. Row(){

10. SymbolGlyph(config.rating>0?$r('sys.symbol.star_fill'):$r('sys.symbol.star'))

11. .fontColor(['red'])

12. .onClick(()=>{

13. config.triggerChange(1)

14. })

15. SymbolGlyph(config.rating>1?$r('sys.symbol.star_fill'):$r('sys.symbol.star'))

16. .fontColor(['red'])

17. .onClick(()=>{

18. config.triggerChange(2)

19. })

20. SymbolGlyph(config.rating>2?$r('sys.symbol.star_fill'):$r('sys.symbol.star'))

21. .fontColor(['red'])

22. .onClick(()=>{

23. config.triggerChange(3)

24. })

25. }

26. .width('100%')

27. }

28. }

30. @Entry

31. @Component

32. struct Component5Page {

33. @State message: string = 'Hello World';

35. build() {

36. Column(){

37. // this.readioTest()

38. this.RatingTest()

39. // this.richTest()

40. }

42. .height('100%')

43. .width('100%')

44. }

46. @Builder RatingTest(){

47. Rating({rating:1,indicator:false})

48. .stars(3)

49. .stepSize(1)

50. .contentModifier(new MyRating())

51. }

52. }

自定义内容区

二十一. RichEditor

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

不包含子组件

1.RichEdiitor接口

RichEditor(value: RichEditorOptions)

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

RichEditorOptions

RichEditor初始化参数。

名称	类型	必填	说明
controller	RichEditorController	是	富文本控制器。

 RichEditor(options: RichEditorStyledStringOptions)

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

RichEditorStyledStringOptions

RichEditor初始化参数。

名称	类型	必填	说明
controller	RichEditorStyledStringController	是	富文本控制器。

2. 属性

（1）customKeyboard

customKeyboard(value: CustomBuilder, options?: KeyboardOptions)

设置自定义键盘。

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

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

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

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

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

参数名	类型	必填	说明
value	CustomBuilder	是	自定义键盘。
options	KeyboardOptions	否	设置自定义键盘是否支持避让功能。

（2）bindSelectionMenu

bindSelectionMenu(spanType: RichEditorSpanType, content: CustomBuilder, responseType: ResponseType | RichEditorResponseType,options?: SelectionMenuOptions)

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

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

RichEditorResponseType枚举

菜单的响应类型。

名称	说明
LONG_PRESS	通过长按触发菜单弹出。
RIGHT_CLICK	通过鼠标右键触发菜单弹出。
SELECT	通过鼠标选中触发菜单弹出。

（3）copyOptions

copyOptions(value: CopyOptions)

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

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

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

（4）enableDataDetector

enableDataDetector(enable: boolean)

设置是否进行文本特殊实体识别。该接口依赖设备底层应具有文本识别能力，否则设置不会生效。

当enableDataDetector设置为true，同时不设置dataDetectorConfig属性时，默认识别所有类型的实体，所识别实体的color和decoration会被更改为如下样式：

1. color: '#ff007dff'

2. decoration:{

3. type: TextDecorationType.Underline,

4. color: '#ff007dff',

5. style: TextDecorationStyle.SOLID

6. }

触摸点击和鼠标右键点击实体，会根据实体类型弹出对应的实体操作菜单，鼠标左键点击实体会直接响应菜单的第一个选项。

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

当copyOption设置为CopyOptions.None时，点击实体弹出的菜单没有选择文本和复制功能。

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

（5）dataDetectorConfig

dataDetectorConfig(config: TextDataDetectorConfig)

设置文本识别配置。

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

当有两个实体A、B重叠时，按以下规则保留实体：

1. 若A ⊂ B，则保留B，反之则保留A。

2. 当A ⊄ B且B ⊄ A时，若A.start < B.start，则保留A，反之则保留B。

参数名	类型	必填	说明
config	TextDataDetectorConfig	是	文本识别配置。

（6）enablePreviewText

enablePreviewText(enable: boolean)

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

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

 该接口在CAPI场景使用时下，默认关闭。可以在工程的module.json5中配置metadata字段控制是否启用预上屏，配置如下：

1. "metadata": [

2. {

3. "name": "can_preview_text",

4. "value": "true",

5. }

6. ]

（7）placeholder

placeholder(value: ResourceStr, style?: PlaceholderStyle)

设置无输入时的提示文本

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

（8）careColor

caretColor(value:ResourceColor)

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

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

（9）selectedBackgroundColor

selectedBackgroundColor(value: ResourceColor)

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

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

（10）editMenuOptions

editMenuOptions(editMenu:EditMenuOptions)

设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。

参数名	类型	必填	说明
editMenu	EditMenuOptions	是	扩展菜单选项。

（11）enterKeyType

enterKeyType(value:EnterKeyType)

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

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

（12）enableKeyboardOnFocus

enableKeyboardOnFocus(isEnabled: boolean)

设置RichEditor通过点击以外的方式获焦时，是否绑定输入法。

参数名	类型	必填	说明
isEnabled	boolean	是	通过点击以外的方式获焦时，是否绑定输入法。 默认值：true

（13）barState

barState(state: BarState)

设置RichEditor编辑态时滚动条的显示模式。

参数名	类型	必填	说明
value	BarState	是	输入框编辑态时滚动条的显示模式。 默认值：BarState.Auto

（14）enableHapticFeedback

enableHapticFeedback(isEnabled:boolean)

设置RichEditor是否支持触控反馈。

参数名	类型	必填	说明
isEnabled	boolean	是	是否支持触控反馈。 默认值：true，true表示开启触控反馈，false表示不开启触控反馈。 设置为true后是否生效，还取决于系统的硬件是否支持。

3.事件

除支持通用事件外，还支持OnDidChangeCallback、StyledStringChangedListener、StyledStringChangeValue和以下事件：

（1）onReady

onReady(callback:Callback<void>)

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

参数名	类型	必填	说明
callback	Callback<void>	是	订阅富文本组件初始化完成的回调。

（2）onSelect

onSelect(callback:Callback<RichEditorSelection>)

鼠标左键双击选中内容时，会触发回调；松开鼠标左键后，会再次触发回调。

手指长按选中内容时，会触发回调；松开手指后，会再次触发回调。

参数名	类型	必填	说明
callback	Callback<RichEditorSelection>	是	RichEditorSelection为选中的所有span信息。 选择时触发的回调。

（3）aboutTolMeInput

aboutToIMEInput(callback:Callback<RichEditorInsertValue, boolean>)

输入法输入内容前，触发回调。使用RichEditorStyledStringOptions构建的RichEditor组件时不支持该回调

参数名	类型	必填	说明
callback	Callback<RichEditorInsertValue, boolean>	是	RichEditorInsertValue为输入法将要输入内容信息。 true:组件执行添加内容操作。 false:组件不执行添加内容操作 输入法输入内容前的回调。

（4）onDidMEInput

onDidlMeInput(callback:Callback<TextRange>)

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

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

参数名	类型	必填	说明
callback	Callback<TextRange>	是	TextRange为输入法本次输入内容的范围。 输入法完成输入时的回调。

（5）onlMEInputComplete

onIMEInputComplete(callback:Callback<RichEditorTextSpanResult>)

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

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

参数名	类型	必填	说明
callback	Callback<RichEditorTextSpanResult>	是	RichEditorTextSpanResult为输入法完成输入后的文本Span信息。 输入法完成输入后的回调。

（6）aboutToDelete

aboutToDelete(callback:Callback<RichEditorDeleteValue, boolean>)

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

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

参数名	类型	必填	说明
callback	Callback<RichEditorDeleteValue, boolean>	是	RichEditorDeleteValue为准备删除的内容所在的文本或者图片Span信息。 true:组件执行删除操作。 false:组件不执行删除操作。 输入法删除内容前的回调。

（7）onDeleteComplete

onDeleteComplete(callback:Callback<void>)

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

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

参数名	类型	必填	说明
callback	Callback<void>	是	订阅输入法完成删除的回调。

（8）onPaste

onPaste(callback: PasteEventCallback )

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

参数名	类型	必填	说明
callback	PasteEventCallback	是	订阅完成粘贴前的回调。

（9）onSelectionChange

onSelectionChange(callback:Callback<RichEditorRange>)

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

参数名	类型	必填	说明
callback	Callback<RichEditorRange>	是	RichEditorRange为所有内容的选择区域起始和终止位置。 订阅文本选择区域发生变化或编辑状态下光标位置发生变化时触发的回调

（10）onEditingChange

onEditingChange(callback: Callback<boolean>)

组件内所有内容的编辑状态发生改变时触发该回调函数。

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

（11）onSubmit

onSubmit(callback: SubmitCallback)

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

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

（12）onWillChange

onWillChange(callback: Callback<RichEditorChangeValue, boolean>)

组件内图文变化前，触发回调。

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

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

（13）onDidChange

onDidChange(callback: OnDidChangeCallback)

图文变化后，触发回调。

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

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

（14）onCut

onCut(callback: Callback<CutEvent>)

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

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

（15）onCopy

onCopy(callback: Callback<CopyEvent>)

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

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

4. 枚举

（1）RichEditorInsertValue

插入文本信息。

名称	类型	必填	说明
insertOffset	number	是	插入的文本偏移位置。
insertValue	string	是	插入的文本内容。
previewText	string	否	插入的预上屏文本内容。

（2）RichEditorDeleteValue

删除操作的信息和被删除内容的信息。

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

（3）RichEditorDeleteDirection

删除操作的方向。

名称	说明
BACKWARD	向后删除。
FORWARD	向前删除。

（4）RichEditorTextSpanResult

文本Span信息。

名称	类型	必填	说明
spanPosition	RichEditorSpanPosition	是	Span位置。
value	string	是	文本Span内容。
textStyle	RichEditorTextStyleResult	是	文本Span样式信息。
offsetInSpan	[number, number]	是	文本Span内容里有效内容的起始和结束位置。
valueResource	Resource	否	组件SymbolSpan内容。
symbolSpanStyle	RichEditorSymbolSpanStyle	否	组件SymbolSpan样式信息。
paragraphStyle	RichEditorParagraphStyle	否	段落样式。
previewText	string	否	文本Span预上屏内容。

（5）RichEditorSpanPosition

Span位置信息。

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

（6）RichEditorSpanType

Span类型信息。

名称	值	说明
TEXT	0	Span为文字类型。
IMAGE	1	Span为图像类型。
MIXED	2	Span为图文混合类型。
BUILDER	3	Span为BuilderSpan类型。

（7）RichEditorTextStyleResult

后端返回的文本样式信息

名称	类型	必填	说明
fontColor	ResourceColor	是	文本颜色。
fontSize	number	是	字体大小，默认单位为fp。
fontStyle	FontStyle	是	字体样式。
fontWeight	number	是	字体粗细。
fontFamily	string	是	字体列表。
decoration	DecorationStyleResult	是	文本装饰线样式信息。
textShadow	Array<ShadowOptions>	否	文字阴影效果。
lineHeight	number	否	文本行高，默认单位为fp。
letterSpacing	number	否	文本字符间距，默认单位为fp。
fontFeature12+	string	否	文字特性效果。

（8）RichEditorSymbolSpanStyleResult

后端返回的SymbolSpan样式信息。

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

（9）RichEditorImageSpanResult

后端返回的图片信息。

名称	类型	必填	说明
spanPosition	RichEditorSpanPosition	是	Span位置。
valuePixelMap	PixelMap	否	图片内容。
valueResourceStr	ResourceStr	否	图片资源id。
imageStyle	RichEditorImageSpanStyleResult	是	图片样式。
offsetInSpan	[number, number]	是	Span里图片的起始和结束位置。

（10）RichEditorImageSpanStyleResult

后端返回的图片样式信息。

名称	类型	必填	说明
size	[number, number]	是	图片的宽度和高度，单位为px。默认值：size的默认值与objectFit的值有关，不同的objectFit值对应的size默认值也不同。objectFit的值为Cover时，图片高度为组件高度减去组件上下内边距，图片宽度为组件宽度减去组件左右内边距。
verticalAlign	ImageSpanAlignment	是	图片垂直对齐方式。
objectFit	ImageFit	是	图片缩放类型。
layoutStyle	RichEditorLayoutStyle	否	图片布局风格。

（11）RichEditorLayoutStyle

名称	类型	必填	说明
margin	Dimension | Margin	否	外边距类型，用于描述组件不同方向的外边距。 参数为Dimension类型时，四个方向外边距同时生效。
borderRadius	Dimension | BorderRadiuses	否	圆角类型，用于描述组件边框圆角半径。 参数为Dimension类型时，不支持以Percentage形式设置。

（12）RichEditorChangeValue

名称	类型	必填	说明
rangeBefore	TextRange	是	即将被替换内容的开始和结束索引。
replacedSpans	Array<RichEditorTextSpanResult>	是	替换后文本Span的具体信息。
replacedImageSpans	Array<RichEditorImageSpanResult>	是	替换后ImageSpan的具体信息。
replacedSymbolSpans	Array<RichEditorTextSpanResult>	是	替换后SymbolSpan的具体信息。

（13）RichEditorBaseController

RichEditor组件控制器基类。

（14）getCaretOffset

getCaretOffset(): number

返回当前光标所在位置。

返回值：

类型	说明
number	当前光标所在位置。

（15）setCaretOffset

setCaretOffset(offset: number): boolean

设置光标位置。

参数名	类型	必填	说明
offset	number	是	光标偏移位置。超出所有内容范围时，设置失败。

返回值：

类型	说明
boolean	光标是否设置成功。

（16）closeSelectionMenu

closeSelectionMenu(): void

关闭自定义选择菜单或系统默认选择菜单。

（17）getTypingStyle

getTypingStyle(): RichEditorTextStyle

获得用户预设的样式。

返回值：

类型	说明
RichEditorTextStyle	用户预设样式。

（18）setTypingStyle

setTypingStyle(value: RichEditorTextStyle): void

设置用户预设的样式。

参数名	类型	必填	说明
value	RichEditorTextStyle	是	预设样式。

（19）setSelection

setSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void

支持设置组件内的内容选中，选中部分背板高亮。

selectionStart和selectionEnd均为-1时表示全选。

未获焦时调用该接口不产生选中效果。

从API version 12开始，在2in1设备中，无论options取何值，调用setSelection接口都不会弹出菜单，此外，如果组件中已经存在菜单，调用setSelection接口会关闭菜单。

在非2in1设备中，options取值为MenuPolicy.DEFAULT时，遵循以下规则：

1. 组件内有手柄菜单时，接口调用后不关闭菜单，并且调整菜单位置。

2. 组件内有不带手柄的菜单时，接口调用后不关闭菜单，并且菜单位置不变。

3. 组件内无菜单时，接口调用后也无菜单显示。

参数名	类型	必填	说明
selectionStart	number	是	选中开始位置。
selectionEnd	number	是	选中结束位置。
options	SelectionOptions	否	选择项配置。

（20）isEditing

isEditing(): boolean

获取当前富文本的编辑状态。

返回值：

类型	说明
boolean	true为编辑态，false为非编辑态。

（21）stopEditing

stopEditing(): void

退出编辑态。

（22）getLayoutManager

getLayoutManager(): LayoutManager

获取布局管理器对象。

返回值：

类型	说明
LayoutManager	布局管理器对象。

（23）getPreviewText

getPreviewText(): PreviewText

获取预上屏信息。

返回值：

类型	说明
PreviewText	预上屏信息。

（24）RichEditorController

RichEditor组件的控制器，继承自RichEditorBaseController。

1. 导入对象

2. controller: RichEditorController = new RichEditorController()

（25）getCaretOffset

getCaretOffset(): number

返回当前光标所在位置。

返回值：

类型	说明
number	当前光标所在位置。

（26）setCaretOffset

setCaretOffset(offset: number): boolean

设置光标位置。

参数：

参数名	类型	必填	说明
offset	number	是	光标偏移位置。超出文本范围时，设置失败。

返回值：

类型	说明
boolean	光标是否设置成功。

（27）addTextSpan

addTextSpan(value: string, options?: RichEditorTextSpanOptions): number

添加文本内容，如果组件光标闪烁，插入后光标位置更新为新插入文本的后面。

参数：

参数名	类型	必填	说明
value	string	是	文本内容。
options	RichEditorTextSpanOptions	否	文本选项。

返回值：

类型	说明
number	添加完成的TextSpan所在的位置。

（28）addImageSpan

addImageSpan(value: PixelMap | ResourceStr, options?: RichEditorImageSpanOptions): number

添加图片内容，如果组件光标闪烁，插入后光标位置更新为新插入图片的后面。

不建议直接添加网络图片

参数：

参数名	类型	必填	说明
value	PixelMap|ResourceStr	是	图片内容。
options	RichEditorImageSpanOptions	否	图片选项。

返回值：

类型	说明
number	添加完成的ImageSpan所在的位置。

（29）addBuilderSpan

addBuilderSpan(value: CustomBuilder, options?: RichEditorBuilderSpanOptions): number

• RichEditor组件添加占位Span，占位Span调用系统的measure方法计算真实的长宽和位置。
• 可通过RichEditorBuilderSpanOptions设置此builder在RichEditor中的index（一个文字为一个单位）。
• 此占位Span不可获焦，支持拖拽，支持部分通用属性，占位、删除等能力等同于ImageSpan，长度视为一个文字。
• 不支持通过bindSelectionMenu设置自定义菜单。
• 不支持通过getSpans，getSelection，onSelect，aboutToDelete获取builderSpan信息。
• 不支持通过updateSpanStyle，updateParagraphStyle等方式更新builder。
• 对此builder节点进行复制或粘贴不生效。
• builder的布局约束由RichEditor传入，如果builder里最外层组件不设置大小，则会用RichEditor的大小作为maxSize。
• builder的手势相关事件机制与通用手势事件相同，如果builder中未设置透传，则仅有builder中的子组件响应。
• 如果组件光标闪烁，插入后光标位置更新为新插入builder的后面。

参数：

参数名	类型	必填	说明
value	CustomBuilder	是	自定义组件。
options	RichEditorBuilderSpanOptions	否	builder选项。

返回值：

类型	说明
number	添加完成的builderSpan所在的位置。

（30）addSymbolSpan

addSymbolSpan(value: Resource, options?: RichEditorSymbolSpanOptions ): number

在Richeditor中添加SymbolSpan，如果组件光标闪烁，插入后光标位置更新为新插入Symbol的后面。

暂不支持手势、复制、拖拽处理。

参数：

参数名	类型	必填	说明
value	Resource	是	组件内容。
options	RichEditorSymbolSpanOptions	否	组件选项。

返回值：

类型	说明
number	添加完成的SymbolSpan所在的位置。

（31）getTypingStyle

getTypingStyle(): RichEditorTextStyle

获得用户预设的样式。

返回值：

类型	说明
RichEditorTextStyle	用户预设样式。

（32）setTypingStyle

setTypingStyle(value: RichEditorTextStyle): void

设置用户预设的样式。

当开发者设置默认值（undefined/null）或未调用该接口时：

• 使用键盘往无文本内容的RichEditor输入内容时，输入的文本样式是按照默认样式显示，默认样式请参照RichEditorTextStyle内容。

• 使用键盘往有文本内容的RichEditor输入内容时，输入的文本是跟随前一个文本样式，不按照默认样式显示。

当开发者设置非默认值时：

• 使用键盘往RichEditor输入内容均按照开发者设置的样式显示，如果预设样式中有未设置的属性则按照RichEditorTextStyle默认值显示。

参数名	类型	必填	说明
value	RichEditorTextStyle	是	预设样式。

（33）updateSpanStyle

updateSpanStyle(value: RichEditorUpdateTextSpanStyleOptions | RichEditorUpdateImageSpanStyleOptions | RichEditorUpdateSymbolSpanStyleOptions): void

更新文本、图片或SymbolSpan样式。

若只更新了一个Span的部分内容，则会根据更新部分、未更新部分将该Span拆分为多个Span。

使用该接口更新文本、图片或SymbolSpan样式时默认不会关闭自定义文本选择菜单。

参数名	类型	必填	说明
value	RichEditorUpdateTextSpanStyleOptions | RichEditorUpdateImageSpanStyleOptions | RichEditorUpdateSymbolSpanStyleOptions	是	文本、图片或SymbolSpan的样式选项信息。

（34）updateParagraphStyle

updateParagraphStyle(value: RichEditorParagraphStyleOptions): void

更新段落的样式。

参数名	类型	必填	说明
value	RichEditorParagraphStyleOptions	是	段落的样式选项信息。

（35）getSpans

getSpans(value?: RichEditorRange): Array<RichEditorImageSpanResult| RichEditorTextSpanResult>

获取span信息。

参数名	类型	必填	说明
value	RichEditorRange	否	需要获取span范围。

返回值：

类型	说明
Array<RichEditorTextSpanResult | RichEditorImageSpanResult>	文本和图片Span信息。

（36）deleteSpans

deleteSpans(value?: RichEditorRange): void

删除指定范围内的文本和图片。

参数名	类型	必填	说明
value	RichEditorRange	否	删除范围。省略时，删除所有文本和图片。

 （37）getParagraphs

getParagraphs(value?: RichEditorRange): Array<RichEditorParagraphResult>

获得指定返回的段落。

参数名	类型	必填	说明
value	RichEditorRange	否	需要获取段落的范围。

返回值：

类型	说明
Array<RichEditorParagraphResult>	选中段落的信息。

（38）closeSelectionMenu

closeSelectionMenu(): void

关闭自定义选择菜单或系统默认选择菜单。

（39）setSelection

setSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void

支持设置文本选中，选中部分背板高亮。

selectionStart和selectionEnd均为-1时表示全选。

未获焦时调用该接口不产生选中效果。

从API version 12开始，在2in1设备中，无论options取何值，调用setSelection接口都不会弹出菜单，此外，如果组件中已经存在菜单，调用setSelection接口会关闭菜单。

在非2in1设备中，options取值为MenuPolicy.DEFAULT时，遵循以下规则：

1. 组件内有手柄菜单时，接口调用后不关闭菜单，并且调整菜单位置。

2. 组件内有不带手柄的菜单时，接口调用后不关闭菜单，并且菜单位置不变。

3. 组件内无菜单时，接口调用后也无菜单显示。

参数名	类型	必填	说明
selectionStart	number	是	选中开始位置。
selectionEnd	number	是	选中结束位置。
options12+	SelectionOptions	否	选择项配置

（40）getSelection

getSelection(): RichEditorSelection

获取选中内容。如果未选中内容，返回光标所在span信息。

返回值：

类型	说明
RichEditorSelection	选中内容信息。

（41）fromStyledString

fromStyledString(value: StyledString): Array<RichEditorSpan>

将属性字符串转换成span信息。

参数名	类型	必填	说明
value	StyledString	是	转换前的属性字符串。

返回值：

类型	说明
Array<RichEditorSpan>	文本和图片Span信息。

错误码：

错误码ID	错误信息
401	The parameter check failed.

（42）toStyledString

toStyledString(value: RichEditorRange): StyledString

将给定范围的组件内容转换成属性字符串。

参数名	类型	必填	说明
value	RichEditorRange	是	需要获取的范围。

返回值：

类型	说明
StyledString	转换后的属性字符串

错误码：

错误码ID	错误信息
401	The parameter check failed.

（43）RichEditorStyledStringController

使用属性字符串构建的RichEditor组件的控制器，继承自RichEditorBaseController。

导入对象

controller: RichEditorStyledStringController = new RichEditorStyledStringController()

（44）getSelection

getSelection(): RichEditorRange

获取当前富文本当前的选中区域范围。

返回值：

类型	说明
RichEditorRange	选中区域范围。

（45）setStyledString

setStyledString(styledString: StyledString): void

设置富文本组件显示的属性字符串。

参数名	类型	必填	说明
styledString	StyledString	是	属性字符串。 说明： StyledString的子类MutableStyledString也可以作为入参值。

（46）getStyledString

getStyledString(): MutableStyledString;

获取富文本组件显示的属性字符串。

返回值：

类型	说明
MutableStyledString	富文本组件显示的属性字符串

（47）onContentChanged

onContentChanged(listener: StyledStringChangedListener): void

注册文本内容变化回调，该回调会在后端程序导致文本内容变更时触发

参数名	类型	必填	说明
listener	StyledStringChangedListener	是	文本内容变化回调监听器。

（48）RichEditorSelection

选中内容信息。

名称	类型	必填	说明
selection	[number, number]	是	选中范围。
spans	Array<RichEditorTextSpanResult| RichEditorImageSpanResult>	是	span信息。

（49）RichEditorRange

定义RichEditor的范围。

继承自RichEditorRange。

名称	类型	必填	说明
start	number	否	需要更新样式的文本起始位置，省略或者设置负值时表示从0开始。
end	number	否	需要更新样式的文本结束位置，省略或者超出文本范围时表示无穷大。

当start大于end时为异常情况，此时start为0，end为无穷大。

（50）RichEditorSpanStyleOptions

文本样式选项。

继承自RichEditorRange。

（51）RichEditorUpdateTextSpanStyleOptions

文本样式选项。

继承自RichEditorSpanStyleOptions。

名称	类型	必填	说明
textStyle	RichEditorTextStyle	是	文本样式。

（52）RichEditorUpdateImageSpanStyleOptions

图片样式选项。

继承自RichEditorSpanStyleOptions。

名称	类型	必填	说明
imageStyle	RichEditorImageSpanStyle	是	图片样式。

（53）RichEditorUpdateSymbolSpanStyleOptions

SymbolSpan样式选项。

继承自RichEditorSpanStyleOptions。

名称	类型	必填	说明
symbolStyle	RichEditorSymbolSpanStyle	是	组件样式。

（54）RichEditorParagraphStyleOptions

段落样式选项。

继承自RichEditorSpanStyleOptions。

名称	类型	必填	说明
style	RichEditorParagraphStyle	是	段落样式。

（55）RichEditorParagraphStyle

段落样式

名称	类型	必填	说明
textAlign	TextAlign	否	设置文本段落在水平方向的对齐方式。默认值：TextAlign.START
leadingMargin	Dimension | LeadingMarginPlaceholder	否	设置文本段落缩进，当段落仅存在ImageSpan或BuilderSpan时，此属性值不生效。参数为Dimension类型时，不支持以Percentage形式设置。默认值：{"size":["0.00px","0.00px"]}
wordBreak12+	WordBreak	否	设置断行规则。 默认值：WordBreak.BREAK_WORD
lineBreakStrategy12+	LineBreakStrategy	否	设置折行规则。 默认值：LineBreakStrategy.GREEDY 在wordBreak不等于breakAll的时候生效，不支持连字符。

（56）LeadingMarginPlaceholder

前导边距占位符，用于表示文本段落左侧与组件边缘之间的距离。

名称	类型	必填	说明
pixelMap	PixelMap	是	图片内容。
size	[Dimension, Dimension]	是	图片大小，不支持设置百分比。

（57）RichEditorParagraphResult

后端返回的段落信息。

名称	类型	必填	说明
style	RichEditorParagraphStyle	是	段落样式。
range	[number, number]	是	段落起始和结束位置。

（58）RichEditorTextSpanOptions

添加文本的偏移位置和文本样式信息。

名称	类型	必填	说明
offset	number	否	添加文本的位置。省略时，添加到所有内容的最后。 当值小于0时，放在所有内容最前面；当值大于所有内容长度时，放在所有内容最后面。
style	RichEditorTextStyle	否	文本样式信息。省略时，使用系统默认文本信息。
paragraphStyle11+	RichEditorParagraphStyle	否	段落样式。
gesture11+	RichEditorGesture	否	行为触发回调。省略时，仅使用系统默认行为。

（59）RichEditorTextStyle

文本样式信息。

名称	类型	必填	说明
fontColor	ResourceColor	否	文本颜色。 默认值：$r('sys.color.font_primary')。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
fontSize	Length | number	否	设置字体大小，Length为number类型时，使用fp单位。字体默认大小16。不支持设置百分比字符串。字体大小设置为0时，显示默认字体大小。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
fontStyle	FontStyle	否	字体样式。 默认值：FontStyle.Normal。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
fontWeight	number | FontWeight | string	否	字体粗细。 number类型取值[100,900]，取值间隔为100，默认为400，取值越大，字体越粗。 string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular” 、“medium”分别对应FontWeight中相应的枚举值。 默认值：FontWeight.Normal。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
fontFamily	ResourceStr	否	设置字体列表。默认字体'HarmonyOS Sans'，当前支持'HarmonyOS Sans'字体和注册自定义字体。 默认字体:'HarmonyOS Sans'。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
decoration	DecorationStyleInterface	否	设置文本装饰线样式及其颜色。 type默认值:TextDecorationType.None。 color默认值：跟随字体颜色。 style默认值:TextDecorationStyle.SOLID。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
textShadow11+	ShadowOptions | Array<ShadowOptions>	否	设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。 说明： 仅支持设置阴影模糊半径、阴影的颜色、阴影的偏移量。 元服务API： 从API version 12开始，该接口支持在元服务中使用。
lineHeight12+	number | string | Resource	否	设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp，不支持设置百分比字符串。 元服务API： 从API version 12开始，该接口支持在元服务中使用。
letterSpacing12+	number | string	否	设置文本字符间距，当取值为负值时，文字会发生压缩，负值过小时会将组件内容区大小压缩为0，导致无内容显示，number类型时单位为fp, 不支持设置百分比字符串。 元服务API： 从API version 12开始，该接口支持在元服务中使用。
fontFeature12+	string	否	设置文字特性效果，比如数字等宽的特性。如果未设置，默认为变宽数字。设置无效字符保持默认。 格式为：normal | <feature-tag-value> <feature-tag-value>的格式为：<string> [ <integer> | on | off ] <feature-tag-value>的个数可以有多个，中间用','隔开。 例如，使用等宽时钟数字的输入格式为："ss01" on。 Font Feature当前支持的属性见 fontFeature属性列表。 设置 Font Feature 属性，Font Feature 是 OpenType 字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。 更多 Font Feature 能力介绍可参考 CSS Fonts Module Level 3 和 The Complete CSS Demo for OpenType Features 元服务API： 从API version 12开始，该接口支持在元服务中使用。

 （60）PlaceholderStyle

添加提示文本的字体样式。

名称	类型	必填	说明
font	Font	否	设置placeholder文本样式。 默认值跟随主题。
fontColor	ResourceColor	否	设置placeholder文本颜色。 默认值跟随主题。

（61）RichEditorImageSpanOptions

添加图片的偏移位置和图片样式信息。

名称	类型	必填	说明
offset	number	否	添加图片的位置。省略时，添加到所有内容的最后。 当值小于0时，放在所有内容最前面；当值大于所有内容长度时，放在所有内容最后面。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
imageStyle	RichEditorImageSpanStyle	否	图片样式信息。省略时，使用系统默认图片信息。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
gesture11+	RichEditorGesture	否	行为触发回调。省略时，仅使用系统默认行为。 元服务API： 从API version 12开始，该接口支持在元服务中使用。

（62）RichEditorImageSpanStyle

图片样式。

名称	类型	必填	说明
size	[Dimension, Dimension]	否	图片宽度和高度。默认值：size的默认值与objectFit的值有关，不同的objectFit值对应的size默认值也不同。objectFit的值为Cover时，图片高度为组件高度减去组件上下内边距，图片宽度为组件宽度减去组件左右内边距。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
verticalAlign	ImageSpanAlignment	否	图片垂直对齐方式。 默认值:ImageSpanAlignment.BASELINE 元服务API： 从API version 11开始，该接口支持在元服务中使用。
objectFit	ImageFit	否	图片缩放类型。 默认值:ImageFit.Cover。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
layoutStyle11+	RichEditorLayoutStyle	否	图片布局风格。默认值：{"borderRadius":"","margin":""} 元服务API： 从API version 12开始，该接口支持在元服务中使用。

 （63）RichEditorSymbolSpanOptions

添加SymbolSpan组件的偏移位置和SymbolSpan组件样式信息。

名称	类型	必填	说明
offset	number	否	添加组件的位置。省略时，添加到所有内容的最后。 当值小于0时，放在所有内容最前面；当值大于所有内容长度时，放在所有内容最后面。
style	RichEditorSymbolSpanStyle	否	组件样式信息。省略时，使用系统默认样式信息。

（64）RichEditorSymbolSpanStyle

组件SymbolSpan样式信息。

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

（65）RichEditorBuilderSpanOptions

添加图片的偏移位置和图片样式信息。

名称	类型	必填	说明
offset	number	否	添加builder的位置。省略或者为异常值时，添加到所有内容的最后。

 （66）RichEditorSpan

type RichEditorSpan = RichEditorImageSpanResult | RichEditorTextSpanResult

RichEditor span信息。

类型	说明
RichEditorImageSpanResult	后端返回的图片信息。
RichEditorTextSpanResult	后端返回的文本样式信息。

（67）SelectionMenuOptions

菜单的选项。

名称	类型	必填	说明
onAppear	MenuOnAppearCallback	否	自定义选择菜单弹出时回调。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
onDisappear	Callback<void>	否	自定义选择菜单关闭时回调。 元服务API： 从API version 11开始，该接口支持在元服务中使用。
menuType13+	MenuType	否	自定义选择菜单类型。 元服务API： 从API version 13开始，该接口支持在元服务中使用

（68）PasteEvent

定义用户粘贴事件。

名称	类型	必填	说明
preventDefault	Callback<void>	否	阻止系统默认粘贴事件。

（69）CutEvent

 定义用户剪切事件。

名称	类型	必填	说明
preventDefault	Callback<void>	否	阻止系统默认剪切事件。

（70）CopyEvent

定义用户拷贝事件。

名称	类型	必填	说明
preventDefault	Callback<void>	否	阻止系统默认拷贝事件。

 （71）RichEditorGesture

 用户行为回调。

名称	类型	必填	说明
onClick	Callback<ClickEvent>	否	ClickEvent为用户点击事件。 点击完成时回调事件。 双击时，第一次点击触发回调事件。
onLongPress	Callback<GestureEvent>	否	GestureEvent为用户长按事件。 长按完成时回调事件。

（72）KeyboardOptions

设置自定义键盘是否支持避让功能。

名称	类型	必填	说明
supportAvoidance	boolean	否	设置自定义键盘是否支持避让功能；默认值为false不支持避让，true为支持避让。

（73）SubmitCallback

type SubmitCallback = (enterKey: EnterKeyType, event: SubmitEvent) => void

软键盘按下回车键时的回调事件。

参数名	类型	必填	说明
enterKey	EnterKeyType	是	软键盘输入法回车键类型。具体类型见EnterKeyType枚举说明。
event	SubmitEvent	是	当提交的时候，提供保持RichEditor编辑状态的方法。

（74）MenuOnAppearCallback

type MenuOnAppearCallback = (start: number, end: number) => void

自定义选择菜单弹出时触发的回调事件。

参数名	类型	必填	说明
start	number	是	选中内容的起始位置。
end	number	是	选中内容的终止位置。

 （75）PasteEventCallback

type PasteEventCallback = (event?: PasteEvent) => void

完成粘贴前，触发回调。

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