harmony 鸿蒙基础类型定义

  • 2025-06-12
  • 浏览 (3)

基础类型定义

说明：

本模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。

Resource

资源引用类型，用于设置组件属性的值。各类资源文件，需要放入特定子目录中存储管理，资源目录的示例请参考资源分类。

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

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

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

可以通过$r或者$rawfile创建Resource类型对象，不可以修改Resource中的各属性的值。

  • $r('belonging.type.name')

belonging：系统资源或者应用资源，相应的取值为’sys’和’app’；

type：资源类型，支持’boolean’、’color’、’float’、’intarray’、’integer’、’pattern’、’plural’、’strarray’、’string’、’media’；

name：资源名称，在资源定义时确定。

  • $rawfile('filename')

filename：工程中resources/rawfile目录下的文件名称。

说明： 在引用资源类型时，注意其数据类型要与属性方法本身的类型一致，例如某个属性方法支持设置string|Resource，那么在使用Resource引用类型时，其数据类型也应当为string。

Length

长度类型，用于描述尺寸单位。

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

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

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

类型 说明
string 需要显式指定像素单位，如’10px’，也可设置百分比字符串，如’100%‘。
说明：
不指定像素单位时，默认单位vp，如’10’，等同于10。
number 默认单位vp。
Resource 资源引用类型，引入系统资源或者应用资源中的尺寸。

ResourceStr

字符串类型，用于描述字符串入参可以使用的类型。

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

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

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

类型 说明
string 字符串类型。
Resource 资源引用类型，引入系统资源或者应用资源中的字符串。

Padding

内边距类型，用于描述组件不同方向的内边距。

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

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

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

名称 类型 必填 说明
top Length 否 上内边距，组件内元素距组件顶部的尺寸。
right Length 否 右内边距，组件内元素距组件右边界的尺寸。
bottom Length 否 下内边距，组件内元素距组件底部的尺寸。
left Length 否 左内边距，组件内元素距组件左边界的尺寸。

LocalizedPadding12+

内边距类型，用于描述组件不同方向的内边距。

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

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

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

名称 类型 必填 说明
top LengthMetrics12+ 否 上内边距，组件内元素距组件顶部的尺寸。
end LengthMetrics12+ 否 右内边距，组件内元素距组件右边界的尺寸。
从右至左显示语言模式下为
左内边距，组件内元素距组件左边界的尺寸。
bottom LengthMetrics12+ 否 下内边距，组件内元素距组件底部的尺寸。
start LengthMetrics12+ 否 左内边距，组件内元素距组件左边界的尺寸。
从右至左显示语言模式下为
右内边距，组件内元素距组件右边界的尺寸。

Margin

外边距类型，用于描述组件不同方向的外边距。

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

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

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

名称 类型 必填 说明
top Length 否 上外边距，组件顶部距组件外元素的尺寸。
right Length 否 右外边距，组件右边界距组件外元素的尺寸。
bottom Length 否 下外边距，组件底部距组件外元素的尺寸。
left Length 否 左外边距，组件左边界距组件外元素的尺寸。

LocalizedMargin12+

外边距类型，用于描述组件不同方向的外边距。

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

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

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

名称 类型 必填 说明
top LengthMetrics12+ 否 上外边距，组件顶部距组件外元素的尺寸。
end LengthMetrics12+ 否 右外边距，组件右边界距组件外元素的尺寸。
从右至左显示语言模式下为
左外边距，组件左边界距组件外元素的尺寸。
bottom LengthMetrics12+ 否 下外边距，组件底部距组件外元素的尺寸。
start LengthMetrics12+ 否 左外边距，组件左边界距组件外元素的尺寸。
从右至左显示语言模式下为
右外边距，组件右边界距组件外元素的尺寸。

EdgeWidths9+

边框宽度类型，用于描述组件边框不同方向的宽度。

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

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

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

名称 类型 必填 说明
top Length 否 组件上边框宽度。
right Length 否 组件右边框宽度。
bottom Length 否 组件下边框宽度。
left Length 否 组件左边框宽度。

LocalizedEdgeWidths12+

边框宽度类型，用于描述组件边框不同方向的宽度。

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

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

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

名称 类型 必填 说明
top LengthMetrics12+ 否 组件上边框宽度。
end LengthMetrics12+ 否 组件右边框宽度。
从右至左显示语言模式下为组件左边框宽度。
bottom LengthMetrics12+ 否 组件下边框宽度。
start LengthMetrics12+ 否 组件左边框宽度。
从右至左显示语言模式下为组件右边框宽度。

BorderRadiuses9+

圆角类型，用于描述组件边框圆角半径。

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

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

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

名称 类型 必填 说明
topLeft Length 否 组件左上角圆角半径。
topRight Length 否 组件右上角圆角半径。
bottomLeft Length 否 组件左下角圆角半径。
bottomRight Length 否 组件右下角圆角半径。

LocalizedBorderRadiuses12+

圆角类型，用于描述组件边框圆角半径。

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

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

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

名称 类型 必填 说明
topStart LengthMetrics12+ 否 组件左上角圆角半径。
从右至左显示语言模式下为组件右上角圆角半径。
topEnd LengthMetrics12+ 否 组件右上角圆角半径。
从右至左显示语言模式下为组件左上角圆角半径。
bottomStart LengthMetrics12+ 否 组件左下角圆角半径。
从右至左显示语言模式下为组件右下角圆角半径。
bottomEnd LengthMetrics12+ 否 组件右下角圆角半径。
从右至左显示语言模式下为组件左下角圆角半径。

EdgeColors9+

边框颜色，用于描述组件边框四条边的颜色。

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

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

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

名称 类型 必填 说明
top ResourceColor 否 组件上边框颜色。
right ResourceColor 否 组件右边框颜色。
bottom ResourceColor 否 组件下边框颜色。
left ResourceColor 否 组件左边框颜色。

LocalizedEdgeColors12+

边框颜色，用于描述组件边框四条边的颜色。

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

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

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

名称 类型 必填 说明
top ResourceColor 否 组件上边框颜色。
end ResourceColor 否 组件右边框颜色。
从右至左显示语言模式下为组件左边框颜色。
bottom ResourceColor 否 组件下边框颜色。
start ResourceColor 否 组件左边框颜色。
从右至左显示语言模式下为组件右边框颜色。

EdgeStyles9+

边框样式，用于描述组件边框四条边的样式。

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

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

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

名称 类型 必填 说明
top BorderStyle 否 组件上边框样式。
right BorderStyle 否 组件右边框样式。
bottom BorderStyle 否 组件下边框样式。
left BorderStyle 否 组件左边框样式。

Offset

相对布局完成位置坐标偏移量。

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

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

名称 类型 必填 说明
dx Length 是 水平方向偏移量。
dy Length 是 竖直方向偏移量。

RectResult10+

位置和尺寸类型，用于描述组件的位置和宽高。

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

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

参数 类型 描述
x number 水平方向横坐标。
y number 竖直方向纵坐标。
width number 内容宽度大小。
height number 内容高度大小。

ResourceColor

颜色类型，用于描述资源颜色类型。

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

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

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

类型 说明
Color 颜色枚举值。
number HEX格式颜色，支持rgb或者argb。示例：0xffffff，0xffff0000。number无法识别传入位数，格式选择依据值的大小，例如0x00ffffff作rgb格式解析
string rgb或者argb格式颜色。示例：’#ffffff’，’#ff000000’，’rgb(255, 100, 255)‘，’rgba(255, 100, 255, 0.5)‘。
Resource 使用引入资源的方式，引入系统资源或者应用资源中的颜色。

LengthConstrain

长度约束，用于对组件最大、最小长度做限制。

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

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

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

名称 类型 必填 说明
minLength Length 是 组件最小长度。
maxLength Length 是 组件最大长度。

Font

设置文本样式。

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

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

名称 类型 必填 说明
size Length 否 设置文本尺寸，Length为number类型时，使用fp单位。不支持设置百分比字符串。
默认值：16.0
weight FontWeight |number |string 否 设置文本的字体粗细，number类型取值[100, 900]，取值间隔为100，取值越大，字体越粗。
默认值：400 |FontWeight.Normal
family string |Resource 否 设置文本的字体列表。使用多个字体，使用’,‘进行分割，优先级按顺序生效。例如：’Arial, HarmonyOS Sans’。当前支持’HarmonyOS Sans’字体和注册自定义字体。
style FontStyle 否 设置文本的字体样式。
默认值：FontStyle.Normal

Area8+

区域类型，用于存储元素所占区域信息。

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

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

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

名称 类型 说明
width Length 目标元素的宽度，作为返回值时，类型为number，单位vp。
height Length 目标元素的高度，作为返回值时，类型为number，单位vp。
position Position 目标元素左上角相对父元素左上角的位置。
globalPosition Position 目标元素左上角相对页面左上角的位置。

Position

位置类型，用于表示一个坐标点。

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

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

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

名称 类型 必填 说明
x Length 否 x轴坐标，作为返回值时，类型为number，单位vp。
y Length 否 y轴坐标，作为返回值时，类型为number，单位vp。

LocalizedPosition12+

位置类型，用于表示一个坐标点。

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

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

名称 类型 必填 说明
start LengthMetrics 否 LTR模式时x轴相对左边坐标，RTL模式x轴相对右边坐标。
top LengthMetrics 否 y轴坐标。

Edges12+

位置类型，表示相对四边的偏移量。同时设置top和bottom，仅top生效；同时设置left和right，仅left生效。

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

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

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

名称 类型 必填 说明
top Dimension 否 相对顶边的偏移量。
bottom Dimension 否 相对底边的偏移量。
left Dimension 否 相对左边的偏移量。
right Dimension 否 相对右边的偏移量。

LocalizedEdges12+

位置类型，表示相对四边的偏移量。同时设置top和bottom，仅top生效；同时设置start和end，仅start生效。

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

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

名称 类型 必填 说明
top LengthMetrics 否 相对顶边的偏移量。
bottom LengthMetrics 否 相对底边的偏移量。
start LengthMetrics 否 LTR模式时相对左边的偏移量，RTL模式时相对右边的偏移量。
end LengthMetrics 否 LTR模式时相对右边的偏移量，RTL模式时相对左边的偏移量。

ConstraintSizeOptions

设置约束尺寸，组件布局时，进行尺寸范围限制。

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

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

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

名称 类型 必填 说明
minWidth Length 否 元素最小宽度。
maxWidth Length 否 元素最大宽度。
minHeight Length 否 元素最小高度。
maxHeight Length 否 元素最大高度。

SizeOptions

设置宽高尺寸。

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

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

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

名称 类型 必填 说明
width Length 否 元素宽度。
height Length 否 元素高度。

BorderOptions

边框属性集合，用于描述边框相关信息。

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

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

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

名称 类型 必填 说明
width Length |EdgeWidths9+ |LocalizedEdgeWidths12+ 否 边框宽度。
color ResourceColor |EdgeColors9+ 否 边框颜色。
radius Length |BorderRadiuses9+ 否 边框圆角半径。
style BorderStyle |EdgeStyles9+ 否 边框样式。

ColorFilter9+

创建具有4*5矩阵的颜色过滤器。

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

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

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

名称 类型 必填 描述
constructor number[] 是 创建具有4*5矩阵的颜色过滤器，入参为[m*n]位于m行和n列中矩阵值，矩阵是行优先的。

CustomBuilder8+

组件属性方法参数可使用CustomBuilder类型来自定义UI描述。

名称 类型定义 描述
CustomBuilder () => any |void 生成用户自定义组件，在使用时结合@Builder使用。

MarkStyle10+对象说明

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

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

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

ModalTransition10+

全屏模态转场方式枚举类型，用于设置全屏模态转场类型。

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

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

名称 描述
NONE 全屏模态无转场动画。
DEFAULT 全屏模态上下切换动画。
ALPHA 全屏模态透明度渐变动画。

Dimension10+

长度类型，用于描述尺寸单位。

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

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

类型 说明
PX 需要指定以px像素单位，如’10px’。
VP 需要指定数字或vp像素单位，如10或’10vp’。
FP 需要指定以fp像素单位，如’10fp’。
LPX 需要指定以lpx像素单位，如’10lpx’。
Percentage 需要指定以%像素单位，如’10%‘。
Resource 资源引用类型，引入系统资源或者应用资源中的尺寸。

PX10+

长度类型，用于描述以px像素单位为单位的长度。

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

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

类型 说明
{number}px 需要指定以px像素单位，如’10px’。

VP10+

长度类型，用于描述以vp像素单位为单位的长度。

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

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

类型 说明
{number}vp|number 需要指定数字或vp像素单位，如10或’10vp’。

FP10+

长度类型，用于描述以fp像素单位为单位的长度。

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

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

类型 说明
{number}fp 需要指定以fp像素单位，如’10fp’。

LPX10+

长度类型，用于描述以lpx像素单位为单位的长度。

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

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

类型 说明
{number}lpx 需要指定以lpx像素单位，如’10lpx’。

Percentage10+

长度类型，用于描述以%像素单位为单位的长度。

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

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

类型 说明
{number}% 需要指定以%像素单位，如’10%‘。

Degree10+

角度类型，用于描述以deg像素单位为单位的长度。

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

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

类型 说明
{number}deg 需要指定以deg像素单位，如’10deg’。

MultiShadowOptions10+

投影样式。

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

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

名称 参数类型 必填 描述
radius number |Resource 否 投影模糊半径。
API version 10及以前，默认值：5
API version 11及以后，默认值：20
单位：vp
说明：
设置小于等于0的值时，按默认值显示。
offsetX number |Resource 否 X轴偏移量。
默认值：5
单位：vp
offsetY number |Resource 否 Y轴偏移量。
默认值：5
单位：vp

SafeAreaType10+

扩展安全区域的枚举类型。

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

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

名称 描述
SYSTEM 系统默认非安全区域，包括状态栏、导航栏。
CUTOUT 设备的非安全区域，例如刘海屏或挖孔屏区域。
KEYBOARD 软键盘区域。

SafeAreaEdge10+

扩展安全区域的方向。

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

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

名称 描述
TOP 上方区域。
BOTTOM 下方区域。
START 前部区域。
END 尾部区域。

KeyboardAvoidMode12+枚举说明

弹窗避让键盘时，避让模式的枚举类型。

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

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

名称 值 说明
DEFAULT 0 默认避让软键盘并在到达极限高度之后进行高度压缩。
NONE 1 不避让软键盘。

LayoutSafeAreaType12+

扩展布局安全区域的枚举类型。

名称 描述
SYSTEM 系统默认非安全区域，包括状态栏、导航栏。
KEYBOARD20+ 软键盘区域。
ALL20+ 同时包含SYSTEM和KEYBOARD区域。

LayoutSafeAreaEdge12+

扩展安全区域的方向。

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

名称 值 描述
TOP 0 上方区域。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
BOTTOM 1 下方区域。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
START20+ 2 前部区域。LTR模式时表示左侧区域，RTL模式表示右侧区域。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
END20+ 3 尾部区域。LTR模式时表示右侧区域，RTL模式表示左侧区域。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
VERTICAL20+ 4 垂直区域。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
HORIZONTAL20+ 5 水平区域。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
ALL20+ 6 全部区域。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

TouchPoint11+

配置跟手点坐标，不配置时，默认居中。

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

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

名称 类型定义 描述
X Dimension 跟手点X轴坐标。
Y Dimension 跟手点Y轴坐标。

PixelRoundPolicy11+

指定组件级像素取整的方向。

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

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

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

名称 类型 必填 说明
start PixelRoundCalcPolicy 否 组件前部边界取整对齐方式。
top PixelRoundCalcPolicy 否 组件上部边界取整对齐方式。
end PixelRoundCalcPolicy 否 组件尾部边界取整对齐方式。
bottom PixelRoundCalcPolicy 否 组件底部边界取整对齐方式。

VoidCallback12+

type VoidCallback：() => void;

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

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

Callback12+

Callback = (data: T) => V;

带参数的函数回调。

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

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

HoverCallback12+

hover事件的回调类型。

type HoverCallback = (isHover: boolean, event: HoverEvent) => void;

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

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

名称 类型 描述
HoverCallback (isHover: boolean, event: HoverEvent) => void hover事件的回调。

VisibleAreaEventOptions12+

关于区域变化相关的参数。

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

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

参数名 类型 必填 说明
ratios Array<number> 是 阈值数组。其中，每个阈值代表组件可见面积（即组件在屏幕显示区的面积，只计算父组件内的面积，超出父组件部分不会计算）与组件自身面积的比值。每个阈值的取值范围为[0.0, 1.0]，如果开发者设置的阈值超出该范围，则会实际取值0.0或1.0。
expectedUpdateInterval number 否 预期更新间隔，单位为ms。定义了开发者期望的更新间隔。默认值：1000。

VisibleAreaChangeCallback12+

组件可见区域变化事件的回调类型。

type VisibleAreaChangeCallback = (isExpanding: boolean, currentRatio: number) => void;

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

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

名称 类型 描述
VisibleAreaChangeCallback (isExpanding: boolean, currentRatio: number) => void 组件可见区域变化事件的回调。
-isExpanding：表示组件的可见面积与自身面积的比值与上一次变化相比的情况，比值变大为true，比值变小为false。
-currentRatio：触发回调时，组件可见面积与自身面积的比值。

DividerStyleOptions12+

分割线样式属性集合, 用于描述分割线相关信息。

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

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

名称 类型 必填 说明
strokeWidth LengthMetrics12+ 否 分割线的线宽。
color ResourceColor 否 分割线的颜色。
startMargin LengthMetrics12+ 否 分割线与菜单侧边起始端的距离。
endMargin LengthMetrics12+ 否 分割线与菜单侧边结束端的距离。
mode DividerMode19+ 否 设置分割线模式。

TextContentControllerBase10+

TextInput、TextArea、Search的基础控制器。

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

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

getTextContentRect10+

getTextContentRect(): RectResult

获取已编辑文本内容区域相对组件的位置和大小，返回值单位为像素。

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

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

返回值：

类型 说明
RectResult 获取已编辑文本内容区域相对组件的位置和大小。

说明：

  • 初始不输入文本时，返回值中有相对组件的位置信息，大小为0。
  • 返回值中的位置信息是第一个字符相对于可编辑组件的位置。
  • 在Search组件中，返回的位置信息是相对Search组件中搜索图标的偏移值。
  • 有输入时返回信息中的宽度是组件编辑的固定宽度。

getTextContentLineCount10+

getTextContentLineCount(): number

获取已编辑文本内容的行数。

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

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

返回值：

类型 说明
number 已编辑文本内容行数。

getCaretOffset11+

getCaretOffset(): CaretOffset

返回当前光标所在位置信息。

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

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

返回值：

类型 说明
CaretOffset 光标相对输入框的位置。

说明：

  • 在当前帧更新光标位置同时调用该接口，该接口不生效。
  • 在Search组件中，返回的位置信息是相对Search组件中搜索图标的偏移值。
  • 在Search组件中，不输入文本时，返回值中有相对Search组件的位置信息。
  • 返回值中的位置信息是光标相对于可编辑组件的位置。

addText15+

addText(text: string, textOperationOptions?: TextContentControllerOptions): number

在已编辑文本的指定位置插入文本，默认插入至文本末尾。 拖拽文本的状态下不生效。

addText仅影响应用内部的UI表现，不影响输入法应用的内部逻辑，不推荐在预上屏状态下调用。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

参数：

参数名 类型 必填 说明
text string 是 插入的文本内容。
textOperationOptions TextContentControllerOptions 否 插入文本的配置选项，不设置时默认插入文本至末尾。

返回值：

类型 说明
number 插入文本后光标的位置。

deleteText15+

deleteText(range?: TextRange): void

删除已编辑文本的指定区域的内容。 拖拽文本的状态下不生效。

deleteText仅影响应用内部的UI表现，不影响输入法应用的内部逻辑，不推荐在预上屏状态下调用。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

参数：

参数名 类型 必填 说明
range TextRange 否 删除文本的范围，包括删除文本的起始位置和终止位置。
未指定删除范围时，默认将删除全部文本。未指定删除文本的起始位置，则默认从下标0开始删除；未指定删除文本的终止位置，则默认以文本末尾作为删除的结束点。

getSelection15+

getSelection(): TextRange

返回当前文本的选择范围。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

返回值：

类型 说明
TextRange 文本当前的选择范围，未选中返回光标位置。

clearPreviewText17+

clearPreviewText(): void

清除当前的预上屏文本内容。

原子化服务API： 从API version 17开始，该接口支持在原子化服务中使用。

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

getText19+

getText(range?: TextRange): string

获取指定范围的文本内容。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

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

参数：

参数名 类型 必填 说明
range TextRange 否 获取文本的范围，包括需要获取文本的起始位置和终止位置。
未指定范围时，默认将获取全部文本。未指定获取文本的起始位置，则默认从下标0开始；未指定获取文本的终止位置，则默认以文本末尾作为结束点。

返回值：

类型 说明
string 指定范围的文本内容。

TextDecorationOptions12+对象说明

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

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

名称 参数类型 必填 描述
type TextDecorationType 是 设置文本装饰线类型。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
color  ResourceColor 否 设置文本装饰线颜色。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
style TextDecorationStyle 否 设置文本装饰线样式。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

SelectionOptions12+对象说明

setTextSelection选中文字时的配置。

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

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

名称 类型 必填 说明
menuPolicy MenuPolicy 否 菜单弹出的策略。

MenuPolicy12+

菜单弹出的策略。

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

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

名称 值 说明
DEFAULT 0 按照底层默认逻辑决定是否弹出菜单。
HIDE 1 始终不弹出菜单。
SHOW 2 始终弹出菜单。

CaretOffset11+对象说明

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

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

参数名 类型 描述
index number 光标所在位置的索引值。
x number 光标相对输入框的x坐标位值，单位px。
y number 光标相对输入框的y坐标位值，单位px。

InputCounterOptions11+对象说明

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

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

参数名 类型 描述
thresholdPercentage number thresholdPercentage是可输入字符数占最大字符限制的百分比值。字符计数器显示的样式为当前输入字符数/最大字符数。当输入字符数大于最大字符数乘百分比值时，显示字符计数器。thresholdPercentage值的有效值区间为[1,100]，数值为小数时，向下取整，如果设置的number超出有效值区间内，不显示字符计数器。thresholdPercentage设置为undefined，显示字符计数器，但此参数不生效。
highlightBorder boolean 如果用户设置计数器时不设置InputCounterOptions，那么当前输入字符数达到最大字符数时，边框和计数器下标将变为红色。如果用户设置显示字符计数器同时thresholdPercentage参数数值在有效区间内，那么当输入字符数超过最大字符数时，边框和计数器下标将变成红色。如果此参数为true，则显示红色边框。计数器默认显示红色边框。

ChainWeightOptions14+对象说明

链中组件的布局权重。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

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

参数名 类型 描述
horizontal number 组件在竖直方向的布局权重，设置大于0的数字时生效。
默认值：0
异常值：0
vertical number 组件在水平方向的布局权重，设置大于0的数字时生效。
默认值：0
异常值：0

Configuration

数据类型。用于设置颜色模式和字体缩放倍数。

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

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

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

名称 类型 只读 可选 说明
colorMode string 是 否 颜色模式。
fontScale number 是 否 字体缩放。

LayoutPolicy15+

用于设置布局策略。

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

名称 类型 只读 可选 说明
matchParent LayoutPolicy 是 否 当前组件适应父组件布局，其大小与父组件内容区相等。
卡片能力： 从API version 15开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。
wrapContent20+ LayoutPolicy 是 否 当前组件适应子组件布局，其大小与子组件相等且不能超过父组件内容区大小。
卡片能力： 从API version 20开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
fixAtIdealSize20+ LayoutPolicy 是 否 当前组件适应子组件布局，其大小与子组件相等但可以超过父组件内容区大小。
卡片能力： 从API version 20开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

说明：

  • LayoutPolicy支持设置三种布局策略：matchParent（自适应父组件布局）、wrapContent（根据内容自适应但不超过父组件尺寸的布局）和fixAtIdealSize（根据内容自适应，可能超过父组件尺寸的布局）。具体示例代码参见设置布局策略。

  • 当设置了matchParent组件，其父容器设定了长度时，该组件将以父容器的尺寸为基准，自动调整以适应父组件的布局。若父容器未设定长度，该组件则会等待其父组件所有子组件完成布局后，再进行自身调整以适应父组件布局。

  • 若同一父组件下有多个设置matchParent的子组件，则多个子组件均会被设置为父组件大小，也即在特定组件（Flex、Row、Column、RelativeContainer）上子组件会被绘制出容器外。

  • matchParent会强制将自身大小设置成父组件大小，因此其设置的其他除宽高比外约束大小的属性将会失效。

  • matchParent的生效优先级为宽高比 > matchParent > constraintSize ，wrapContent的生效优先级为宽高比 > constraintSize > wrapContent，fixAtIdealSize的生效优先级为宽高比 > constraintSize > fixAtIdealSize。

  • 设置了matchParent的组件会将其大小设置为其父组件不包含padding、border以及safeAreaPadding后的大小，即与父组件内容区大小相等。

使用场景：

  • 使用自定义组件的自定义布局时，对其中的子组件的内容未知，不能确定设置固定的长度和宽度，可以为其的宽度或高度设置LayoutPolicy.fixAtIdealSize，使得子组件不受到父组件的影响，只受到自定义布局限制的影响。

TextContentControllerOptions15+

用于设置输入框插入字符时的配置选项。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

名称 类型 只读 可选 说明
offset number 是 是 插入文本的位置。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙图像AI分析错误码

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/3hxcXk
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录