目录

Basic Types

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Resource

Atomic service API: This API can be used in atomic services since API version 11.

The Resource type is used to reference resources for setting component attributes.

You can use $r or $rawfile to create a Resource object, but its attribute values cannot be changed.

Length

The Length type is used to represent a size unit.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
string

String type. Specify the length unit explicitly, for example, '10px', or provide the length in percentage, for example, '100%'.

NOTE

If the unit is not specified, the default unit vp is used, in which case '10' is equivalent to 10 vp.

number Number type. The default unit is vp.
Resource Size referenced from system or application resources.

ResourceStr

The ResourceStr type is used to represent the types that can be used by input parameters of the string type.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
string String type.
Resource String referenced from system or application resources.

Padding

The Padding type is used to describe the paddings in different directions of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
top Length No Height of the padding on the top of the component.
right Length No Width of the padding on the right of the component.
bottom Length No Height of the padding at the bottom of the component.
left Length No Width of the padding on the left of the component.

LocalizedPadding12+

The Padding type is used to describe the paddings in different directions of a component.

Name Type Mandatory Description
top LengthMetrics12+ No Height of the padding on the top of the component.
end LengthMetrics12+ No

Width of the padding on the right of the component.

For right-to-left scripts:

Width of the padding on the left of the component.

bottom LengthMetrics12+ No Height of the padding at the bottom of the component.
start LengthMetrics12+ No

Width of the padding on the left of the component.

For right-to-left scripts:

Width of the padding on the right of the component.

Margin

The Margin type is used to describe the margins in different directions of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
top Length No Height of the margin above the component.
right Length No Width of the margin on the right of the component.
bottom Length No Height of the margin below the component.
left Length No Width of the margin on the left of the component.

LocalizedMargin12+

The Margin type is used to describe the margins in different directions of a component.

Name Type Mandatory Description
top LengthMetrics12+ No Height of the margin above the component.
end LengthMetrics12+ No

Width of the margin on the right of the component.

For right-to-left scripts:

Width of the margin on the left of the component.

bottom LengthMetrics12+ No Height of the margin below the component.
start LengthMetrics12+ No

Width of the margin on the left of the component.

For right-to-left scripts:

Width of the margin on the right of the component.

EdgeWidths9+

The EdgeWidths type is used to describe the edge widths in different directions of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
top Length No Width of the top edge of the component.
right Length No Width of the right edge of the component.
bottom Length No Width of the bottom edge of the component.
left Length No Width of the left edge of the component.

LocalizedEdgeWidths12+

The EdgeWidths type is used to describe the edge widths in different directions of a component.

Name Type Mandatory Description
top LengthMetrics12+ No Width of the top edge of the component.
end LengthMetrics12+ No

Width of the right edge of the component.

Width of the left edge of the component for right-to-left scripts.

bottom LengthMetrics12+ No Width of the bottom edge of the component.
start LengthMetrics12+ No

Width of the left edge of the component.

Width of the right edge of the component for right-to-left scripts.

BorderRadiuses9+

The BorderRadiuses type is used to describe the radius of the rounded corners of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
topLeft Length No Radius of the top left rounded corner of the component.
topRight Length No Radius of the top right rounded corner of the component.
bottomLeft Length No Radius of the bottom left rounded corner of the component.
bottomRight Length No Radius of the bottom right rounded corner of the component.

LocalizedBorderRadiuses12+

The BorderRadiuses type is used to describe the radius of the rounded corners of a component.

Name Type Mandatory Description
topStart LengthMetrics12+ No

Radius of the top left rounded corner of the component.

Radius of the top right rounded corner of the component for right-to-left scripts.

topEnd LengthMetrics12+ No

Radius of the top right rounded corner of the component.

Radius of the top left rounded corner of the component for right-to-left scripts.

bottomStart LengthMetrics12+ No

Radius of the bottom left rounded corner of the component.

Radius of the bottom right rounded corner of the component for right-to-left scripts.

bottomEnd LengthMetrics12+ No

Radius of the bottom right rounded corner of the component.

Radius of the bottom left rounded corner of the component for right-to-left scripts.

EdgeColors9+

The EdgeColors type is used to describe the edge colors of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
top ResourceColor No Color of the top edge of the component.
right ResourceColor No Color of the right edge of the component.
bottom ResourceColor No Color of the bottom edge of the component.
left ResourceColor No Color of the left edge of the component.

LocalizedEdgeColors12+

The EdgeColors type is used to describe the edge colors of a component.

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Mandatory Description
top ResourceColor No Color of the top edge of the component.
end ResourceColor No

Color of the right edge of the component.

Color of the left edge of the component for right-to-left scripts.

bottom ResourceColor No Color of the bottom edge of the component.
start ResourceColor No

Color of the left edge of the component.

Color of the right edge of the component for right-to-left scripts.

EdgeStyles9+

The EdgeStyles type is used to describe the edge styles of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
top BorderStyle No Style of the top edge of the component.
right BorderStyle No Style of the right edge of the component.
bottom BorderStyle No Style of the bottom edge of the component.
left BorderStyle No Style of the left edge of the component.

Offset

The Offset type is used to describe the offset coordinates of a component in the layout.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
dx Length Yes X coordinate of the offset.
dy Length Yes Y coordinate of the offset.

RectResult10+

The RectResult type is used to describe the position, width, and height of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Description
x number Horizontal coordinate.
y number Vertical coordinate.
width number Content width.
height number Content height.

ResourceColor

The ResourceColor type is used to describe the color types of resources.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
Color Color enums.
number Color in hexadecimal notation. RGB and ARGB are supported. Examples: 0xffffff and 0xffff0000. The number of input digits cannot be identified. The format is selected based on the value. For example, 0x00ffffff is parsed in RGB format.
string Color in RGB or ARGB notation. Example: '#ffffff', '#ff000000', 'rgb(255, 100, 255)', 'rgba(255, 100, 255, 0.5)'
Resource Color referenced from system or application resources.

ColoringStrategy10+

The ColoringStrategy type is used to describe the foreground and shadow colors.

Atomic service API: This API can be used in atomic services since API version 11.

Name Description
INVERT

The foreground colors are the inverse of the component background colors.

Atomic service API: This API can be used in atomic services since API version 11.

AVERAGE11+

The shadow colors of the component are the average color obtained from the component background shadow area.

Atomic service API: This API can be used in atomic services since API version 12.

PRIMARY11+

The shadow colors of the component are the primary color obtained from the component background shadow area.

Atomic service API: This API can be used in atomic services since API version 12.

LengthConstrain

The LengthConstrain type is used to describe the maximum and minimum lengths of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
minLength Length Yes Minimum length of the component.
maxLength Length Yes Maximum length of the component.

Font

The Font type is used to set the text style.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
size Length No

Font size. If the value is of the number type, the unit fp is used. The value cannot be a percentage.

Default value: 16.0

weight FontWeight | number | string No

Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a thicker font.

Default value: 400 | FontWeight.Normal

family string | Resource No Font family of the text. Use commas (,) to separate multiple fonts. The priority of the fonts is the sequence in which they are placed. An example value is 'Arial, HarmonyOS Sans'. The 'HarmonyOS Sans' font and registered custom fonts are supported.
style FontStyle No

Font style.

Default value: FontStyle.Normal

Area8+

The Area type is used to describe the area information of a component.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Description
width Length Width of the component. The value is of the number type in vp when used as the return value.
height Length Height of the component. The value is of the number type in vp when used as the return value.
position Position Position of the upper left corner of the component relative to that of its parent container.
globalPosition Position Position of the upper left corner of the component relative to that of the page where the component resides.

Position

The Position type is used to represent coordinates of a point.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
x Length No X coordinate. The value is of the number type in vp when used as the return value.
y Length No Y coordinate. The value is of the number type in vp when used as the return value.

LocalizedPosition12+

The LocalizedPosition type is used to represent coordinates of a point.

Name Type Mandatory Description
start LengthMetrics No X-coordinate relative to the left for left-to-right scripts; X-coordinate relative to the right for right-to-left scripts.
top LengthMetrics No Y-coordinate.

Edges12+

The Edges type is used to describe the offset relative to the four edges. If both top and bottom are set, only top takes effect. If both left and right are set, only left takes effect.

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Mandatory Description
top Dimension No Offset relative to the top edge.
bottom Dimension No Offset relative to the bottom edge.
left Dimension No Offset relative to the left edge.
right Dimension No Offset relative to the right edge.

LocalizedEdges12+

The LocalizedEdges type is used to describe the offset relative to the four edges. If both top and** bottom **are set, only top takes effect. If both start and end are set, only start takes effect.

Name Type Mandatory Description
top LengthMetrics No Offset relative to the top edge.
bottom LengthMetrics No Offset relative to the bottom edge.
start LengthMetrics No Offset relative to the left for left-to-right scripts; offset relative to the right for right-to-left scripts.
end LengthMetrics No Offset relative to the right for left-to-right scripts; offset relative to the left for right-to-left scripts.

ConstraintSizeOptions

The ConstraintSizeOptions type is used to set the size constraints of a component during component layout.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
minWidth Length No Minimum width of the component.
maxWidth Length No Maximum width of the component.
minHeight Length No Minimum height of the component.
maxHeight Length No Maximum height of the component.

SizeOptions

The SizeOptions type is used to set the width and height.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
width Length No Width of the component.
height Length No Height of the component.

BorderOptions

The BorderOptions type is used to provide border information.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
width Length | EdgeWidths9+ | LocalizedEdgeWidths12+ No Border width.
color ResourceColor | EdgeColors9+ No Border color.
radius Length | BorderRadiuses9+ No Radius of the rounded corner border.
style BorderStyle | EdgeStyles9+ No Border style.

ColorFilter9+

The ColorFilter type is used to create a color filter with a 4 x 5 matrix.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
constructor number[] Yes Constructor for creating a color filter with a 4 x 5 matrix. The input parameter is [m*n], which is the matrix value in row m and column n. The matrix is row-first.

CustomBuilder8+

The CustomBuilder type is used to define custom UI descriptions in component attribute methods.

Name Type Description
CustomBuilder () => any | void Builder for creating a custom component; must be used with @Builder. For details, see @Builder.

MarkStyle10+

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Default Value Description
strokeColor ResourceColor No Color.White Color of the mark.
size Length No -

Size of the mark, in vp. The default size is the same as the width of the check box.

This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.

strokeWidth Length No 2 Stroke width of the mark, in vp. This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.

ModalTransition10+

The ModalTransition type is used to set the transition type for a full-screen modal.

Atomic service API: This API can be used in atomic services since API version 11.

Name Description
NONE No transition animation for the modal.
DEFAULT Slide-up and slide-down animation for the modal.
ALPHA Opacity gradient animation for the modal.

Dimension10+

The Length type is used to represent a size unit.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
PX Physical pixel unit type. The unit px must be included, for example, '10px'.
VP Pixel unit type specific to the screen density. The unit vp can be included or omitted, for example, 10 or '10vp'.
FP Font pixel unit type. The unit fp must be included, for example, '10fp'.
LPX Logical pixel unit type. The unit lpx must be included, for example, '10lpx'.
Percentage Percentage type. The unit % must be included, for example, '10%'.
Resource Size referenced from system or application resources.

PX10+

The PX type is used to represent a length in px.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}px Physical pixel unit type. The unit px must be included, for example, '10px'.

VP10+

The VP type is used to represent a length in vp.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}vp|number Pixel unit type specific to the screen density. The unit vp can be included or omitted, for example, 10 or '10vp'.

FP10+

The FP type is used to represent a length in fp.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}fp Font pixel unit type. The unit fp must be included, for example, '10fp'.

LPX10+

The LPX type is used to represent a length in lpx.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}lpx Logical pixel unit type. The unit lpx must be included, for example, '10lpx'.

Percentage10+

The Percentage type is used to represent a length in percentage.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}% Percentage type. The unit % must be included, for example, '10%'.

Degree10+

The Degree type is used to represent a length in deg.

Atomic service API: This API can be used in atomic services since API version 11.

Type Description
{number}deg Degree type. The unit deg must be included, for example, '10deg'.

MultiShadowOptions10+

The MultiShadowOptions type is used to describe the shadow style.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
radius number | Resource No

Shadow blur radius.

The default value varies by API version.

API version 10 and earlier versions: 5

Since API version 11: 20

Unit: vp

NOTE

A value less than or equal to 0 is handled as the default value.

offsetX number | Resource No

Offset on the x-axis.

Default value: 5

Unit: vp

offsetY number | Resource No

Offset on the y-axis.

Default value: 5

Unit: vp

SafeAreaType10+

The SafeAreaType type is used to describe the types of expanded safe areas.

Atomic service API: This API can be used in atomic services since API version 11.

Name Description
SYSTEM Default non-safe area of the system, including the status bar and navigation bar.
CUTOUT Non-safe area of the device, for example, the notch area.
KEYBOARD Soft keyboard area.

SafeAreaEdge10+

The SafeAreaEdge type is used to define the edge for expanding the safe area.

Atomic service API: This API can be used in atomic services since API version 11.

Name Description
TOP Top edge.
BOTTOM Bottom edge.
START Start edge.
END End edge.

KeyboardAvoidMode11+

The KeyboardAvoidMode type is used to define the avoidance mode for the virtual keyboard.

Atomic service API: This API can be used in atomic services since API version 11.

Name Description
OFFSET Avoid the virtual keyboard through offset.
RESIZE Avoid the virtual keyboard through resizing.

LayoutSafeAreaType12+

The LayoutSafeAreaType type is used to describe the types of expanded safe areas in layout.

Name Description
SYSTEM Default non-safe area of the system, including the status bar and navigation bar.

LayoutSafeAreaEdge12+

The LayoutSafeAreaEdge type is used to define the edge for expanding the safe area.

Name Description
TOP Top edge.
BOTTOM Bottom edge.

TouchPoint11+

The TouchPoint type is used to define the coordinates of the touch point.

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Description
X Dimension X coordinate of the touch point.
Y Dimension Y coordinate of the touch point.

PixelRoundPolicy11+

The PixelRoundPolicy type is used to describe the rounding strategy for component pixel-level alignment.

Atomic service API: This API can be used in atomic services since API version 11.

Name Type Mandatory Description
start PixelRoundCalcPolicy No Rounding for alignment with the start edge.
top PixelRoundCalcPolicy No Rounding for alignment with the top edge.
end PixelRoundCalcPolicy No Rounding for alignment with the end edge.
bottom PixelRoundCalcPolicy No Rounding for alignment with the bottom edge.

VoidCallback12+

type VoidCallback: () => void;

Atomic service API: This API can be used in atomic services since API version 12.

Callback12+

Callback<T,V = void> = (data: T) => V;

The Callback type is used to represent the callback with parameters.

Atomic service API: This API can be used in atomic services since API version 12.

HoverCallback12+

The HoverCallback type is used to represent the callback for the hover event.

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

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Description
HoverCallback (isHover: boolean, event: HoverEvent) => void Callback for the hover event.

VisibleAreaEventOptions12+

The VisibleAreaEventOptions type is used to describe visible area changes.

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Mandatory Description
ratios Array<number> Yes Threshold array. Each threshold represents a ratio of the component's visible area (that is, the area of the component that is visible on screen; only the area within the parent component is counted) to the component's total area. The value range of the threshold is [0.0, 1.0]. If the threshold set exceeds this range, the value 0.0 or 1.0 will be used.
expectedUpdateInterval number No Expected update interval, in milliseconds. You can set it as appropriate. Default value: 1000

VisibleAreaChangeCallback12+

The VisibleAreaChangeCallback type is used to represent a callback for visible area changes of the component.

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

Atomic service API: This API can be used in atomic services since API version 12.

Name Type Description
VisibleAreaChangeCallback (isExpanding: boolean, currentRatio: number) => void

Callback for visible area changes of the component.

- isExpanding: whether the ratio of the component's visible area to its total area is greater than the previous one. The value true means that the ratio is greater than the previous one, and false means the opposite.

- currentRatio: ratio of the component's visible area to its total area when this callback is invoked.

StyledStringValue12+

The StyledStringValue type is used to set the style for an attribute string.

Atomic service API: This API can be used in atomic services since API version 12.

Name Description
TextStyle Text style.
DecorationStyle Text decorative line style.
BaselineOffsetStyle Text baseline offset style.
LetterSpacingStyle Text letter spacing style.
LineHeightStyle Text line height style.
TextShadowStyle Text shadow style.
GestureStyle Gesture style.
ParagraphStyle Text paragraph style.
ImageAttachment Image style.
CustomSpan Custom span style.
UserDataSpan User data span style.

EnterKeyType

Name Description
Go

The Enter key is labeled "Go."

Atomic service API: This API can be used in atomic services since API version 11.

Search

The Enter key is labeled "Search."

Atomic service API: This API can be used in atomic services since API version 11.

Send

The Enter key is labeled "Send."

Atomic service API: This API can be used in atomic services since API version 11.

Next

The Enter key is labeled "Next."

Atomic service API: This API can be used in atomic services since API version 11.

Done

The Enter key is labeled "Done."

Atomic service API: This API can be used in atomic services since API version 11.

PREVIOUS11+

The Enter key is labeled "Previous."

Atomic service API: This API can be used in atomic services since API version 12.

NEW_LINE11+

The Enter key is labeled "Return."

Atomic service API: This API can be used in atomic services since API version 12.

DividerStyleOptions12+

The DividerStyleOptions type is used to provide the information about the divider.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
strokeWidth LengthMetrics12+ No Width of the divider.
color ResourceColor No Color of the divider.
startMargin LengthMetrics12+ No Distance between the divider and the start edge of the menu.
endMargin LengthMetrics12+ No Distance between the divider and the end edge of the menu.

TextContentControllerBase10+

The TextContentControllerBase type is used to represent the base controller for TextInput, TextArea, and Search components.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

[h2]getTextContentRect10+

getTextContentRect(): RectResult

The getTextContentRect type is used to obtain the position of the edited text area relative to the component and its size. The unit of the return value is pixel.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
RectResult Position of the edited text area relative to the component and its size.
  • If no text is entered, the return value contains the position information, but the size is 0.
  • The position information is the offset of the first character relative to the editable area.
  • For the Search component, the returned position information is the offset of the first character relative to the search icon in the component.
  • If there is input, the width in the return value is the fixed width of the editable area.

[h2]getTextContentLineCount10+

getTextContentLineCount(): number

The getTextContentLineCount type is used to obtain the number of lines of the edited text.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
number Number of lines of the edited text.

[h2]getCaretOffset11+

getCaretOffset(): CaretOffset

The getCaretOffset type is used to obtain the position information of the caret.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
CaretOffset Position of the caret relative to the text box.
  • If this API is called when the caret position is updated in the current frame, it will not take effect.
  • For the Search component, the returned position information is the offset of the first character relative to the search icon in the component.
  • If no text is entered in the Search component, the return value contains the position information relative to the component.
  • The location information in the return value is the location of the caret relative to the editable component.

TextDecorationOptions12+

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
type TextDecorationType Yes

Style of the text decorative line.

Atomic service API: This API can be used in atomic services since API version 11.

color ResourceColor No

Color of the text decorative line.

Atomic service API: This API can be used in atomic services since API version 11.

style TextDecorationStyle No

Style of the text decorative line.

Atomic service API: This API can be used in atomic services since API version 12.

SelectionOptions12+

The SelectionOptions type is used to describe the configuration options for text selection.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
menuPolicy MenuPolicy No Menu display policy.

CaretOffset11+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Description
index number Index of the caret position.
x number X coordinate of the caret relative to the text box, in px.
y number Y coordinate of the caret relative to the text box, in px.

InputCounterOptions11+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Description
thresholdPercentage number

Threshold percentage for displaying the character counter. The character counter is displayed when the number of characters that have been entered is greater than the maximum number of characters multiplied by the threshold percentage value. When displayed, the character counter is in the following format: Number of characters that have been entered/Maximum number of characters allowed. It is visible when the number of characters entered is greater than the character limit multiplied by the threshold percentage value. Value range: [1, 100]

If the value is not an integer, it is rounded down to the nearest integer. If the value exceeds the valid value range, the character counter is not displayed. If the value is undefined, the character counter is displayed, but this parameter has no effect.

highlightBorder boolean Whether to highlight the text box border and character counter subscript in red. If options is not set, the text box border and character counter subscript turn red when the number of characters entered reaches the limit. If the character counter is displayed and thresholdPercentage is set to a valid value, the text box border and character counter subscript turn red when the number of entered characters exceeds the limit. The value true (default) means to highlight the text box border and character counter subscript in red.