1# Universal Methods
2
3>  **NOTE**
4>
5>  This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
6
7After a component is assigned the **id** attribute, you can use the ID to obtain the component objects and call methods on them.
8
9
10## animate
11
12animate( keyframes: Keyframes, options: Options): void
13
14**Parameters**
15
16| Name      | Type     | Mandatory  | Description                                  |
17| --------- | --------- | ---- | ------------------------------------ |
18| keyframes | keyframes | Yes   | Animation style.                              |
19| options   | Options   | Yes   | Array of objects used to set animation attributes. For details, see **Options**.|
20
21  **Table 1** keyframes
22
23| Name    | Type                | Description                                    |
24| ------ | ------------------ | -------------------------------------- |
25| frames | Array<Style> | Array of objects used to set animation attributes. For details, see **Style attributes**.|
26
27  **Table 2** Style attributes
28
29| Name                | Type                                      | Default Value                 | Description                                      |
30| ------------------ | ---------------------------------------- | -------------------- | ---------------------------------------- |
31| width              | number                                   | -                    | Width set for the component during playback of the animation.                      |
32| height             | number                                   | -                    | Height set for the component during playback of the animation.                      |
33| backgroundColor    | <color>                            | none                 | Background color set for the component during playback of the animation.                     |
34| opacity            | number                                   | 1                    | Opacity set for the component. The value ranges from 0 to 1.                     |
35| backgroundPosition | string                                   | -                    | The value format is **"x y"**, in percentage or pixels.<br>The first value indicates the horizontal position, and the second value indicates the vertical position.<br>If only one value is specified, the other value is **50%**.|
36| transformOrigin    | string                                   | 'center center' | Origin position of the transformed element.<br>The first value indicates the x-axis position. The value can be **left**, **center**, **right**, a length, or a percentage.<br>The second value indicates the y-axis position. The value can be **top**, **center**, **bottom**, a length, or a percentage.|
37| transform          | [Transform](js-components-common-animation.md) | -                    | Transformation type set for a transformed element.                            |
38| offset             | number                                   | -                    | - The value of **offset** must be within (0.0, 1.0] and sorted in ascending order if it is provided.<br>- If there are only two frames, **offset** can be left empty.<br>- If there are more than two frames, **offset** is mandatory.|
39
40  **Table 3** Options
41
42| Name                    | Type                        | Default Value   | Description                                      |
43| ---------------------- | -------------------------- | ------ | ---------------------------------------- |
44| duration               | number                     | 0      | Duration for playing the animation, in milliseconds.                       |
45| easing                 | string                     | linear | Time curve of the animation. For details about the supported types, see **Available values of the easing attribute**.          |
46| delay                  | number                     | 0      | Delay for the animation start. The default value indicates no delay.                   |
47| iterations             | number \| string | 1      | Number of times the animation will be played. **number** indicates a fixed number of playback operations, and **Infinity** indicates an unlimited number of playback operations.|
48| direction<sup>6+</sup> | string                     | normal | Mode of playing the animation.<br>**normal**: Plays the animation in forward loop mode.<br>**reverse**: Plays the animation in reverse loop mode.<br>**alternate**: Plays the animation in alternating loop mode. When the animation is played for an odd number of times, the playback is in forward direction. When the animation is played for an even number of times, the playback is in backward direction. <br>**alternate-reverse**: plays the animation in reverse alternating loop mode. When the animation is played for an odd number of times, the playback is in reverse direction. When the animation is played for an even number of times, the playback is in forward direction.|
49| fill                   | string                     | none   | Start and end styles of the animation.<br>**none**: No style is applied to the target before or after the animation is executed.<br>**forwards**: The target keeps the state at the end of the animation (defined in the last key frame) after the animation is executed.<br>**backwards**<sup>6+</sup>: The animation uses the value defined in the first key frame during the **animation-delay**. When **animation-direction** is set to **normal** or **alternate**, the value in the **from** key frame is used. When **animation-direction** is set to **reverse** or **alternate-reverse**, the value in the **to** key frame is used.<br>**both**: The animation follows the **forwards** and **backwards** rules.|
50
51  **Table 4** Available values of the easing attribute
52
53| Value                                       | Description                                      |
54| ---------------------------------------- | ---------------------------------------- |
55| linear                                   | The animation speed keeps unchanged.                                 |
56| ease-in                                  | The animation starts at a low speed and then picks up speed until the end. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used.|
57| ease-out                                 | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used.|
58| ease-in-out                              | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used.|
59| friction                                 | The animation uses the friction cubic-bezier curve (0.2, 0.0, 0.2, 1.0).|
60| extreme-deceleration                     | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0).|
61| sharp                                    | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0).|
62| rhythm                                   | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0).|
63| smooth                                   | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0).|
64| cubic-bezier(x1, y1, x2, y2) | You can customize an animation speed curve in the **cubic-bezier()** function. The x and y values of each input parameter must be between 0 and 1.     |
65| steps(number, step-position)<sup>6+</sup> | The animation uses the step curve.<br>The **number** must be set and only an integer is supported.<br>**step-position** is optional. It can be set to **start** or **end**. The default value is **end**.|
66
67**Return value**
68  The **animation** attributes are as follows.
69
70| Name       | Type     | Description                                      |
71| --------- | ------- | ---------------------------------------- |
72| finished  | boolean | Read-only attribute, which indicates whether the animation playback is complete.                     |
73| pending   | boolean | Read-only attribute, which indicates whether the animation is waiting for the completion of other asynchronous operations (for example, start an animation with a delay).|
74| playState | string  | Read-write attribute, which indicates the playback status of the animation:<br>- **idle**: The animation is not running (playback ended or not started).<br>- **running**: The animation is running.<br>- **paused**: The animation is paused.<br>- **finished**: The animation finishes playing.|
75| startTime | number  | Read-write attribute, which indicates the animation start time. This attribute is similar to **delay** in the **options** attribute. |
76
77  The **animation** methods are as follows.
78
79| Method     | Parameter  | Description     |
80| ------- | ---- | ------- |
81| play    | -    | Plays the animation.|
82| finish  | -    | Ends the animation.|
83| pause   | -    | Pauses the animation.|
84| cancel  | -    | Cancels the animation.|
85| reverse | -    | Plays the animation in reverse.|
86
87  The **animation** events are as follows.
88
89| Event                | Description      |
90| ------------------ | -------- |
91| start<sup>6+</sup> | The animation starts. |
92| cancel             | The animation is forcibly canceled.|
93| finish             | The animation playback is complete. |
94| repeat             | The animation repeats. |
95
96**Example**
97```html
98<!-- xxx.hml -->
99<div class="container">
100  <div id="idName" class="box"></div>
101  <div class="buttonBox">
102    <button @click="start">
103      start
104    </button>
105    <button @click="cancel">
106      cancel
107    </button>
108  </div>
109</div>
110```
111
112```css
113/* xxx.css */
114.container {
115  flex-direction: column;
116  justify-content: center;
117  align-items: center;
118  width: 100%;
119}
120.box{
121  width: 200px;
122  height: 200px;
123  background-color: #ff0000;
124  margin-top: 30px;
125}
126.buttonBox{
127  margin-top: 30px;
128  width: 250px;
129  justify-content: space-between;
130}
131button{
132  background-color: #8e8b89;
133  color: white;
134  width: 100px;
135  height: 40px;
136  font-size: 24px;
137}
138```
139
140```js
141// xxx.js
142export default {
143    data: {
144        animation: '',
145        options: {},
146        frames: {}
147    },
148    onInit() {
149        this.options = {
150            duration: 1500,
151            easing: 'friction',
152            delay: 500,
153            fill: 'forwards',
154            iterations: 2,
155            direction: 'normal',
156        };
157        this.frames = [
158            {
159                transform: {
160                    translate: '-120px -0px'
161                }, opacity: 0.1, offset: 0.0
162            },
163            {
164                transform: {
165                    translate: '120px 0px'
166                }, opacity: 1.0, offset: 1.0
167            }
168        ];
169    },
170
171    start() {
172        this.animation = this.$element('idName').animate(this.frames, this.options);
173        this.animation.play();
174    },
175    cancel() {
176        this.animation.cancel();
177    }
178}
179```
180
181![en-us_image_0000001229677045](figures/en-us_image_0000001229677045.gif)
182
183## getBoundingClientRect
184
185getBoundingClientRect(): \<Rect>
186
187Obtains the size of the element and its position relative to the window.
188
189**Return value**
190
191  **Table 5** Rect<sup>6+</sup>
192
193| Name    | Type    | Description            |
194| ------ | ------ | -------------- |
195| width  | number | Width of the element.       |
196| height | number | Height of the element.       |
197| left   | number | Offset between the left boundary of the element and the window.|
198| top    | number | Offset between the upper boundary of the element and the window.|
199
200**Example**
201```js
202// xxx.js
203var rect = this.$element('id').getBoundingClientRect();
204console.info(`current element position is ${rect.left}, ${rect.top}`);
205```
206## createIntersectionObserver
207
208createIntersectionObserver(param?:  ObserverParam): Observer
209
210Listens for the visibility of the element on the current page.
211
212**Parameters**
213
214| Name  | Type         | Mandatory  | Description            |
215| ----- | ------------- | ---- | -------------- |
216| param | ObserverParam | -    | Observer callback.|
217
218  **Table 6** ObserverParam<sup>6+</sup>
219
220| Name    | Type                 | Description                      |
221| ------ | ------------------- | ------------------------ |
222| ratios | Array&lt;number&gt; | Range for triggering the observer callback. If the component is not within the range, the observer callback is triggered.|
223
224**Return value**
225
226  **Table 7** Methods supported Observer<sup>6+</sup>
227
228| Method       | Parameter                     | Description                                 |
229| --------- | ----------------------- | ----------------------------------- |
230| observe   | callback: function | Subscribes to events of the observed object. The callback method is called when the value is greater than or less than the threshold.|
231| unobserve | -                       | Unsubscribes from events of the observed object.                   |
232
233**Example**
234```js
235// xxx.js
236let observer = this.$element('broad').createIntersectionObserver({
237  ratios: [0.2, 0.5], // number
238});
239
240observer.observe((isVisible, ratio)=> {
241    console.info('this element is ' + isVisible + 'ratio is ' + ratio)
242})
243
244observer.unobserve()
245```
246