docs: update Animate API docs

Change-Id: Id08447becc68e639a61d48086df6f27346860e02

Author: YellowFishWyfCPP

docs/en/api/lynx-api/lynx/lynx-animate-api.mdx

@@ -1,6 +1,4 @@
----
-title: animate()
----
+import { VersionBadge } from '@lynx';
 
 # animate()
 
@@ -119,6 +117,8 @@ The `Animation` object has the following methods:
 
 ## Example
 
+### by getElementById()
+
 ```js
 let ani = lynx.getElementById('test').animate(
   [
@@ -172,28 +172,119 @@ ani.play();
 ani.cancel();
 ```
 
-## Animation Event
+::: note
 
-The events for the `animate()` API are the same as the [animation events](../event/animation-event#animation) for CSS animations.
+- Each call to `getElementById("test").animate` will generate a new `Animation` object, and the later created animation will override the previous ones.
+- If you want to restart the same animation, you need to call `getElementById("test").animate` again to create a new `Animation` object.
 
-## Other Infos
+:::
 
-:::info
+### by createSelectorQuery()
 
-- Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.
-- Each call to `getElementById("test").animate` will generate a new `Animation` object.
-- Animate Api currently only supports the creation of one animation, and will support the creation of multiple animations in the future. So now if `getElementById("test").animate` is called multiple times for a node, the last created animation will overwrite the previous animation.
-- After the animation corresponding to an `Animation` object ends, if you want to restart the same animation, you need to call `getElementById("test").animate` again to create a new `Animation` object.
-- Animate API currently only supports getElementById API, and the support for SelectQuery API is still being accessed.
+After **Lynx version 3.3**, the `animate()` can be called via the `createSelectorQuery()`.
 
-:::
+**It's an experimental feature, and you should use it with caution.**
+
+<VersionBadge>3.3</VersionBadge>
+
+```js
+const ani1 = lynx.createAnimation(
+  'ani1',
+  [
+    {
+      transform: 'translateY(0px)',
+    },
+    {
+      transform: 'translateY(-150px)',
+    },
+  ],
+  {
+    name: 'js-animation-1',
+    duration: 3000,
+    iterations: 'infinite',
+    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
+    fill: 'forwards',
+  },
+);
+
+// start
+this.createSelectorQuery().select('#test').animate([ani1]).exec();
+// pause
+this.createSelectorQuery()
+  .select('#test')
+  .pauseAnimation(['js-animation-1'])
+  .exec();
+```
+
+### Multiple animate()
+
+After **Lynx version 3.3**, you can chain multiple animation with `createSelectorQuery()`.
+
+**It's an experimental feature, and you should use it with caution.**
+
+<VersionBadge>3.3</VersionBadge>
+
+```js
+const ani1 = lynx.createAnimation(
+  'ani1',
+  [
+    {
+      transform: 'translateY(0px)',
+    },
+    {
+      transform: 'translateY(-150px)',
+    },
+  ],
+  {
+    name: 'js-animation-1',
+    duration: 3000,
+    iterations: 'infinite',
+    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
+    fill: 'forwards',
+  },
+);
+
+const ani2 = lynx.createAnimation(
+  'ani2',
+  [
+    {
+      'background-color': 'red',
+    },
+    {
+      'background-color': 'blue',
+    },
+  ],
+  {
+    name: 'js-animation-2',
+    duration: 3000,
+    easing: 'linear',
+    fill: 'forwards',
+    iterations: 'infinite',
+  },
+);
+
+// start
+this.createSelectorQuery().select('#test').animate([ani1, ani2]).exec();
+// pause
+this.createSelectorQuery()
+  .select('#test')
+  .pauseAnimation(['js-animation-1', 'js-animation-2'])
+  .exec();
+```
+
+## Animation Event
+
+The events for the `animate()` API are the same as the [animation events](../event/animation-event#animation) for CSS animations.
+
+## Other Infos
 
 :::tip
 
-The Animate API may not take effect, possibly because `getElementById` failed to select the node:
+- Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.
 
-- The ID selector might be incorrect
-- The value of the ID selector might depend on a complex JS expression, causing the value of the ID selector not to be available on the first screen. In this case, if getElementById is invoked too early (like in ComponentDidMount), it might not find the node.
+- The Animate API may not take effect, possibly because `getElementById` failed to select the node:
+  - The ID selector might be incorrect
+  - The value of the ID selector might depend on a complex JS expression, causing the value of the ID selector not to be available on the first screen. In this case, if getElementById is invoked too early (like in ComponentDidMount), it might not find the node.
 
 :::
 

docs/zh/api/lynx-api/lynx/lynx-animate-api.mdx

@@ -1,6 +1,4 @@
----
-title: animate()
----
+import { VersionBadge } from '@lynx';
 
 # animate()
 
@@ -119,6 +117,8 @@ element.animate([
 
 ## 示例
 
+### 通过 getElementById() 调用
+
 ```js
 let ani = lynx.getElementById('test').animate(
   [
@@ -172,32 +172,119 @@ ani.play();
 ani.cancel();
 ```
 
-## 动画事件
+:::note
 
-Animate API 的事件和 CSS Animation [动画事件](../event/animation-event#animation-动画)相同。
+- 每次调用 `lynx.getElementById("test").animate` 都会生成一个新的 `Animation` 对象，同时后面创建的动画会覆盖前面创建的动画。
+- 如果想重启一个同样的动画，需要重新调用 `lynx.getElementById("test").animate` 来创建一个新的 `Animation` 对象。。
 
-## 其他信息
+:::
 
-:::info
+### 通过 createSelectorQuery() 调用
 
-- Animate API 与 CSS Animation 会互相覆盖，后生效的那一方会覆盖前者。
+在 **Lynx 3.3** 版本后，`animate()` 可以通过 `createSelectorQuery()` 来调用。
+
+**该方式属于实验性功能。**
+
+<VersionBadge>3.3</VersionBadge>
+```js
+const ani1 = lynx.createAnimation(
+  'ani1',
+  [
+    {
+      transform: 'translateY(0px)',
+    },
+    {
+      transform: 'translateY(-150px)',
+    },
+  ],
+  {
+    name: 'js-animation-1',
+    duration: 3000,
+    iterations: 'infinite',
+    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
+    fill: 'forwards',
+  },
+);
 
-- 每次调用 `lynx.getElementById("test").animate` 都会生成一个新的 `Animation` 对象。
+// start
+this.createSelectorQuery().select('#test').animate([ani1]).exec();
+// pause
+this.createSelectorQuery()
+.select('#test')
+.pauseAnimation(['js-animation-1'])
+.exec();
 
-- Animate Api 暂只支持创建一个动画，未来会支持创建多个。因此现在若对一个节点多次调用 `lynx.getElementById("test").animate`，最后创建的动画会覆盖前面的动画。
+````
 
-- 一个 `Animation` 对象对应的动画结束后，若想重启一个同样的动画，需要重新调用 `lynx.getElementById("test").animate` 创建一个新的 `Animation` 对象。
+### 多动画 Multiple animate
 
-- Animate API 暂只支持 getElementById API，对 SelectQuery API 的支持还未接入。
+在 **Lynx 3.3** 版本后，可以通过 `createSelectorQuery()` 来在一个节点上同时启动多个动画。
 
-:::
+**该方式属于实验性功能。**
+
+<VersionBadge>3.3</VersionBadge>
+
+```js
+const ani1 = lynx.createAnimation(
+  'ani1',
+  [
+    {
+      transform: 'translateY(0px)',
+    },
+    {
+      transform: 'translateY(-150px)',
+    },
+  ],
+  {
+    name: 'js-animation-1',
+    duration: 3000,
+    iterations: 'infinite',
+    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
+    fill: 'forwards',
+  },
+);
+
+const ani2 = lynx.createAnimation(
+  'ani2',
+  [
+    {
+      'background-color': 'red',
+    },
+    {
+      'background-color': 'blue',
+    },
+  ],
+  {
+    name: 'js-animation-2',
+    duration: 3000,
+    easing: 'linear',
+    fill: 'forwards',
+    iterations: 'infinite',
+  },
+);
+
+// start
+this.createSelectorQuery().select('#test').animate([ani1, ani2]).exec();
+// pause
+this.createSelectorQuery()
+  .select('#test')
+  .pauseAnimation(['js-animation-1', 'js-animation-2'])
+  .exec();
+````
+
+## 动画事件
+
+Animate API 的事件和 CSS Animation [动画事件](../event/animation-event#animation-动画)相同。
+
+## 其他信息
 
 :::tip
 
-Animate API 不生效，可能是 getElementById 未能选中节点：
+- Animate API 与 CSS Animation 会互相覆盖，后生效的那一方会覆盖前者。
 
-- 可能是 ID 选择器不正确
-- 可能是 ID 选择器的值依赖复杂 JS 表达式，导致 ID 选择器的值无法在首屏得到，此时若 getElementById 的时机过早 (如在 ComponentDidMount)，则可能找不到节点
+- Animate API 不生效，可能是 getElementById 未能选中节点：
+  - 可能是 ID 选择器不正确
+  - 可能是 ID 选择器的值依赖复杂 JS 表达式，导致 ID 选择器的值无法在首屏得到，此时若 getElementById 的时机过早 (如在 ComponentDidMount)，则可能找不到节点
 
 :::
 
@@ -211,3 +298,4 @@ Animate API 不生效，可能是 getElementById 未能选中节点：
 import { LegacyCompatTable } from '@lynx';
 
 <LegacyCompatTable metadata="lynx-api/lynx/animateAPI" />
+```

packages/lynx-compat-data/lynx-api/lynx/animateAPI.json

@@ -2,21 +2,43 @@
   "lynx-api": {
     "lynx": {
       "animateAPI": {
-        "__compat": {
-          "description": "Used to import modules.",
-          "lynx_path": "api/lynx-api/lynx/lynx-animate_api",
-          "support": {
-            "android": {
-              "version_added": "1.6"
-            },
-            "ios": {
-              "version_added": "1.6"
-            },
-            "harmony": {
-              "version_added": "3.4"
-            },
-            "web_lynx": {
-              "version_added": false
+        "compat": {
+          "__compat": {
+            "description": "Used to import modules.",
+            "lynx_path": "api/lynx-api/lynx/lynx-animate_api",
+            "support": {
+              "android": {
+                "version_added": "1.6"
+              },
+              "ios": {
+                "version_added": "1.6"
+              },
+              "harmony": {
+                "version_added": "3.4"
+              },
+              "web_lynx": {
+                "version_added": false
+              }
+            }
+          }
+        },
+        "multiple animation implementation": {
+          "__compat": {
+            "description": "Multiple animate",
+            "lynx_path": "api/lynx-api/lynx/lynx-animate_api",
+            "support": {
+              "android": {
+                "version_added": "3.4"
+              },
+              "ios": {
+                "version_added": "3.4"
+              },
+              "harmony": {
+                "version_added": "3.4"
+              },
+              "web_lynx": {
+                "version_added": false
+              }
             }
           }
         }