| animation(value: AnimateParam) | Applies a property animator to this component to control the transition of the component from one state to another.|
When the universal attributes of a component change, you can create an **AnimatorProperty** for gradient to improve user experience.
## AnimateParam
- Attributes
| Name | Type | Default Value | Description |
| -------- | -------- | -------- | -------- |
| duration | number | 1000 | Animation duration, in ms. The default duration is 1000 ms. |
| curve | Curve | Curve.Linear | Animation curve. The default curve is linear. |
| delay | number | 0 | Delay of animation playback, in ms. By default, the playback is not delayed. |
| iterations | number | 1 | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times. |
| playMode | [PlayMode](ts-appendix-enums.md#playmode-enums) | PlayMode.Normal | Playback mode. By default, the animation is played from the beginning after the playback is complete. |
- Curve enums
| Name | Description |
| -------- | -------- |
| Linear | The animation speed keeps unchanged. |
| Ease | The animation starts at a low speed and then accelerates. It slows down before the animation ends. The cubic-bezier curve (0.25, 0.1, 0.25, 1.0) is used. |
| EaseIn | The animation starts at a low speed. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used. |
| EaseOut | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used. |
| EaseInOut | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used. |
| FastOutSlowIn | The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0). |
| LinearOutSlowIn | The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0). |
| FastOutLinearIn | The animation uses the acceleration cubic-bezier curve (0.4, 0.0, 1.0, 1.0). |
| ExtremeDeceleration | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0). |
| Sharp | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0). |
| Rhythm | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0). |
| Smooth | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0). |
| Friction | Damping curve. The cubic-bezier curve (0.2, 0.0, 0.2, 1.0) is used. |
| duration | number | 1000 | Animation duration, in ms. The default duration is 1000 ms. |
| curve | [Curve](ts-appendix-enums.md#curve) | Curve.Linear | Animation curve. The default curve is linear. |
| delay | number | 0 | Delay of animation playback, in ms. By default, the playback is not delayed. |
| iterations | number | 1 | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times. |
| playMode | [PlayMode](ts-appendix-enums.md#playmode) | PlayMode.Normal | Animation playback mode. By default, the animation is played from the beginning after the playback is complete.|
## Example
```ts
// xxx.ets
@Entry
...
...
@@ -67,8 +54,8 @@ struct AttrAnimationExample {
curve:Curve.EaseOut,// Animation curve
delay:500,// Animation delay
iterations:1,// Number of playback times
playMode:PlayMode.Normal// Animation mode
})// Animation configuration for the width and height attributes of the Button component
The **\<ImageAnimator>** component enables images to be played frame by frame. The list of images to be played can be configured, and the duration of each image can be configured.
# ImageAnimator
> **NOTE**
>
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **\<ImageAnimator>** component enables images to be played frame by frame. The list of images to be played can be configured, and the duration of each image can be configured.
## Required Permissions
None
...
...
@@ -23,55 +24,41 @@ ImageAnimator()
## Attributes
| Name | Type | Default Value | Mandatory | Description |
| images | Array<{<br>src:string,<br>width?:Length,<br>height?:Length,<br>top?:Length,<br>left?:Length,<br>duration?:number<br>}> | [] | Yes | Image frame information. The information of each frame includes the image path, image size, image position, and image playback duration. The detailed description is as follows:<br>**src**: image path. The image format can be SVG, PNG, or JPG.<br>**width**: image width.<br>**height**: image height.<br>**top**: vertical coordinate of the image relative to the upper left corner of the component.<br>**left**: horizontal coordinate of the image relative to the upper left corner of the component.<br>**duration**: playback duration of the image, in ms. |
| state | AnimationStatus | AnimationStatus.Initial | No | Playback status of the animation. The default status is **Initial**. |
| duration | number | 1000 | No | Playback duration, in ms. The default duration is 1000 ms. When the duration is **0**, no image is played. The value change takes effect only at the beginning of the next cycle. When a separate duration is set in images, the setting of this attribute is invalid. |
| reverse | boolean | false | No | Playback sequence. The value **false** indicates that images are played from the first one to the last one, and **true** indicates that images are played from the last one to the first one. |
| fixedSize | boolean | true | No | Whether the image size is the same as the component size. **true**: The image size is the same as the component size. In this case, the width, height, top, and left attributes of the image are invalid. **false**: The width, height, top, and left attributes of each image must be set separately. |
| preDecode | number | 0 | No | Whether to enable pre-decoding. The default value **0** indicates that pre-decoding is disabled. If this attribute is set to **2**, two images following the currently playing frame will be cached in advance to improve performance. |
| fillMode | FillMode | FillMode.Forwards | No | Status before and after the animation starts. For details about the options, see **FillMode**. |
| iterations | number | 1 | No | By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times. |
| images | Array<ImageFrameInfo> | [] | Yes| Image frame information. The information of each frame includes the image path, image size, image position, and image playback duration. For details, see **ImageFrameInfo**.|
| state | [AnimationStatus](ts-appendix-enums.md#animationstatus) | Initial | No| Playback status of the animation. The default status is **Initial**.|
| duration | number | 1000 | No| Playback duration, in ms. The default duration is 1000 ms. When the duration is **0**, no image is played. The value change takes effect only at the beginning of the next cycle. When a separate duration is set in **images**, the setting of this attribute is invalid.|
| reverse | boolean | false | No| Playback sequence. The value **false** indicates that images are played from the first one to the last one, and **true** indicates that images are played from the last one to the first one.|
| fixedSize | boolean | true | No| Whether the image size is the same as the component size.<br>**true**: The image size is the same as the component size. In this case, the width, height, top, and left attributes of the image are invalid.<br>**false**: The width, height, top, and left attributes of each image must be set separately.|
| preDecode | number | 0 | No| Whether to enable pre-decoding. The default value **0** indicates that pre-decoding is disabled. The value **2** indicates that two images following the currently playing frame will be cached in advance to improve performance.|
| fillMode | [FillMode](ts-appendix-enums.md#fillmode) | Forwards | No| Status before and after the animation starts. For details about the options, see **FillMode**.|
| iterations | number | 1 | No| Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times.|
- ImageFrameInfo
| Name | Type | Default Value | Mandatory | Description |
| scroller | [Scroller](ts-container-scroll.md#scroller) | Yes | - | Scroller, which can be bound to and control scrollable components. |
| direction | ScrollBarDirection | No | ScrollBarDirection.Vertical | Scrollbar direction in which scrollable components scroll. |
| state | BarState | No | BarState.Auto | Scrollbar state. |
| scroller | [Scroller](ts-container-scroll.md#scroller) | Yes| - | Scroller, which can be bound to scrollable components.|
| direction | ScrollBarDirection | No| ScrollBarDirection.Vertical | Scrollbar direction in which scrollable components scroll.|
| state | [BarState](ts-appendix-enums.md#barstate) | No| BarState.Auto | Scrollbar state.|
> **NOTE**<br>
> The **<ScrollBar>** component defines the behavior style of the scrollable area, and its subnodes define the behavior style of the scrollbar.
> **NOTE**
> The **<\ScrollBar>** component defines the behavior style of the scrollable area, and its subnodes define the behavior style of the scrollbar.
>
> This component is bound to a scrollable component through **scroller**, and can be used to scroll the scrollable component only when their directions are the same. The **<ScrollBar>** component can be bound to only one scrollable component, and vice versa.
> This component is bound to a scrollable component through **scroller**, and can be used to scroll the scrollable component only when their directions are the same. The **\<ScrollBar>** component can be bound to only one scrollable component, and vice versa.
- ScrollBarDirection enums
| Name | Description |
| -------- | -------- |
| Vertical | Vertical scrollbar. |
| Horizontal | Horizontal scrollbar. |
- BarState enums
| Name | Description |
| Name| Description|
| -------- | -------- |
| On | Always display the scrollbar. |
| Off | Hide the scrollbar. |
| Auto | Display the scrollbar on demand (for example, display the scrollbar when the screen is touched or hide the scrollbar after 2s of inactivity). |
| content | string | No| '' | Text content. The content and style set for the **\<Text>** component do not take effect when it contains the **\<Span>** child component.|
| content | [ResourceStr](../../ui/ts-types.md#resourcestr8) | No| '' | Text content. The content and style set for the **\<Text>** component do not take effect when it contains the **\<Span>** child component.|
## Attributes
In addition to the following attributes, the attributes in [Text Style](ts-universal-attributes-text-style.md) are supported.
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| textAlign | [TextAlign](ts-appendix-enums.md) | TextAlign.Start | Text alignment mode of multiple lines of text.|
| textOverflow | {overflow: [TextOverflow](ts-appendix-enums.md)} | {overflow: TextOverflow.Clip} | Display mode when the text is too long.<br>**NOTE**<br/>Text is truncated at the transition between words. To truncate text in the middle of a word, add **\u200B** between characters.<br>This attribute must be used with `maxLines` to take effect. |
| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | TextAlign.Start | Text alignment mode of multiple lines of text.|
| textOverflow | {overflow: [TextOverflow](ts-appendix-enums.md#textoverflow)} | {overflow: TextOverflow.Clip} | Display mode when the text is too long.<br>**NOTE**<br/>Text is truncated at the transition between words. To truncate text in the middle of a word, add **\u200B** between characters.<br>This attribute must be used with `maxLines` to take effect. |
| maxLines | number | Infinity | Maximum number of lines in the text.<br>**NOTE**<br/>By default, text is automatically folded. If this parameter is specified, the text does not exceed the specified number of lines. If there is extra text, you can use `textOverflow` to specify the truncation mode. |
| lineHeight | Length | - | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.|
| decoration | {<br>type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),<br>color?: Color<br>} | {<br>type: TextDecorationType.None,<br>color: Color.Black<br>} | Style and color of the text decorative line.|
| baselineOffset | Length | - | Offset of the text baseline.|
| lineHeight | string \| number \|[Resource](../../ui/ts-types.md) | - | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.|
| decoration | {<br>type: TextDecorationType,<br>color?: [ResourceColor](../../ui/ts-types.md)<br>} | {<br>type: TextDecorationType.None,<br>color: Color.Black<br>} | Style and color of the text decorative line. |
| baselineOffset | number \| string | - | Offset of the text baseline. |
| letterSpacing | [Length](../../ui/ts-types.md) | - | Letter spacing. |
| minFontSize | number \| string \|[Resource](../../ui/ts-types.md) | - | Minimum font size. |
| maxFontSize | number \| string \|[Resource](../../ui/ts-types.md) | - | Maximum font size. |
| textCase | [TextCase](ts-appendix-enums.md#textcase) | TextCase.Normal | Text case.|
| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md) | CopyOptions.None | Whether copy and paste is allowed.|
| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | CopyOptions.None | Whether copy and paste is allowed.|
| alignItems | HorizontalAlign | HorizontalAlign.Center | Alignment mode of child components in the horizontal direction. |
| justifyContent<sup>8+</sup> | [FlexAlign](ts-container-flex.md) | FlexAlign.Start | Alignment mode of child components in the vertical direction. |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| alignItems | [HorizontalAlign](ts-appendix-enums.md#horizontalalign) | HorizontalAlign.Center | Alignment mode of the child components in the horizontal direction.|
| justifyContent<sup>8+</sup> | [FlexAlign](ts-container-flex.md) | FlexAlign.Start | Alignment mode of the child components in the vertical direction.|
| direction | FlexDirection | No | FlexDirection.Row | Direction in which child components are arranged in the **\<Flex>** component, that is, the direction of the main axis. |
| wrap | FlexWrap | No | FlexWrap.NoWrap | Whether the **\<Flex>** component has a single line or multiple lines. |
| justifyContent | FlexAlign | No | FlexAlign.Start | Alignment mode of the child components in the **\<Flex>** component along the main axis. |
| alignItems | [ItemAlign](ts-appendix-enums.md#itemalign-enums)| No | ItemAlign.Stretch | Alignment mode of the child components in the **\<Flex>** component along the cross axis. |
| alignContent | FlexAlign | No | FlexAlign.Start | Alignment mode of the child components in a multi-line **<Flex>** component along the cross axis. This parameter is valid only when **wrap** is set to **Wrap** or **WrapReverse**.|
- FlexDirection enums
| Name | Description |
| ------------- | ---------------- |
| Row | The child components are arranged in the same direction as the main axis runs along the rows. |
| RowReverse | The child components are arranged opposite to the **Row** direction. |
| Column | The child components are arranged in the same direction as the main axis runs down the columns. |
| ColumnReverse | The child components are arranged opposite to the **Column** direction.|
| Start | The child components are aligned with the start edge of the main axis. The first component is aligned with the main-start, and subsequent components are aligned with the previous one.|
| Center | The child components are aligned in the center of the main axis. The space between the first component and the main-start is the same as that between the last component and the main-end.|
| End | The child components are aligned with the end edge of the main axis. The last component is aligned with the main-end, and other components are aligned with the next one.|
| SpaceBetween | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The first component is aligned with the main-start, the last component is aligned with the main-end, and the remaining components are distributed so that the space between any two adjacent components is the same. |
| SpaceAround | The child components are evenly distributed along the main axis. The space between any two adjacent components is the same. The space between the first component and main-start, and that between the last component and cross-main are both half the size of the space between two adjacent components. |
| SpaceEvenly | The child components are equally distributed along the main axis. The space between the first component and main-start, the space between the last component and main-end, and the space between two adjacent components are the same.|
| direction | [FlexDirection](ts-appendix-enums.md#flexdirection) | No | FlexDirection.Row | Direction in which child components are arranged in the **\<Flex>** component, that is, the direction of the main axis. |
| wrap | [FlexWrap](ts-appendix-enums.md#flexwrap) | No | FlexWrap.NoWrap | Whether the **\<Flex>** component has a single line or multiple lines. |
| justifyContent | [FlexAlign](ts-appendix-enums.md#flexalign) | No | FlexAlign.Start | Alignment mode of the child components in the **\<Flex>** component along the main axis. |
| alignItems | [ItemAlign](ts-appendix-enums.md#itemalign) | No | ItemAlign.Stretch | Alignment mode of the child components in the **\<Flex>** component along the cross axis. |
| alignContent | [FlexAlign](ts-appendix-enums.md#flexalign) | No | FlexAlign.Start | Alignment mode of the child components in a multi-line **<Flex>** component along the cross axis. This parameter is valid only when **wrap** is set to **Wrap** or **WrapReverse**.|
| space | Length | No| 0 | Space between two adjacent child components in the horizontal layout. |
| space | Length | No| 0 | Space between two adjacent child components in the horizontal layout.|
## Attributes
| Name | Type | Default Value | Description |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| alignItems | VerticalAlign | VerticalAlign.Center | Alignment mode of the child components in the vertical direction. |
| justifyContent8+ | [FlexAlign](ts-container-flex.md) | FlexAlign.Start | Alignment mode of the child components in the horizontal direction. |
- VerticalAlign enums
| Name | Description |
| -------- | -------- |
| Top | Top aligned. |
| Center | Center aligned. This is the default alignment mode. |
| Bottom | Bottom aligned. |
| alignItems | [VerticalAlign](ts-appendix-enums.md#verticalalign) | VerticalAlign.Center | Alignment mode of the child components in the vertical direction.|
| justifyContent<sup>8+</sup> | [FlexAlign](ts-appendix-enums.md#flexalign) | FlexAlign.Start | Alignment mode of the child components in the horizontal direction.|
> - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
> - When a **\<List>** is nested in this component, you are advised to specify the width and height of the **\<List>** under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the **\<List>**.
> - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
> - When nesting a **\<List>** within this component, specify the width and height for the **\<List>** under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the **\<List>**.
> - This component can produce a bounce effect only when there is more than one screen of content.
The **\<Scroll>** component scrolls the content when the layout size of a component exceeds the viewport of its parent component.
| Spring | Spring effect. When at one of the edges, the component can move beyond the bounds through touches, and produces a bounce effect when the user releases their finger.|
| Fade | Fade effect. When at one of the edges, the component produces a fade effect. |
| None | No effect when the component is at one of the edges. |
| onScrollBegin<sup>9+</sup>(dx: number, dy: number) => { dxRemain: number, dyRemain: number } | Invoked when scrolling starts.<br>Parameters:<br>- **dx**: amount to scroll by in the horizontal direction.<br>- **dy**: amount to scroll by in the vertical direction.<br>Return value:<br>- **dxRemain**: remaining amount to scroll by in the horizontal direction.<br>- **dyRemain**: remaining amount to scroll by in the vertical direction.|
| onScroll(xOffset: number, yOffset: number) => void | Invoked to return the horizontal and vertical offsets during scrolling when the specified scroll event occurs.|
| onScrollEdge(side: Edge) => void | Invoked when scrolling reaches the edge. |
| onScrollEnd() => void | Invoked when scrolling stops. |
| onScroll(event: (xOffset: number, yOffset: number) => void) | Invoked to return the horizontal and vertical offsets during scrolling when the specified scroll event occurs.|
| onScrollEdge(event: (side: Edge) => void) | Invoked when scrolling reaches the edge. |
> If the **onScrollBegin** event and **scrollBy** API are used to implement nested scrolling, you must set **edgeEffect** of the scrolling child node to **None**. For example, if a **\<List>** is nested in the **\<Scroll>** component, the **edgeEffect** attribute of the **\<List>** must be set to **EdgeEffect.None**.
## Scroller
Controller of the scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. Currently, this component can be bound to the **\<List>** and **\<Scroll>** components.
Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. Currently, this component can be bound to the **\<Scroll>** and **\<ScrollBar>** components.
### Objects to Import
...
...
@@ -90,14 +100,8 @@ Scrolls to the edge of the container.
- Parameters
| Name | Type| Mandatory | Default Value | Description |
| ----- | ---- | ---- | ---- | --------- |
| value | Edge | Yes | - | Edge position to scroll to.|
- Edge enums
| value | [Edge](ts-appendix-enums.md#edge) | Yes | - | Edge position to scroll to.|
| Name | Value | Description |
| ------ | ---- | ---------- |
| Top | 0 | Top edge.|
| Bottom | 2 | Bottom edge.|
...
...
@@ -111,7 +115,7 @@ Scrolls to the next or previous page.
| Name | Type | Mandatory | Default Value | Description |
| next | boolean | Yes | - | Whether to turn to the next page. The value **true** means to scroll to the next page, and **false** means to scroll to the previous page.|
| direction | Axis | No | - | Scrolling direction: horizontal or vertical. |
| direction | [Axis](ts-appendix-enums.md#axis) | No | - | Scrolling direction: horizontal or vertical. |
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **<Shape\>** component is the parent component of the drawing components. The attributes described in this topic are universal attributes supported by all the drawing components.
The **\<Shape>** component is the parent component of the drawing components. The attributes described in this topic are universal attributes supported by all the drawing components.
1. Drawing components use **<Shape\>** as their parent component to implement the effect similar to SVG.
1. Drawing components use **\<Shape>** as their parent to implement the effect similar to SVG.
2. The **<Shape\>** component is used independently to draw a specific shape.
2. The **\<Shape>** component is used independently to draw a specific shape.
## Required Permissions
...
...
@@ -21,47 +21,43 @@ None
## Child Components
The **<Shape>** component can contain child components.
This component can contain child components.
## APIs
Shape(value:{target?: PixelMap})
Shape(value?: PixelMap)
- Parameters
| Name | Type | Mandatory | Default Value | Description |
| target | PixelMap | No | null | Shape to draw. You can draw a shape in the specified **PixelMap** object. If no object is specified, the shape is drawn in the current drawing target. |
| value | PixelMap | No| - | Shape to draw. You can draw a shape in the specified **PixelMap** object. If no object is specified, the shape is drawn in the current drawing target.|
## Attributes
| Name | Type | Default Value | Mandatory | Description |
| viewPort | {<br>x?: number \| string,<br>y?: number \| string,<br>width?: number \| string,<br>height?: number \| string<br>} | { x:0, y:0, width:0, height:0 } | No| View port of the shape.|
| fill | [ResourceColor](../../ui/ts-types.md) | Color.Black | No| Color of the fill area.|
| fillOpacity | number \| string \|[Resource](../../ui/ts-types.md#resource-type)| 1 | No| Opacity of the fill area.|
| mesh<sup>8+</sup> | Array<number>,number,number | [],0,0 | No| Mesh effect. The first parameter is an array of lengths (column + 1) * (row + 1) * 2, which records the position of each vertex of the distorted bitmap. The second parameter is the number of columns in the mesh matrix. The third parameter is the number of rows in the mesh matrix.|
// Draw a 300 x 50 rectangle with strokes at (-2, -2). The fill color is 0x317Af7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
// Draw a 300 x 50 ellipse with strokes at (-2, 58). The fill color is 0x317Af7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
// Draw a 300 x 10 path at (-2, 118). The fill color is 0x317Af7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, and the join style is rounded, and anti-aliasing is enabled (default).
// Draw a 300 x 10 path at (-2, 118). The fill color is 0x317Af7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
You can create explicit animation with your custom settings.
> **NOTE**<br>
> This animation is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
> **NOTE**
>
> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
| Name | Description |
| -------- | -------- |
| animateTo(value: [AnimationOptions](#animationoptions), event: ()=> void) : void | Provides a transition animation when the status changes due to the closure code.<br/>**event** specifies the closure function that displays the dynamic effect. The system automatically inserts the transition animation if the status changes in the closure function. |
| animateTo(value: [AnimationOptions](#animationoptions), event: ()=> void) : void | Provides a transition animation when the status changes due to the closure code.<br>**event** specifies the closure function that displays the dynamic effect. The system automatically inserts the transition animation if the status changes in the closure function.|
## AnimationOptions
- Attributes
| Name | Type | Default Value | Description |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| duration | number | 1000 | Animation duration, in ms.|
| tempo | number | 1.0 | Animation playback speed. A larger value indicates faster animation playback, and a smaller value indicates slower animation playback. The value **0** means that there is no animation.|
| delay | number | 0 | Delay of animation playback, in ms. By default, the playback is not delayed.|
| iterations | number | 1 | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times.|
| playMode | PlayMode | Normal | Animation playback mode. By default, the animation is played from the beginning after the playback is complete. |
| duration | number | 1000 | Animation duration, in ms.|
| tempo | number | 1.0 | Animation playback speed. A larger value indicates faster animation playback, and a smaller value indicates slower animation playback. The value **0** means that there is no animation.|
| delay | number | 0 | Delay of animation playback, in ms. By default, the playback is not delayed.|
| iterations | number | 1 | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times.|
| playMode | [PlayMode](ts-appendix-enums.md#playmode) | Normal | Animation playback mode. By default, the animation is played from the beginning after the playback is complete.|
Configure the component transition animations for when a component is inserted or deleted. This feature takes effect only when **animateTo** is used. The animation duration, curve, and delay are the same as those configured in **animateTo**.
> This animation is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
Configure the component transition animations for when a component is inserted or deleted, which improves user experience. This feature takes effect only when **animateTo** is used. The animation duration, curve, and delay are the same as those configured in **animateTo**.
> **NOTE**
>
> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
## Attributes
| Name | Type | Default Value | Description |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| transition | Object | - | All parameters are optional. For details, see **transition** parameters. |
| transition | Object | - | All parameters are optional. For details, see **transition**.|
- transition parameters
| Name | Type | Default Value | Mandatory | Description |
| type | TransitionType | TransitionType.All | No | Transition type, which includes component addition and deletion by default.<br/>> **NOTE**<br/>> If **type** is not specified, insertion and deletion use the same transition type. |
| opacity | number | 1 | No | Opacity effect during component transition, which is the value of the start point of insertion and the end point of deletion. |
| translate | {<br/>x? : number,<br/>y? : number,<br/>z? : number<br/>} | - | No | Translation effect during component transition, which is the value of the start point of insertion and the end point of deletion. |
| scale | {<br/>x? : number,<br/>y? : number,<br/>z? : number,<br/>centerX? : number,<br/>centerY? : number<br/>} | - | No | Scaling effect during component transition, which is the value of the start point of insertion and the end point of deletion. |
| rotate | {<br/>x?: number,<br/>y?: number,<br/>z?: number,<br/>angle?: Angle,<br/>centerX?: Length,<br/>centerY?: Length<br/>} | - | No | Rotation effect during component transition, which is the value of the start point of insertion and the end point of deletion. |
- TransitionType enums
| Name | Description |
| -------- | -------- |
| All | The transition takes effect in all scenarios. |
| Insert | The transition takes effect when a component is inserted. |
| Delete | The transition takes effect when a component is deleted. |
| type | [TransitionType](ts-appendix-enums.md#transitiontype) | TransitionType.All | No| Transition type, which includes component addition and deletion by default.<br>**NOTE**<br>If **type** is not specified, insertion and deletion use the same transition type.|
| opacity | number | 1 | No| Opacity of the component during transition, which is the value of the start point of insertion and the end point of deletion.|
| translate | {<br>x? : number,<br>y? : number,<br>z? : number<br>} | - | No| Translation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>-**x**: distance to translate along the x-axis.<br>-**y**: distance to translate along the y-axis.<br>-**z**: distance to translate along the z-axis.|
| scale | {<br>x? : number,<br>y? : number,<br>z? : number,<br>centerX? : number,<br>centerY? : number<br>} | - | No| Scaling of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: scale factor along the x-axis.<br>- **y**: scale factor along the y-axis.<br>- **z**: scale factor along the z-axis.<br>- **centerX** and **centerY**: x coordinate and y coordinate of the scale center, respectively.<br>- If the center point is 0, it indicates the upper left corner of the component. |
| rotate | {<br>x?: number,<br>y?: number,<br>z?: number,<br>angle?: Angle,<br>centerX?: Length,<br>centerY?: Length<br>} | - | No| Rotation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: rotation vector along the x-axis.<br>- **y**: rotation vector along the y-axis.<br>- **z**: rotation vector along the z-axis.<br>- **centerX** and **centerY**: x coordinate and y coordinate of the rotation center, respectively.<br>- If the center point is (0, 0), it indicates the upper left corner of the component.|
## Example
The following example shows how to use a button to control the appearance and disappearance of another button, and how to configure the required transition animations.
| backgroundColor | [ResourceColor](../../ui/ts-types.md) | - | Background color of a component. |
| backgroundImage | src: [ResourceStr](../../ui/ts-types.md),<br/>repeat?: [ImageRepeat](ts-appendix-enums.md#imagerepeat-enums) | - | **src**: image address, which can be the address of an Internet or a local image. (SVG images are not supported.)<br/>**repeat**: whether the background image is repeatedly used. By default, the background image is not repeatedly used. |
| backgroundImageSize | {<br/>width?: Length,<br/>height?: Length<br/>} \| ImageSize | Auto | Width and height of the background image. When the input is a **{width: Length, height: Length}** object, if only one attribute is set, the other attribute is the set value multiplied by the original aspect ratio of the image. By default, the original image aspect ratio remains unchanged. |
| backgroundImagePosition | {<br/>x?: Length,<br/>y?: Length<br/>} \|[Alignment](ts-appendix-enums.md#alignment-enums) | {<br/>x: 0,<br/>y: 0<br/>} | Position of the background image in the component. |
- ImageSize enums
| Name | Description |
| -------- | -------- |
| Cover | Default value. The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. |
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Auto | The original image aspect ratio is retained. |
| backgroundImage | src: [ResourceStr](../../ui/ts-types.md),<br/>repeat?: [ImageRepeat](ts-appendix-enums.md#imagerepeat) | - | **src**: image address, which can be the address of an Internet or a local image. (SVG images are not supported.)<br/>**repeat**: whether the background image is repeatedly used. By default, the background image is not repeatedly used. |
| backgroundImageSize | {<br/>width?: Length,<br/>height?: Length<br/>} \|[ImageSize](ts-appendix-enums.md#imagesize) | Auto | Width and height of the background image. When the input is a **{width: Length, height: Length}** object, if only one attribute is set, the other attribute is the set value multiplied by the original aspect ratio of the image. By default, the original image aspect ratio remains unchanged. |
| backgroundImagePosition | {<br/>x?: Length,<br/>y?: Length<br/>} \|[Alignment](ts-appendix-enums.md#alignment) | {<br/>x: 0,<br/>y: 0<br/>} | Position of the background image in the component. |
Create a more gorgeous look for a component by applying a gradient color effect to it.
> **NOTE**
> **NOTE**
>
> This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
...
...
@@ -15,37 +15,21 @@ None
## Attributes
| Name | Type | Default Value | Description |
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| linearGradient | {<br/>angle?: [Angle](../../ui/ts-types.md),<br/>direction?:GradientDirection,<br/>colors: Array<[ColorStop](../../ui/ts-types.md)><br/>repeating?: boolean<br/>} | - | Linear gradient.<br/>**angle**: angle of the linear gradient.<br/>**direction**: direction of the linear gradient. It does not take effect when **angle** is set.<br/>**colors**: description of the gradient colors.<br/>**repeating**: whether the colors are repeated. |
| sweepGradient | {<br/>center: Point,<br/>start?: angle,<br/>end?: angle,<br/>colors: Array<[ColorStop](../../ui/ts-types.md)><br/>repeating?: boolean<br/>} | - | Angle gradient.<br/>**center**: center point of the angle gradient.<br/>**start**: start point of the angle gradient.<br/>**end**: end point of the angle gradient.<br/>**colors**: description of the gradient colors.<br/>**repeating**: whether the colors are repeated. |
| radialGradient | {<br/>center: Point,<br/>radius: Length,<br/>colors: Array<[ColorStop](../../ui/ts-types.md)><br/>repeating: boolean<br/>} | - | Radial gradient.<br/>**center**: center point of the radial gradient.<br/>**radius**: radius of the radial gradient.<br/>**colors**: description of the gradient colors.<br/>**repeating**: whether the colors are repeated. |
- GradientDirection
Enumerates the gradient directions.
| Name | Description |
| -------- | -------- |
| Left | The gradient direction is from right to left. |
| Top | The gradient direction is from bottom to top. |
| Right | The gradient direction is from left to right. |
| Bottom | The gradient direction is from top to bottom. |
| LeftTop | The gradient direction is upper left. |
| LeftBottom | The gradient direction is lower left. |
| RightTop | The gradient direction is upper right. |
| RightBottom | The gradient direction is lower right. |
| None | No gradient. |
| linearGradient | {<br>angle?: [Angle](../../ui/ts-types.md),<br>direction?: [GradientDirection](ts-appendix-enums.md#gradientdirection),<br>colors: Array<[ColorStop](../../ui/ts-types.md)><br>repeating?: boolean<br>} | - | Linear gradient.<br>**angle**: angle of the linear gradient.<br>**direction**: direction of the linear gradient. It does not take effect when **angle** is set.<br>**colors**: description of the gradient colors.<br>**repeating**: whether the colors are repeated.|
| sweepGradient | {<br>center: Point,<br>start?: angle,<br>end?: angle,<br>colors: Array<[ColorStop](../../ui/ts-types.md)><br>repeating?: boolean<br>} | - | Angle gradient.<br>**center**: center point of the angle gradient.<br>**start**: start point of the angle gradient.<br>**end**: end point of the angle gradient.<br>**colors**: description of the gradient colors.<br>**repeating**: whether the colors are repeated.|
| radialGradient | {<br>center: Point,<br>radius: Length,<br>colors: Array<[ColorStop](../../ui/ts-types.md)><br>repeating: boolean<br>} | - | Radial gradient.<br>**center**: center point of the radial gradient.<br>**radius**: radius of the radial gradient.<br>**colors**: description of the gradient colors.<br>**repeating**: whether the colors are repeated.|
This module provides APIs for binding a menu – a vertical list of items – to a component. This menu is displayed by long-pressing, clicking, or right-clicking the component.
A menu – a vertical list of items – can be bound to a component and displayed by long-pressing, clicking, or right-clicking the component.
> **NOTE**
>
> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
> **NOTE**
>
> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
| bindMenu | Array<MenuItem> \| [CustomBuilder](../../ui/ts-types.md)<sup>8+</sup> | - | Menu bound to the component, which is displayed when you click the component. Textual and custom menu items are supported.|
| bindContextMenu<sup>8+</sup> | content: [CustomBuilder](../../ui/ts-types.md),<br>responseType: ResponseType | - | Context menu bound to the component, which is displayed when you long-press or right-click the component. Only custom menu items are supported. |
| bindMenu | Array<MenuItem>\|[CustomBuilder](../../ui/ts-types.md)<sup>8+</sup> | - | Menu bound to the component, which is displayed when you click the component. Textual and custom menu items are supported.|
| bindContextMenu<sup>8+</sup> | content:[CustomBuilder](../../ui/ts-types.md),<br>responseType: [ResponseType](ts-appendix-enums.md#responsetype8) | - | Context menu bound to the component, which is displayed when you long-press or right-click the component. Only custom menu items are supported. |
| fontColor | [ResourceColor](../../ui/ts-types.md) | - | Text color. |
| fontSize | Length \| [Resource](../../ui/ts-types.md) | - | Text size. If the value is of the number type, the unit fp is used. |
| fontStyle | FontStyle | FontStyle.Normal | Font style of the text. |
| fontWeight | number \| FontWeight \| string | FontWeight.FontWeightNormal | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.<br/>For common values of the **FontWeight** type, see **FontWeight** enums. |
| fontFamily | string \| [Resource](../../ui/ts-types.md) | - | Font family of the text. Use commas (,) to separate multiple fonts. The priority the fonts is the sequence in which they are placed. An example value is **Arial, sans-serif**. |
- FontStyle enums
| Name | Description |
| -------- | -------- |
| Normal | Standard font style. |
| Italic | Italic font style. |
- FontWeight enums
| Name | Description |
| -------- | -------- |
| Lighter | The font weight is lighter. |
| Normal | The font weight is normal. |
| Regular | The font weight is regular. |
| Medium | The font weight is medium. |
| Bold | The font weight is bold. |
| Bolder | The font weight is bolder. |
| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | FontStyle.Normal | Font style of the text. |
| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | FontWeight.FontWeightNormal | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.<br/>For common values of the **FontWeight** type, see **FontWeight** enums. |
| fontFamily | string \| [Resource](../../ui/ts-types.md#resource-type) | - | Font family of the text. Use commas (,) to separate multiple fonts. The priority the fonts is the sequence in which they are placed. An example value is **Arial, sans-serif**. |
| visibility | Visibility | Visibility.Visible | Whether the component is visible. Note that even if a component is hidden, it needs to be re-created when the page is refreshed. Therefore, you are advised to use [conditional rendering](../../ui/ts-rending-control-syntax-if-else.md) instead under scenarios where consistently high performance is required. |
- Visibility enums
| Name| Description|
| -------- | -------- |
| Hidden | The component is hidden, and a placeholder is used for it in the layout.|
| Visible | The component is visible.|
| None | The component is hidden. It is not involved in the layout, and no placeholder is used for it.|
| visibility | [Visibility](ts-appendix-enums.md#visibility) | Visibility.Visible | Whether the component is visible. Note that even if a component is hidden, it needs to be re-created when the page is refreshed. Therefore, you are advised to use [conditional rendering](../../ui/ts-rending-control-syntax-if-else.md) instead under scenarios where consistently high performance is required. |
| onHover(callback: (isHover: boolean) => void) | No | Triggered when the mouse cursor enters or leaves the component.<br/>**isHover**: whether the mouse cursor hovers over the component. The value **true** means that the mouse cursor enters the component, and the value **false** means that the mouse cursor leaves the component. |
| onHover(callback: (isHover?: boolean) => void) | No | Triggered when the mouse cursor enters or leaves the component.<br/>**isHover**: whether the mouse cursor hovers over the component. The value **true** means that the mouse cursor enters the component, and the value **false** means that the mouse cursor leaves the component. |
| onMouse(callback: (event?: MouseEvent) => void) | Yes | Triggered when the component is clicked by a mouse button or the mouse cursor moves on the component. The **event** parameter indicates the timestamp, mouse button, action, coordinates of the clicked point on the entire screen, and coordinates of the clicked point relative to the component when the event is triggered. |
...
...
@@ -29,30 +29,11 @@ None
| screenY | number | Y-coordinate of the clicked point relative to the upper left corner of the screen. |
| x | number | X-coordinate of the clicked point relative to the upper left corner of the component. |
| y | number | Y-coordinate of the clicked point relative to the upper left corner of the component. |
| Length | string \| number | Length unit. If the input is a number, use vp. If the input is a string, explicitly specify the unit, for example, '10px', or specify the length in percentage, for example, '100%'.|
The **Resource** type is used to reference resources for setting component attribute values.
If a **Resource** object is created using `$r` or `$rawfile`, modifying attribute values of the object is prohibited.
## Angle Type
-`$r('belonging.type.name')`
| Name| Type| Description|
| -------- | -------- | -------- |
| Angle | string \| number | Angle unit. If the input is a number, use deg. If the input is a string, use either of the following angle units:<br>- deg: for example, '100deg'<br>- rad: for example, '3.14rad' |
**belonging**: system or application resource. The value can be **'sys'** or **'app'**.
**type**: resource type, which can be **'color'**, **'float'**, **'string'**, or **'media'**.
## Point Type
**name**: resource name, which is determined during resource definition.
| Name| Type| Description|
| -------- | -------- | -------- |
| Point | [Length, Length] | Coordinates of a point. The first value is the x-axis coordinate, and the second value is the y-axis coordinate.|
-`$rawfile('filename')`
**filename**: name of the file in **resources/rawfile** of the project.
The Color type used by component attribute methods is described as follows:
## Length
| Name| Type| Description|
| -------- | -------- | -------- |
| Color | string \| number \| Color | Color information. If the input is a string, use rgb or rgba to specify the color. If the input is a number, use Hex format to specify the color. If the input is a Color enum, use a color value to specify the color.<br>- 'rgb(255, 255, 255)'<br>- 'rgba(255, 255, 255, 1.0)'<br>- Hex format: 0xrrggbb, 0xaarrggbb, '\#FFFFFF'<br>- Enum: Color.Black, Color.White |
The **Length** type is used to represent a size unit.
| top | Length | No | Height of the padding area on the top of the component. |
| right | Length | No | Width of the padding area on the right of the component.|
| bottom | Length | No | Height of the padding area at the bottom of the component. |
| left | Length | No | Width of the padding area on the left of the component.|
| Name| Type| Description|
| -------- | -------- | -------- |
| ColorStop | [Color, number] | Type of the progressive color stop. The first parameter specifies the color value, and the second parameter specifies the ratio of 0 to 1.|
## Margin
The **Margin** type is used to describe the margin areas in different directions of a component.
| size | number | No | Font size. If the value is of the number type, the unit fp is used. |
| weight | number | No | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.|
| family | [FontWeight](../reference/arkui-ts/ts-appendix-enums.md#fontweight)\| number \| string | 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, sans-serif'**.|
| style | string \| Resource | No | Font style. |
| Name| Type| Description|
| -------- | -------- | -------- |
| Resource | {<br>readonly id: [number];<br>readonly type: [number];<br>readonly params?: any[];<br>} | **id**: resource ID.<br>**type**: resource type (enumerated value).<br>**params**: optional parameters.<br>After a **Resource** object is created using `$r` or `$rawfile`, modifying attribute values of the object is prohibited. |
## Area<sup>8+</sup>
The **Area** type is used to describe the area information of the target element.
| x | Length | No | X coordinate. The value is of the number type when being used as the return value and the unit is vp. |
| y | Length | No | Y coordinate. The value is of the number type when used as the return value and the unit is vp. |
## Font Type<sup>8+</sup>
## ConstraintSizeOptions
| Name| Type| Description|
| -------- | -------- | -------- |
| Font | {<br/>size?: Length;<br/>weight?: <ahref="https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md">FontWeight</a>\| number \| string;<br/>family?: string \|<ahref="ts-types.md#Resource">Resource</a>;<br/>style?: <ahref="https://gitee.com/superFat/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md">FontStyle</a>;<br/>} | Text style.<br>**size**: font size. For the number type, use the unit fp.<br>weight: font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is 400. A larger value indicates a larger font weight.<br>**family**: font family. Use commas (,) to separate multiple fonts. The priority of the fonts is the sequence in which they are placed. An example value is **'Arial, sans-serif'**.<br>**style**: font style. |
The **ConstraintSizeOptions** type is used to set the constraint size of a component, thereby limiting the size range during component layout.
## CustomBuilder Type<sup>8+</sup>
| Name | Type | Mandatory | Description |
| --------- | -------- | ---- | -------------- |
| minWidth | Length | No | Minimum width of the element. |
| maxWidth | Length | No | Maximum width of the element. |
| minHeight | Length | No | Minimum height of the element. |
| maxHeight | Length | No | Maximum height of the element. |
You can use CustomBuilder to define custom UI descriptions in component attribute methods.
## SizeOptions
| Name| Type| Description|
| -------- | -------- | -------- |
| CustomBuilder | () => any | Builder of component attribute methods for defining custom UI descriptions. This type of method must be decorated by @Builder. For details, see [@Builder](ts-component-based-builder.md).|
The **SizeOptions** type is used to set the width and height.
| constructor | number[] | Yes | Constructor for creating a color filter with a 4\*5 matrix. The input parameter is [m*n], which is the matrix value in row m and column n. The matrix is row-first. |
| CustomBuilder | () => any | Builder of component attribute methods for defining custom UI descriptions. This type of method must be decorated by **@Builder**. For details, see [@Builder](ts-component-based-builder.md).|
