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.
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.
$r('belonging.type.name')
belonging: group to which the resource belongs, which can be 'sys' or 'app'.
type: resource type, which can be 'boolean', 'color', 'float', 'intarray', 'integer', 'pattern', 'plural', 'strarray', 'string', or 'media'.
name: resource name, which is determined during resource definition.
$rawfile('filename')
filename: name of the file in the resources/rawfile directory of the project.
NOTE
When referencing resources of the Resource type, make sure the data type is the same as that of the attribute method. For example, if an attribute method supports the string | Resource types, the data type of the Resource type must be string.
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. |
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. |
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. |
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. |
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.
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. |
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.
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. |
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. |
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. |
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. |
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. |
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. |
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.
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. |
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. |
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. |
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.
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 |
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. |
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.
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. |
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.
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. |
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.
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.
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. |
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. |
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. |
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. |
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. |
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. |
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'. |
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'. |
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'. |
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'. |
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%'. |
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'. |
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 |
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. |
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. |
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. |
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. |
The LayoutSafeAreaEdge type is used to define the edge for expanding the safe area.
| Name | Description |
|---|---|
| TOP | Top edge. |
| BOTTOM | Bottom edge. |
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.
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. |
type VoidCallback: () => void;
Atomic service API: This API can be used in atomic services since API version 12.
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.
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. |
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 |
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. |
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. |
| 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. |
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. |
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
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. |
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. |
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. |
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. |
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. |
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. |
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. |