@react-native-ohos/react-native-reanimated 4.0.2 → 4.1.0-beta.1

package/README.md

@@ -0,0 +1,842 @@
+> 文档模板：v0.4.2
+
+<p align="center">
+  <h1 align="center"> <code>react-native-reanimated</code> </h1>
+</p>
+<p align="center">
+    <a href="https://github.com/software-mansion/react-native-reanimated">
+        <img src="https://img.shields.io/badge/platforms-ios%20|%20android%20|%20web%20|%20harmony%20-lightgrey.svg" alt="Supported platforms" />
+    </a>
+    <a href="https://github.com/software-mansion/react-native-reanimated/blob/main/LICENSE">
+        <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
+    </a>
+</p>
+
+本项目基于 [原库 react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) 开发。
+
+该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-reanimated`，版本所属关系如下：
+
+| 三方库名称                                  | 三方库版本（npm地址）                                                                                 | 发布信息                                                                    | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址                                                                                       |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------- | -------- | ----------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| @react-native-ohos/react-native-reanimated | [~ 4.1.0(进行中)](https://www.npmjs.com/package/@react-native-ohos/react-native-reanimated)            | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/releases) | 0.84.*     | 是       | API12+      | 4.5.3        | [master](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated)                    |
+| @react-native-ohos/react-native-reanimated | [~ 4.0.0](https://www.npmjs.com/package/@react-native-ohos/react-native-reanimated)                  | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/releases) | 0.82.*     | 否       | API12+      | 4.2.1        | [br_rnoh0.82](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/tree/br_rnoh0.82) |
+| @react-native-ohos/react-native-reanimated | [~ 3.18.1](https://www.npmjs.com/package/@react-native-ohos/react-native-reanimated)                 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/releases) | 0.77.*     | 否       | API12+      | 3.18.0       | [br_rnoh0.77](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/tree/br_rnoh0.77) |
+| @react-native-ohos/react-native-reanimated | [~ 3.6.5](https://www.npmjs.com/package/@react-native-ohos/react-native-reanimated)                  | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/releases) | 0.72.*     | 是       | API12+      | 3.6.0        | [br_rnoh0.72](https://gitcode.com/openharmony-sig/rntpc_react-native-reanimated/tree/br_rnoh0.72) |
+| @react-native-oh-tpl/react-native-reanimated | [<= 3.6.4@deprecated](https://www.npmjs.com/package/@react-native-oh-tpl/react-native-reanimated) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-harmony-reanimated/releases) | 0.72.* | 否 | API12+ | 3.6.0 | [sig](https://github.com/react-native-oh-library/react-native-harmony-reanimated) |
+
+## 简介
+
+react-native-reanimated 是 React Native 生态中使用最广泛的高性能动画库，是 RN 内置 `Animated` 库的增强替代方案。它通过 worklet 机制将动画计算放到 UI 线程执行，提供了动画（`withTiming` / `withSpring` / `withDecay` 等）、布局动画（进入 / 退出 / 布局过渡 / 共享元素转场）、CSS 动画与过渡、手势与传感器联动、键盘动画等全面的能力。
+
+> `react-native-reanimated >= 4.0.0` 起，worklets 能力已独立成库，需同时引入 [@react-native-ohos/react-native-worklets](../react-native-worklets/README.md)。
+
+## 下载安装
+
+进入到工程目录并输入以下命令：
+
+**npm**
+
+```bash
+# RN 0.84
+npm install react-native-reanimated@4.5.3
+npm install @react-native-ohos/react-native-reanimated
+```
+
+**yarn**
+
+```bash
+# RN 0.84
+yarn add react-native-reanimated@4.5.3
+yarn add @react-native-ohos/react-native-reanimated
+```
+
+#### 插件配置
+
+添加插件到 `babel.config.js`：
+
+> [!TIP] 为什么需要添加这个？Reanimated Babel 插件会自动转换特殊的 JavaScript 函数（称为 worklet），以便它们可以被传递并在 UI 线程上运行。
+
+```js
+  module.exports = {
+    presets: [
+      ... // don't add it here :)
+    ],
+    plugins: [
+      ...
+      'react-native-worklets/plugin',
+    ],
+  };
+```
+
+清除 Metro 的缓存（推荐）：
+
+**npm**
+
+```bash
+npm start --reset-cache
+```
+
+**yarn**
+
+```bash
+yarn start --reset-cache
+```
+
+## Link
+
+|                     | 是否支持autolink | RN框架版本 |
+| ------------------- | ---------------- | ---------- |
+| ~ 4.1.0             | 是               | 0.84       |
+
+使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md
+
+如您使用的版本支持 Autolink，并且工程已接入 Autolink，需要配置[Overrides RN SDK](#1-overrides-rn-sdk)后，可跳过ManualLink配置。
+
+> [!TIP] version >= 4.0.0。
+> 该版本 HarmonyOS 侧实现依赖 `@react-native-ohos/react-native-worklets` 的原生端代码，如已在 HarmonyOS 工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。
+> 如未引入请参照 [@react-native-ohos/react-native-worklets文档的 Link 章节](../react-native-worklets//README.md)进行引入。
+
+<details>
+  <summary>ManualLink: 此步骤为手动配置原生依赖项的指导</summary>
+
+首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 `harmony`。
+
+### 1. Overrides RN SDK
+
+为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 `oh-package.json5` 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。
+
+关于该字段的作用请阅读[官方说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-oh-package-json5-V5#zh-cn_topic_0000001792256137_overrides)
+
+```json
+{
+  ...
+  "overrides": {
+    "@rnoh/react-native-openharmony" : "~0.84.2",
+    // version >= 4.0.0
+    "@react-native-ohos/react-native-worklets": "file:../node_modules/@react-native-ohos/react-native-worklets/harmony/worklets.har"
+  }
+}
+```
+
+### 2. 引入原生端代码
+
+目前有两种方法：
+
+- 通过 har 包引入；
+- 直接链接源码。
+
+方法一：通过 har 包引入（推荐）
+
+> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。
+
+打开 `entry/oh-package.json5`，添加以下依赖
+
+```json
+"dependencies": {
+    "@rnoh/react-native-openharmony": "~0.84.2",
+
+    "@react-native-ohos/react-native-reanimated": "file:../../node_modules/@react-native-ohos/react-native-reanimated/harmony/reanimated.har",
+  }
+```
+
+点击右上角的 `sync` 按钮
+
+或者在命令行终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+方法二：直接链接源码
+
+> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md)
+
+### 3. 配置 CMakeLists 和引入 ReanimatedPackage
+
+打开 `entry/src/main/cpp/CMakeLists.txt`，添加：
+
+```diff
+project(rnapp)
+cmake_minimum_required(VERSION 3.4.1)
+set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
++ set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
++ set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
+
+# (可选) 若开启对应SVG的Feature flags，需配置如下：
++ add_compile_definitions(REANIMATED_FEATURE_FLAGS="[RUNTIME_TEST_FLAG:false][DISABLE_COMMIT_PAUSING_MECHANISM:false][ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS:false][IOS_SYNCHRONOUSLY_UPDATE_UI_PROPS:false][EXPERIMENTAL_CSS_ANIMATIONS_FOR_SVG_COMPONENTS:true][IOS_CSS_CORE_ANIMATION:false][USE_SYNCHRONIZABLE_FOR_MUTABLES:true][USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS:true][ENABLE_SHARED_ELEMENT_TRANSITIONS:false][FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS:true][USE_ANIMATION_BACKEND:false]")
+
+add_subdirectory("${RNOH_CPP_DIR}" ./rn)
+
+# RNOH_END: manual_package_linking_1
+add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+
++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-reanimated/src/main/cpp" ./reanimated)
+
+# RNOH_END: manual_package_linking_1
+
+add_library(rnoh_app SHARED
+    "./PackageProvider.cpp"
+    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
+)
+
+target_link_libraries(rnoh_app PUBLIC rnoh)
+
+# RNOH_BEGIN: manual_package_linking_2
+target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
++ target_link_libraries(rnoh_app PUBLIC rnoh_reanimated)
+
+# RNOH_BEGIN: manual_package_linking_2
+```
+> [!Tip] 注意：上面RNOH_CPP_DIR定义，为RNOH框架的安装路径，用户可以根据安装的实际路径定义RNOH_CPP_DIR
+
+打开 `entry/src/main/cpp/PackageProvider.cpp`，添加：
+
+```diff
+#include "RNOH/PackageProvider.h"
+#include "SamplePackage.h"
++ #include "ReanimatedPackage.h"
+using namespace rnoh;
+
+std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
+    return {
+      std::make_shared<SamplePackage>(ctx),
++     std::make_shared<ReanimatedPackage>(ctx)
+    };
+}
+```
+
+### 4. 在 ArkTs 侧引入 ReanimatedPackage
+
+打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加：
+
+```diff
+  ...
++ import { ReanimatedPackage} from '@react-native-ohos/react-native-reanimated/ts';
+
+export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
+  return [
+    new SamplePackage(ctx),
++   new ReanimatedPackage(ctx),
+  ];
+}
+```
+
+</details>
+
+### 运行
+
+点击右上角的 `sync` 按钮
+
+或者在命令行终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+然后编译、运行即可。
+
+## 约束与限制
+
+### 兼容性
+
+本文档内容基于以下版本验证通过：
+
+1. RNOH: 0.84.2;  SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1.260; ROM: 6.0.0.130 SP15;
+
+### 权限要求
+
+> [!Tip] 使用传感器（`useAnimatedSensor`）的功能，需要使用 >= 4.0.0 的版本。在 `entry` 目录下的 `module.json5` 中添加权限
+
+```json
+"requestPermissions": [
+  {
+    "name": "ohos.permission.ACCELEROMETER",  // 加速度传感器权限名称
+    "reason": "$string:accele_reason",
+    "usedScene": {
+      "abilities": [
+        "EntryAbility"
+      ],
+      "when":"inuse"
+    }
+  },
+  {
+    "name": "ohos.permission.GYROSCOPE", // 陀螺仪传感器权限名称
+    "reason": "$string:gyr_reason",
+    "usedScene": {
+      "abilities": [
+        "EntryAbility"
+      ],
+      "when":"inuse"
+    }
+  },
+]
+```
+
+在 entry 目录下添加申请以上权限的原因，打开 `entry/src/main/resources/base/element/string.json`，添加：
+
+```json
+{
+  "string": [
+    {
+      "name": "accele_reason",
+      "value": "使用加速度传感器"
+    },
+    {
+      "name": "gyr_reason",
+      "value": "使用陀螺仪传感器"
+    },
+  ]
+}
+```
+
+## 使用示例
+
+下面的代码展示了这个库的基本使用场景：
+
+> [!WARNING] 使用时 import 的库名不变。
+
+```js
+import { Button, View } from "react-native";
+import Animated, { useSharedValue, withSpring } from "react-native-reanimated";
+
+export default function App() {
+  const width = useSharedValue(100);
+
+  const handlePress = () => {
+    width.value = withSpring(width.value + 50);
+  };
+
+  return (
+    <View style={{ flex: 1, alignItems: "center" }}>
+      <Animated.View
+        style={{
+          width,
+          height: 100,
+          backgroundColor: "violet",
+        }}
+      />
+      <Button onPress={handlePress} title="Click me" />
+    </View>
+  );
+}
+```
+
+## 接口说明
+
+> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。
+
+> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
+
+> 自 4.0.0 起，`runOnJS`、`runOnUI`、`runOnRuntime`、`executeOnUIRuntimeSync`、`createWorkletRuntime`、`isWorkletFunction`、`makeShareableCloneRecursive` 等线程调度 API 已迁移至 `react-native-worklets`，reanimated 中的同名导出仅为已废弃的兼容转发，其属性与用法请查阅 [react-native-worklets 文档](../react-native-worklets/README.md)，不再在本表列出。
+>
+> 
+
+### 属性
+
+#### Animated 组件（默认导出 `Animated`）
+
+| 名称                        | 参数类型              | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| --------------------------- | --------------------- | ------ | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `Animated.View`             | ViewProps + 动画样式  | none   | No   | All  | Yes               | 动画版 View 组件                                  |
+| `Animated.Text`             | TextProps + 动画样式  | none   | No   | All  | Yes               | 动画版 Text 组件                                  |
+| `Animated.Image`            | ImageProps + 动画样式 | none   | No   | All  | Yes               | 动画版 Image 组件                                 |
+| `Animated.ScrollView`       | AnimatedScrollViewProps + 动画样式 | none | No | All | Yes          | 动画版 ScrollView 组件，支持 `useScrollOffset`、`scrollTo` |
+| `Animated.FlatList`         | FlatListPropsWithLayout + 动画样式 | none | No | All | Yes          | 动画版 FlatList 组件，支持 `itemLayoutAnimation` 列表项布局动画 |
+| `Animated.createAnimatedComponent` | (component: ComponentType) => AnimatedComponent | none | No | All | Yes   | 将任意 RN 组件封装为动画组件                     |
+| `Animated.addWhitelistedNativeProps` | (props: Record<string, string>) => void | none | No | All | Yes | 扩展动画组件可直接更新的原生属性白名单           |
+| `Animated.addWhitelistedUIProps`     | (props: Record<string, string>) => void | none | No | All | Yes | 扩展动画组件可直接更新的 UI 属性白名单           |
+
+#### LayoutAnimationConfig 组件属性
+
+用于批量跳过子树的进入 / 退出动画：
+
+| 名称            | 参数类型    | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                          |
+| --------------- | ----------- | ------ | ---- | ---- | ----------------- | --------------------------------------------- |
+| `skipEntering`  | boolean     | false  | No   | All  | Yes               | 挂载时是否跳过子组件的进入动画                |
+| `skipExiting`   | boolean     | false  | No   | All  | Yes               | 卸载时是否跳过子组件的退出动画                |
+| `children`      | ReactNode   | none   | Yes  | All  | Yes               | 子组件                                        |
+
+#### PerformanceMonitor 组件属性
+
+| 名称             | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                       |
+| ---------------- | -------- | ------ | ---- | ---- | ----------------- | ------------------------------------------ |
+| `smoothingFrames` | number  | none   | No   | All  | Yes               | 用于 FPS 平滑统计的历史帧数，影响数值抖动程度 |
+
+#### ReducedMotionConfig 组件属性
+
+| 名称     | 参数类型      | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                       |
+| -------- | ------------- | ------ | ---- | ---- | ----------------- | ------------------------------------------ |
+| `mode`   | ReduceMotion  | none   | Yes  | All  | Yes               | 覆盖子树的减弱动态效果（无障碍）设置        |
+| `children` | ReactNode  | none   | No   | All  | Yes               | 子组件                                     |
+
+#### SharedTransitionBoundary 组件属性
+
+| 名称       | 参数类型    | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                       |
+| ---------- | ----------- | ------ | ---- | ---- | ----------------- | ------------------------------------------ |
+| `isActive` | boolean     | none   | Yes  | All  | Yes               | 边界是否激活（用于嵌套共享元素转场的边界判定）|
+| `children` | ReactNode   | none   | No   | All  | Yes               | 子组件                                     |
+
+#### WithTimingConfig（withTiming 配置）
+
+| 名称           | 参数类型                                 | 默认值              | 必填 | 平台 | HarmonyOS平台支持 | 描述                                          |
+| -------------- | ---------------------------------------- | ------------------- | ---- | ---- | ----------------- | --------------------------------------------- |
+| `duration`     | number                                   | 300                 | No   | All  | Yes               | 动画时长（毫秒）                              |
+| `easing`       | EasingFunction \| EasingFunctionFactory  | Easing.inOut(Easing.quad) | No | All | Yes          | 缓动曲线，需使用本库导出的 `Easing`          |
+| `reduceMotion` | ReduceMotion                             | ReduceMotion.System | No   | All  | Yes               | 减弱动态效果（无障碍）策略                    |
+
+#### WithSpringConfig（withSpring 配置）
+
+> 两组参数互斥：`stiffness + damping`（物理参数）或 `duration + dampingRatio`（时长参数）二选一。
+
+| 名称                  | 参数类型                  | 默认值              | 必填 | 平台           | HarmonyOS平台支持 | 描述                                                       |
+| --------------------- | ------------------------- | -------------------- | ---- | -------------- | ----------------- | ---------------------------------------------------------- |
+| `mass`                | number                    | 4                    | No   | Android and iOS | Yes               | 弹簧质量，越小动画越快                                     |
+| `stiffness`           | number                    | 900                  | No   | Android and iOS | Yes               | 弹簧刚度（与 damping 一组使用）                            |
+| `damping`             | number                    | 120                  | No   | Android and iOS | Yes               | 阻尼，越大越快静止（与 stiffness 一组使用）                |
+| `duration`            | number                    | 550                  | No   | Android and iOS | Yes               | 感知时长（毫秒），实际时长约为其 1.5 倍（与 dampingRatio 一组使用） |
+| `dampingRatio`        | number                    | 1                    | No   | Android and iOS | Yes               | 阻尼比：1 临界阻尼、<1 欠阻尼（回弹）、>1 过阻尼（与 duration 一组使用） |
+| `clamp`               | { min?: number, max?: number } | none            | No   | Android and iOS | Yes               | 位移限幅（仅与 duration + dampingRatio 组合时可用），超限时自动增大阻尼抑制回弹 |
+| `velocity`            | number                    | 0                    | No   | Android and iOS | Yes               | 初始速度                                                   |
+| `overshootClamping`   | boolean                   | false                | No   | Android and iOS | Yes               | 是否禁止越过 toValue 回弹                                  |
+| `energyThreshold`     | number                    | 6e-9                 | No   | Android and iOS | Yes               | 相对能量阈值，低于该阈值直接吸附到目标值                   |
+| `reduceMotion`        | ReduceMotion              | ReduceMotion.System  | No   | Android and iOS | Yes               | 减弱动态效果（无障碍）策略                                  |
+
+#### WithDecayConfig（withDecay 配置）
+
+| 名称               | 参数类型              | 默认值              | 必填 | 平台           | HarmonyOS平台支持 | 描述                                              |
+| ------------------ | --------------------- | -------------------- | ---- | -------------- | ----------------- | ------------------------------------------------- |
+| `velocity`         | number                | 0                    | No   | Android and iOS | Yes               | 初始速度                                          |
+| `deceleration`     | number                | 0.998                | No   | Android and iOS | Yes               | 减速率，速度随时间的衰减系数                      |
+| `clamp`            | [min: number, max: number] | []              | No   | Android and iOS | Yes               | 动画范围限幅；启用 rubberBandEffect 时必填        |
+| `velocityFactor`   | number                | 1                    | No   | Android and iOS | Yes               | 速度倍率，需大于 0                                |
+| `rubberBandEffect`  | boolean              | false                | No   | Android and iOS | Yes               | 到达 clamp 边界后的橡皮筋回弹效果                 |
+| `rubberBandFactor`  | number              | 0.6                  | No   | Android and iOS | Yes               | 橡皮筋效果强度（启用 rubberBandEffect 时可用）    |
+| `reduceMotion`     | ReduceMotion          | ReduceMotion.System  | No   | Android and iOS | Yes               | 减弱动态效果（无障碍）策略                        |
+
+#### withClamp / withRepeat / withDelay / withSequence 参数
+
+| 名称               | 所属 API      | 参数类型                        | 默认值  | 必填 | 平台           | HarmonyOS平台支持 | 描述                                              |
+| ------------------ | -------------- | ------------------------------- | ------- | ---- | -------------- | ----------------- | ------------------------------------------------- |
+| `min` / `max`      | withClamp      | number \| string                | none    | No   | Android and iOS | Yes               | 限幅上下界                                        |
+| `numberOfRepeats`  | withRepeat     | number                          | none    | Yes  | Android and iOS | Yes               | 重复次数，-1 表示无限重复                         |
+| `reverse`          | withRepeat     | boolean                         | false   | No   | Android and iOS | Yes               | 是否每次迭代反向播放                              |
+| `delay`            | withDelay      | number                          | none    | Yes  | Android and iOS | Yes               | 延迟时长（毫秒）                                  |
+| `callback`         | 全部动画函数   | (finished?: boolean, current?: AnimatableValue) => void | none | No | Android and iOS | Yes | 动画结束回调，被取消时入参为 false                |
+
+#### SensorConfig（useAnimatedSensor 配置）
+
+| 名称                        | 参数类型           | 默认值                  | 必填 | 平台           | HarmonyOS平台支持 | 描述                                                       |
+| --------------------------- | ------------------ | ----------------------- | ---- | -------------- | ----------------- | ---------------------------------------------------------- |
+| `interval`                  | number \| 'auto'   | 'auto'                  | No   | Android and iOS | Yes               | 采样间隔（毫秒），'auto' 由系统决定                        |
+| `adjustToInterfaceOrientation` | boolean          | true                    | No   | Android and iOS | Yes               | 传感器数值是否根据屏幕方向调整                             |
+| `iosReferenceFrame`         | IOSReferenceFrame  | IOSReferenceFrame.Auto  | No   | iOS            | No                | iOS 传感器姿态参考系，iOS 专属             |
+
+#### AnimatedSensor（useAnimatedSensor 返回值）
+
+| 名称          | 参数类型                              | 默认值 | 必填 | 平台           | HarmonyOS平台支持 | 描述                                              |
+| ------------- | ------------------------------------- | ------ | ---- | -------------- | ----------------- | ------------------------------------------------- |
+| `sensor`      | SharedValue&lt;Value3D \| ValueRotation&gt; | none | No  | Android and iOS | Yes          | 传感器数据共享值                                  |
+| `unregister`  | () => void                            | none   | No   | Android and iOS | Yes               | 注销传感器监听                                    |
+| `isAvailable` | boolean                               | false  | No   | Android and iOS | Yes               | 传感器是否可用（注册失败为 false）                |
+| `config`      | SensorConfig                          | none   | No   | Android and iOS | Yes               | 实际生效的配置（默认值与传入值合并）              |
+
+其中 `Value3D` 为 `{ x, y, z, interfaceOrientation }`；`ValueRotation` 为 `{ qw, qx, qy, qz, yaw, pitch, roll, interfaceOrientation }`。
+
+#### AnimatedKeyboardOptions / AnimatedKeyboardInfo（useAnimatedKeyboard）
+
+| 名称                             | 参数类型             | 默认值 | 必填 | 平台    | HarmonyOS平台支持 | 描述                                       |
+| -------------------------------- | -------------------- | ------ | ---- | ------- | ----------------- | ------------------------------------------ |
+| `isStatusBarTranslucentAndroid`  | boolean              | none   | No   | Android | Yes（忽略，无副作用） | Android 状态栏透明标志（Android 专属） |
+| `isNavigationBarTranslucentAndroid` | boolean           | none   | No   | Android | Yes（忽略，无副作用） | Android 导航栏透明标志（Android 专属） |
+| `height`（返回值）               | SharedValue&lt;number&gt; | 0     | No   | All     | Yes               | 键盘高度共享值                             |
+| `state`（返回值）                | SharedValue&lt;KeyboardState&gt; | KeyboardState.UNKNOWN | No | All | Yes      | 键盘状态共享值                             |
+
+#### SharedValue（useSharedValue 返回值）
+
+| 名称           | 参数类型                                                   | 默认值 | 必填 | 平台           | HarmonyOS平台支持 | 描述                                              |
+| -------------- | ---------------------------------------------------------- | ------ | ---- | -------------- | ----------------- | ------------------------------------------------- |
+| `value`        | Value                                                      | none   | No   | Android and iOS | Yes               | 读写共享值（写入触发 UI 线程同步更新）            |
+| `get`          | () => Value                                                | none   | No   | Android and iOS | Yes               | 获取当前值                                        |
+| `set`          | (value: Value \| ((value: Value) => Value)) => void         | none   | No   | Android and iOS | Yes               | 更新共享值，支持直接赋值或更新函数                |
+| `addListener`   | (listenerID: number, listener: (value: Value) => void) => void | none | No  | Android and iOS | Yes               | 注册值变化监听                                    |
+| `removeListener` | (listenerID: number) => void                             | none   | No   | Android and iOS | Yes               | 移除值变化监听                                    |
+| `modify`       | (modifier?: (value: Value) => Value, forceUpdate?: boolean) => void | none | No | Android and iOS | Yes        | 在 UI 线程上以原子方式修改当前值                  |
+
+#### Easing 缓动函数（Easing 对象成员）
+
+| 名称      | 参数类型                       | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                   |
+| --------- | ------------------------------ | ------ | ---- | ---- | ----------------- | -------------------------------------- |
+| `linear`  | () => EasingFunction           | none   | No   | All  | Yes               | 线性                                   |
+| `ease`    | () => EasingFunction           | none   | No   | All  | Yes               | 基础缓动                               |
+| `quad`    | () => EasingFunction           | none   | No   | All  | Yes               | 二次曲线                               |
+| `cubic`   | () => EasingFunction           | none   | No   | All  | Yes               | 三次曲线                               |
+| `poly`    | (n: number) => EasingFunction  | none   | No   | All  | Yes               | n 次曲线                               |
+| `sin`     | () => EasingFunction           | none   | No   | All  | Yes               | 正弦曲线                               |
+| `circle`  | () => EasingFunction           | none   | No   | All  | Yes               | 圆弧曲线                               |
+| `exp`     | () => EasingFunction           | none   | No   | All  | Yes               | 指数曲线                               |
+| `elastic` | (bounciness?: number) => EasingFunction | none | No  | All  | Yes          | 弹性曲线                               |
+| `back`    | (overshoot?: number) => EasingFunction   | none | No  | All  | Yes          | 回退曲线                               |
+| `bounce`  | () => EasingFunction           | none   | No   | All  | Yes               | 弹跳曲线                               |
+| `bezier`  | (x1, y1, x2, y2: number) => EasingFunctionFactory | none | No | All  | Yes        | 三阶贝塞尔曲线                         |
+| `bezierFn`| (x1, y1, x2, y2: number) => EasingFunction | none | No | All  | Yes        | 三阶贝塞尔曲线（直接返回函数，不带工厂信息） |
+| `steps`   | (n?: number, roundToNextStep?: boolean) => EasingFunction | none | No | All | Yes | 阶梯曲线                               |
+| `in`      | (easing: EasingFunction) => EasingFunction   | none | No | All  | Yes        | 先加速                                 |
+| `out`     | (easing: EasingFunction) => EasingFunction   | none | No | All  | Yes        | 先减速                                 |
+| `inOut`   | (easing: EasingFunction) => EasingFunction   | none | No | All  | Yes        | 先加速后减速                           |
+
+#### CSS 样式属性（css.create / createCSSAnimatedComponent）
+
+配合 `css.create` 创建的样式或 `createCSSAnimatedComponent` 封装的组件使用：
+
+| 名称                       | 参数类型                | 默认值 | 必填 | 平台           | HarmonyOS平台支持 | 描述                                       |
+| -------------------------- | ----------------------- | ------ | ---- | -------------- | ----------------- | ------------------------------------------ |
+| `transitionProperty`       | string \| string[]      | none   | No   | Android and iOS | Yes               | 参与过渡的样式属性名                       |
+| `transitionDuration`       | string \| number（ms）  | none   | No   | Android and iOS | Yes               | 过渡时长                                   |
+| `transitionDelay`          | string \| number（ms）  | none   | No   | Android and iOS | Yes               | 过渡开始前的延迟                           |
+| `transitionTimingFunction` | CSS timing function     | none   | No   | Android and iOS | Yes               | 过渡缓动函数                               |
+| `transitionBehavior`       | 'normal' \| 'allow-discrete' | none | No  | Android and iOS | Yes               | 是否对离散属性应用过渡                     |
+| `onTransitionRun`          | (event: { propertyName: string, elapsedTime: number }) => void | none | No | Web | No | 过渡触发回调 |
+| `onTransitionStart`        | (event: { propertyName: string, elapsedTime: number }) => void | none | No | Web | No | 延迟结束后过渡开始回调 |
+| `onTransitionEnd`          | (event: { propertyName: string, elapsedTime: number }) => void | none | No | Web | No | 过渡完成回调 |
+| `onTransitionCancel`       | (event: { propertyName: string, elapsedTime: number }) => void | none | No | Web | No | 过渡中断回调 |
+| `animationName`            | CSSKeyframesRule        | none   | No   | Android and iOS | Yes               | 关键帧动画（由 `css.keyframes` 创建）      |
+| `animationDuration`        | string \| number（ms）  | none   | No   | Android and iOS | Yes               | 动画时长                                   |
+| `animationDelay`           | string \| number（ms）  | none   | No   | Android and iOS | Yes               | 动画开始前的延迟                           |
+| `animationTimingFunction`  | CSS timing function     | none   | No   | Android and iOS | Yes               | 动画缓动函数                               |
+| `animationDirection`       | 'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse' | none | No | Android and iOS | Yes | 动画播放方向 |
+| `animationIterationCount`  | number \| 'infinite'    | none   | No   | Android and iOS | Yes               | 动画迭代次数                               |
+| `animationFillMode`        | 'none' \| 'forwards' \| 'backwards' \| 'both' | none | No | Android and iOS | Yes | 动画前后样式的保持策略 |
+| `animationPlayState`       | 'running' \| 'paused'   | none   | No   | Android and iOS | Yes               | 动画播放 / 暂停                            |
+
+#### CSS 样式伪类值（StyleWithPseudoValues）
+
+`css.create` 创建的样式或 `createCSSAnimatedComponent` 封装组件的内联 `style` 中，任意 CSS 样式属性的值可从单值扩展为"按交互态取值"的对象（至少写一个键），由原生侧跟踪指针悬停 / 按压链 / 焦点链自动切换，无需手写 state 与事件；可与 `transitionProperty` 联动实现状态切换过渡：
+
+```tsx
+backgroundColor: {
+  default: '#e7e7e7',
+  ':hover': '#b58df1',
+  ':active': '#61dafb',
+},
+```
+
+| 伪类键 | 触发条件 | 平台 | HarmonyOS平台支持 | 描述 |
+| ------ | -------- | ---- | ----------------- | ---- |
+| `default` | 无交互态时的基础值 | All | Yes | 伪类对象的基础值键 |
+| `:hover` | 指针悬停（含祖先链） | Android and iOS | Yes | 悬停高亮 |
+| `:active` | 按压自身或其后代期间（祖先链语义） | Android and iOS | Yes | 按压反馈 |
+| `:active-deepest` | 按压链上最深的已注册组件 | Android and iOS | Yes | 仅按压链最深处生效 |
+| `:focus` | 输入组件自身聚焦期间 | Android and iOS | Yes | 聚焦描边等 |
+| `:focus-within` | 后代存在聚焦期间 | Android and iOS | Yes | 容器级聚焦高亮 |
+
+### API
+
+#### 动画函数
+
+| 名称             | 类型     | 参数类型                                                                 | 返回值            | 必填 | 平台 | HarmonyOS平台支持 | 描述                                                     |
+| ---------------- | -------- | ------------------------------------------------------------------------ | ----------------- | ---- | ---- | ----------------- | -------------------------------------------------------- |
+| `withTiming`     | function | (toValue: AnimatableValue, config?: WithTimingConfig, callback?: AnimationCallback) | Animation | No | All | Yes | 基于时长与缓动曲线的动画                                 |
+| `withSpring`     | function | (toValue: AnimatableValue, config?: WithSpringConfig, callback?: AnimationCallback) | Animation | No | All | Yes | 基于弹簧模型的动画                                       |
+| `withDecay`      | function | (config: WithDecayConfig, callback?: AnimationCallback)                  | Animation         | No   | All  | Yes               | 带摩擦减速的衰减动画，常用于手势释放后的惯性滑动         |
+| `withRepeat`     | function | (animation: Animation, numberOfRepeats: number, reverse?: boolean, callback?: AnimationCallback) | Animation | No | All | Yes | 重复执行动画，numberOfRepeats 为 -1 时无限重复 |
+| `withSequence`   | function | (...animations: Animation[])                                             | Animation         | No   | All  | Yes               | 按顺序依次执行多个动画                                   |
+| `withDelay`      | function | (delay: number, animation: Animation)                                    | Animation         | No   | All  | Yes               | 延迟指定毫秒后执行动画                                   |
+| `withClamp`      | function | (config: { min?, max?, reduceMotion? }, animation: Animation)            | Animation         | No   | All  | Yes               | 限制内部动画的值域范围                                   |
+| `cancelAnimation`| function | (sharedValue: SharedValue) => void                                       | void              | No   | All  | Yes               | 取消共享值上正在运行的动画（异步生效）                   |
+| `defineAnimation`| function | (starting: AnimatableValue \| (() => Animation), factory: () => Animation) | Animation       | No   | All  | Yes               | 自定义动画的底层工厂（配合 custom animation 使用）       |
+
+#### Hooks
+
+| 名称                        | 类型     | 参数类型                                                                                  | 返回值                                     | 必填 | 平台 | HarmonyOS平台支持 | 描述                                                              |
+| --------------------------- | -------- | ----------------------------------------------------------------------------------------- | ------------------------------------------ | ---- | ---- | ----------------- | ----------------------------------------------------------------- |
+| `useSharedValue`            | function | (initialValue: Value)                                                                      | SharedValue&lt;Value&gt;                   | No   | All  | Yes               | 定义可在 JS 线程与 UI 线程间共享的值                              |
+| `useDerivedValue`           | function | (updater: () => Value, dependencies?: DependencyList)                                      | DerivedValue&lt;Value&gt;（只读）          | No   | All  | Yes               | 基于其他共享值派生新的响应式共享值                                |
+| `useAnimatedStyle`          | function | (updater: () => StyleProps, dependencies?: DependencyList)                                 | AnimatedStyle                              | No   | All  | Yes               | 创建由共享值驱动的动画样式                                        |
+| `useAnimatedProps`          | function | (updater: () => AnimatedProps, dependencies?: DependencyList)                              | AnimatedProps                              | No   | All  | Yes               | 创建可动画的组件属性（用于非样式属性，如 SVG 的 path）           |
+| `useAnimatedRef`            | function | ()                                                                                        | AnimatedRef&lt;T&gt;                       | No   | All  | Yes               | 获取动画组件引用，配合 measure、scrollTo、useScrollOffset 使用   |
+| `useAnimatedReaction`       | function | (prepare: () => PreparedResult, react: (prepared, previous) => void, dependencies?)        | void                                       | No   | All  | Yes               | 对共享值变化做出反应（在 UI 线程执行 react）                     |
+| `useAnimatedScrollHandler`  | function | (handlers: ScrollHandlers \| ScrollHandler, dependencies?)                                 | 事件处理器（传给 onScroll）                | No   | All  | Yes               | 创建滚动事件处理器，回调自动 worklet 化                          |
+| `useScrollOffset`           | function | (aref: AnimatedRef, providedOffset?: SharedValue&lt;number&gt;)                            | SharedValue&lt;number&gt;                  | No   | All  | Yes               | 读取滚动组件（ScrollView / FlatList 等）的滚动偏移              |
+| `useScrollViewOffset`       | function | 同 `useScrollOffset`（`useScrollOffset` 的废弃别名）                                        | SharedValue&lt;number&gt;                  | No   | All  | Yes               | 已废弃，请使用 `useScrollOffset`                                 |
+| `useAnimatedSensor`         | function | (sensorType: SensorType, config?: Partial&lt;SensorConfig&gt;)                             | AnimatedSensor                             | No   | All  | Yes               | 订阅设备传感器（加速度 / 陀螺仪 / 旋转等），需申请传感器权限    |
+| `useAnimatedKeyboard`       | function | (options?: AnimatedKeyboardOptions)                                                        | AnimatedKeyboardInfo                       | No   | All  | Yes               | 订阅键盘高度与状态                                               |
+| `useFrameCallback`          | function | (callback: (frameInfo: FrameInfo) => void, autostart?: boolean)                            | FrameCallback                              | No   | All  | Yes               | 每帧回调，返回 FrameCallback 对象：setActive / isActive / callbackId                      |
+| `useTimestamp`              | function | (isActive?: boolean)                                                                       | SharedValue&lt;number&gt;                  | No   | All  | Yes               | 每帧更新的时间戳共享值                                            |
+| `useReducedMotion`          | function | ()                                                                                        | boolean                                    | No   | All  | Yes               | 读取系统"减弱动态效果"无障碍设置                                 |
+| `useEvent`                  | function | (handler: EventHandler, eventNames?: readonly string[], rebuild?: boolean)                 | 事件处理器                                 | No   | All  | Yes               | 创建 worklet 化的底层事件处理器（自定义事件处理的基础）          |
+| `useHandler`                | function | (handlers: Record&lt;string, Handler&gt;, dependencies?: DependencyList)                    | { changedDepFlag } 等内部上下文            | No   | All  | Yes               | 供自定义 use*Handler 类 Hook 复用的底层 Hook                     |
+| `useComposedEventHandler`   | function | (handlers: (EventHandlerProcessed \| null)[])                                              | 组合后的事件处理器                         | No   | All  | Yes               | 将多个 useEvent 系事件处理器组合为单个处理器                     |
+
+#### 颜色工具
+
+| 名称              | 类型     | 参数类型                                                        | 返回值             | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| ----------------- | -------- | --------------------------------------------------------------- | ------------------ | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `interpolateColor`| function | (value, inputRange, outputRange, colorSpace?: 'RGB' \| 'HSV' \| 'LAB', options?) | string \| number | No | All | Yes | 颜色插值，支持 RGB / HSV / LAB 色彩空间          |
+| `processColor`    | function | (value: string \| number \| ColorValue, context?)               | number \| object \| false \| null | No | All | Yes | 将颜色值处理为可动画的内部表示 |
+| `PlatformColor`   | function | (...names: string[])                                            | OpaqueColorValue   | No   | All  | Yes               | 引用系统主题色（鸿蒙侧按系统资源色对齐处理）      |
+| `DynamicColorIOS` | function | (tuple: { light, dark, highContrastLight?, highContrastDark? }) | OpaqueColorValue   | No   | iOS  | **No**            | iOS 专属的深浅色自适应颜色，鸿蒙不支持            |
+| `convertToRGBA`   | function | (color: string \| number \| ParsedColorArray)                   | ParsedColorArray（RGBA 数组） | No | All | Yes | 将任意颜色转换为 RGBA 数组        |
+| `isColor`         | function | (value: unknown)                                                | boolean            | No   | All  | Yes               | 判断给定值是否为颜色                              |
+
+#### 插值工具
+
+| 名称           | 类型     | 参数类型                                                                     | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                                    |
+| -------------- | -------- | ---------------------------------------------------------------------------- | ------ | ---- | ---- | ----------------- | ------------------------------------------------------- |
+| `interpolate`  | function | (value: number, inputRange: number[], outputRange: number[], type?: ExtrapolationType) | number | No | All | Yes | 数值插值                                              |
+| `clamp`        | function | (value: number, min: number, max: number)                                    | number | No   | All  | Yes               | 将值限制在 [min, max] 区间内（可在 worklet 中使用）     |
+| `Extrapolation`| enum     | IDENTITY / CLAMP / EXTEND                                                     | -      | No   | All  | Yes               | 插值外推方式枚举                                        |
+| `Extrapolate`<sup>deprecated</sup> | enum     | 同 Extrapolation                                                              | -      | No   | All  | Yes               | 已废弃，请使用 `Extrapolation`                         |
+
+#### 布局动画构建器通用修饰方法
+
+以下静态方法在全部布局动画构建器（`Layout`、`FadeIn`、`BounceIn`、`SharedTransition` 等）上可用，链式调用：
+
+| 名称                       | 参数类型                                    | 返回值       | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| -------------------------- | ------------------------------------------- | ------------ | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `duration(ms)`             | number                                      | 构建器实例   | No   | All  | Yes               | 动画时长                                          |
+| `delay(ms)`                | number                                      | 构建器实例   | No   | All  | Yes               | 动画延迟                                          |
+| `easing(easing)`           | EasingFunctionFactory \| EasingFunction     | 构建器实例   | No   | All  | Yes               | 缓动曲线（ComplexAnimationBuilder 及其子类）      |
+| `springify()`              | -                                           | 构建器实例   | No   | All  | Yes               | 切换为弹簧动画（ComplexAnimationBuilder 及其子类）|
+| `damping(v)` / `stiffness(v)` / `mass(v)` | number                        | 构建器实例   | No   | All  | Yes               | 弹簧物理参数（springify 后生效）                  |
+| `dampingRatio(v)`          | number                                      | 构建器实例   | No   | All  | Yes               | 弹簧阻尼比（springify 后生效）                    |
+| `overshootClamping(v)` / `restDisplacementThreshold(v)` / `restSpeedThreshold(v)` / `energyThreshold(v)` | number | 构建器实例 | No | All | Yes | 弹簧细调参数（springify 后生效） |
+| `rotate(deg)`              | number \| string                            | 构建器实例   | No   | All  | Yes               | 入场旋转角度修正（ComplexAnimationBuilder 子类）  |
+| `reduceMotion(mode)`       | ReduceMotion                                | 构建器实例   | No   | All  | Yes               | 减弱动态效果策略                                  |
+| `withCallback(cb)`         | (finished: boolean) => void                 | 构建器实例   | No   | All  | Yes               | 动画结束回调                                      |
+| `withInitialValues(values)`| StyleProps                                  | 构建器实例   | No   | All  | Yes               | 指定起始样式（ComplexAnimationBuilder 子类）      |
+| `withTargetValues(values)` | StyleProps                                  | 构建器实例   | No   | All  | Yes               | 指定目标样式（ComplexAnimationBuilder 子类）      |
+| `randomDelay()`            | -                                           | 构建器实例   | No   | All  | Yes               | 随机延迟（用于列表错落动画）                      |
+| `getDuration()`            | -                                           | number       | No   | All  | Yes               | 读取构建器内部时长                                |
+
+#### 布局动画（进入 Entering）
+
+通过组件的 `entering` 属性使用：
+
+| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
+| ---- | ---- | -------- | ------ | ---- | ---- | ----------------- | ---- |
+| `BounceIn` | class | - | 构建器实例 | No | All | Yes | 弹跳进入 |
+| `BounceInDown` / `BounceInLeft` / `BounceInRight` / `BounceInUp` | class | - | 构建器实例 | No | All | Yes | 从下 / 左 / 右 / 上方向弹跳进入 |
+| `FadeIn` | class | - | 构建器实例 | No | All | Yes | 淡入 |
+| `FadeInDown` / `FadeInLeft` / `FadeInRight` / `FadeInUp` | class | - | 构建器实例 | No | All | Yes | 带位移的淡入 |
+| `FlipInEasyX` / `FlipInEasyY` | class | - | 构建器实例 | No | All | Yes | 轻量 X / Y 轴翻转入场 |
+| `FlipInXDown` / `FlipInXUp` / `FlipInYLeft` / `FlipInYRight` | class | - | 构建器实例 | No | All | Yes | X / Y 轴向翻转进入 |
+| `LightSpeedInLeft` / `LightSpeedInRight` | class | - | 构建器实例 | No | All | Yes | 光速左侧 / 右侧进入 |
+| `PinwheelIn` | class | - | 构建器实例 | No | All | Yes | 风车进入 |
+| `RollInLeft` / `RollInRight` | class | - | 构建器实例 | No | All | Yes | 滚动进入（左 / 右） |
+| `RotateInDownLeft` / `RotateInDownRight` / `RotateInUpLeft` / `RotateInUpRight` | class | - | 构建器实例 | No | All | Yes | 旋转进入 |
+| `SlideInDown` / `SlideInLeft` / `SlideInRight` / `SlideInUp` | class | - | 构建器实例 | No | All | Yes | 滑入（下 / 左 / 右 / 上） |
+| `StretchInX` / `StretchInY` | class | - | 构建器实例 | No | All | Yes | 拉伸进入 |
+| `ZoomIn` | class | - | 构建器实例 | No | All | Yes | 缩放进入 |
+| `ZoomInDown` / `ZoomInEasyDown` / `ZoomInEasyUp` / `ZoomInLeft` / `ZoomInRight` / `ZoomInRotate` / `ZoomInUp` | class | - | 构建器实例 | No | All | Yes | 各方向 / 轻量 / 旋转缩放进入 |
+
+#### 布局动画（退出 Exiting）
+
+通过组件的 `exiting` 属性使用，与进入动画一一对应：
+
+| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
+| ---- | ---- | -------- | ------ | ---- | ---- | ----------------- | ---- |
+| `BounceOut` / `BounceOutDown` / `BounceOutLeft` / `BounceOutRight` / `BounceOutUp` | class | - | 构建器实例 | No | All | Yes | 弹跳退出（各方向） |
+| `FadeOut` / `FadeOutDown` / `FadeOutLeft` / `FadeOutRight` / `FadeOutUp` | class | - | 构建器实例 | No | All | Yes | 淡出（各方向） |
+| `FlipOutEasyX` / `FlipOutEasyY` / `FlipOutXDown` / `FlipOutXUp` / `FlipOutYLeft` / `FlipOutYRight` | class | - | 构建器实例 | No | All | Yes | 翻转退出 |
+| `LightSpeedOutLeft` / `LightSpeedOutRight` | class | - | 构建器实例 | No | All | Yes | 光速退出 |
+| `PinwheelOut` | class | - | 构建器实例 | No | All | Yes | 风车退出 |
+| `RollOutLeft` / `RollOutRight` | class | - | 构建器实例 | No | All | Yes | 滚动退出 |
+| `RotateOutDownLeft` / `RotateOutDownRight` / `RotateOutUpLeft` / `RotateOutUpRight` | class | - | 构建器实例 | No | All | Yes | 旋转退出 |
+| `SlideOutDown` / `SlideOutLeft` / `SlideOutRight` / `SlideOutUp` | class | - | 构建器实例 | No | All | Yes | 滑出 |
+| `StretchOutX` / `StretchOutY` | class | - | 构建器实例 | No | All | Yes | 拉伸退出 |
+| `ZoomOut` / `ZoomOutDown` / `ZoomOutEasyDown` / `ZoomOutEasyUp` / `ZoomOutLeft` / `ZoomOutRight` / `ZoomOutRotate` / `ZoomOutUp` | class | - | 构建器实例 | No | All | Yes | 缩放退出（各方向 / 轻量 / 旋转） |
+
+#### 布局动画（布局过渡 Layout）与组合
+
+通过组件的 `layout` 属性使用；`EntryExitTransition` 可组合进入与退出动画，用于组件的 `entering` 与 `exiting`：
+
+| 名称                  | 类型   | 参数类型                                        | 返回值     | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| --------------------- | ------ | ----------------------------------------------- | ---------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `Layout`              | class | -                                               | 构建器实例 | No   | All  | Yes               | 默认布局过渡动画                                  |
+| `LinearTransition`    | class | -                                               | 构建器实例 | No   | All  | Yes               | 线性布局过渡                                      |
+| `CurvedTransition`    | class | -                                               | 构建器实例 | No   | All  | Yes               | 曲线布局过渡（速度插值）                          |
+| `SequencedTransition` | class | - | 构建器实例 | No   | All  | Yes               | 先旋转缩放后位移的分段过渡，reverse() 方法可反向                        |
+| `FadingTransition`    | class | -                                               | 构建器实例 | No   | All  | Yes               | 淡入淡出布局过渡                                  |
+| `JumpingTransition`   | class | -                                               | 构建器实例 | No   | All  | Yes               | 跳跃布局过渡                                      |
+| `EntryExitTransition` | class | - | 构建器实例 | No | All | Yes       | 组合进入与退出动画，经 entering() / exiting() 方法分别指定，同时用于 entering / exiting 属性 |
+| `Keyframe`            | class | (keyframes: Record&lt;string \| number, StyleProps&gt;) | 构建器实例 | No | All | Yes | 自定义关键帧布局动画，支持 '0%'–'100%' 或 0–1 关键帧 |
+| `BaseAnimationBuilder` | class | -                                              | 基类       | No   | All  | Yes               | 全部布局动画构建器的基类                          |
+| `ComplexAnimationBuilder` | class | -                                           | 基类       | No   | All  | Yes               | 支持 easing / springify 等复杂配置的构建器基类    |
+
+#### 共享元素转场
+
+通过组件的 `sharedTransitionTag` 字符串标签配对使用：
+
+| 名称                      | 类型   | 参数类型             | 返回值     | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| ------------------------- | ------ | -------------------- | ---------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `SharedTransition`        | class | -                    | 构建器实例 | No   | All  | Yes               | 共享元素转场动画，两个相同 sharedTransitionTag 的组件间平滑过渡 |
+| `SharedTransitionBoundary` | 组件  | 见属性章节           | ReactNode  | No   | All  | Yes               | 共享元素转场边界组件（嵌套场景）                  |
+
+#### UI 线程平台函数
+
+| 名称               | 类型     | 参数类型                                                        | 返回值                    | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| ------------------ | -------- | --------------------------------------------------------------- | ------------------------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `measure`          | function | (animatedRef: AnimatedRef)                                      | MeasuredDimensions \| null | No | All | Yes | 在 UI 线程同步获取组件的尺寸与位置（x, y, width, height, pageX, pageY） |
+| `scrollTo`         | function | (animatedRef, x: number, y: number, animated?: boolean)         | void                      | No   | All  | Yes               | 滚动到指定位置                                    |
+| `dispatchCommand`  | function | (animatedRef, commandName: string, args?: unknown[])            | void                      | No   | All  | Yes               | 同步调用组件的原生命令                            |
+| `setGestureState`  | function | (handlerTag: number, newState: number)                          | void                      | No   | All  | Yes               | 配合 RNGH 在 worklet 中更新手势状态               |
+| `setNativeProps`   | function | (animatedRef, updates: Record&lt;string, unknown&gt;)           | void                      | No   | All  | Yes               | 命令式更新组件属性                                |
+| `getRelativeCoords`| function | (animatedRef, absoluteX: number, absoluteY: number)             | ComponentCoords \| null   | No   | All  | Yes               | 计算相对于某组件的坐标                            |
+| `getViewProp`<sup>deprecated</sup> | function | (viewTag: number, propName: string, component?) => Promise      | Promise&lt;T&gt;     | No   | All  | Yes               | 读取视图属性（已废弃）                            |
+
+#### 核心与工具
+
+| 名称                           | 类型     | 参数类型                                          | 返回值                    | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| ------------------------------ | -------- | ------------------------------------------------- | ------------------------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `makeMutable`                  | function | (initialValue: Value)                             | SharedValue&lt;Value&gt;   | No  | All  | Yes               | 直接创建共享值（useSharedValue 的底层实现）       |
+| `isSharedValue`                | function | (value: unknown)                                  | boolean                   | No   | All  | Yes               | 判断给定值是否为共享值                            |
+| `createAnimatedComponent`      | function | (component: ComponentType, options?)             | AnimatedComponent          | No  | All  | Yes               | 将任意 RN 组件封装为动画组件                      |
+| `createAnimatedPropAdapter`    | function | (adapter: (props, config?) => void, props?: string[]) | PropAdapter           | No  | All  | Yes               | 创建 useAnimatedProps 的属性适配器                |
+| `startMapper`                  | function | (worklet, inputs?, outputs?)                      | number（mapperId）         | No | All  | Yes               | 注册 mapper（驱动动画的底层机制）                |
+| `stopMapper`                   | function | (mapperId: number)                                | void                      | No   | All  | Yes               | 注销 mapper                                       |
+| `isReanimated3`                | function | ()                                                | boolean                   | No   | All  | Yes               | 是否为 Reanimated 3（4.x 中恒为 false）           |
+| `isConfigured`                 | function | ()                                                | boolean                   | No   | All  | Yes               | 已废弃，等价于 isReanimated3                     |
+| `enableLayoutAnimations`       | function | (isEnabled?: boolean)                             | void                      | No   | All  | Yes               | 已废弃，4.x 中不再起作用                         |
+| `getUseOfValueInStyleWarning`  | function | ()                                                | string                    | No   | All  | Yes               | 返回"在样式中使用 .value"的警告文案（调试用）     |
+| `NativeEventsManager`          | class    | (component, options?)                             | 事件管理器实例             | No  | All  | Yes               | createAnimatedComponent 内部使用的事件管理器     |
+| `reanimatedVersion`            | const    | -                                                 | string                    | No   | All  | Yes               | 当前 reanimated 版本号字符串                     |
+
+#### Feature Flags
+
+| 名称                     | 类型     | 参数类型                            | 返回值  | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| ------------------------ | -------- | ----------------------------------- | ------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `getStaticFeatureFlag`  | function | (name: keyof StaticFeatureFlagsSchema) | boolean | No | All | Yes | 读取静态特性开关（编译期确定，需配合 CMake 宏 REANIMATED_FEATURE_FLAGS 配置） |
+| `setDynamicFeatureFlag` | function | (name: string, value: boolean)      | void    | No   | All  | Yes               | 动态设置特性开关                                  |
+| `getDynamicFeatureFlag` | function | (name: string)                      | boolean | No   | All  | Yes               | 读取动态特性开关                                  |
+
+静态开关：
+
+| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
+| ---- | -------- | ------ | ---- | ---- | ----------------- | ---- |
+| `RUNTIME_TEST_FLAG` | boolean | false | No | All | Yes | 运行时测试开关（上游测试用途，源码中无业务消费点），鸿蒙行为与上游一致 |
+| `DISABLE_COMMIT_PAUSING_MECHANISM` | boolean | false | No | All | Yes | 是否禁用 commit 暂停机制（动画更新高峰期暂停 React 提交、为动画让路的优化） |
+| `ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS` | boolean | false | No | Android | **No** | Android 专属：在 performOperations 中同步更新 UI 属性的实验优化；原生侧走 `#ifdef ANDROID` 分支，鸿蒙上不生效（与上游 iOS 行为一致，详见遗留问题） |
+| `IOS_SYNCHRONOUSLY_UPDATE_UI_PROPS` | boolean | false | No | iOS | Yes | 同步更新 UI 属性的实验优化； |
+| `EXPERIMENTAL_CSS_ANIMATIONS_FOR_SVG_COMPONENTS` | boolean | true | No | All | Yes | 对 SVG 组件启用实验性 CSS 动画/过渡（鸿蒙上需按 Link 章节配置 CMake 宏方可生效） |
+| `IOS_CSS_CORE_ANIMATION` | boolean | false | No | iOS | Yes | CSS 动画改用后端渲染； |
+| `USE_SYNCHRONIZABLE_FOR_MUTABLES` | boolean | true | No | All | Yes | 共享值（mutable）底层使用 worklets 提供的 Synchronizable 实现跨 runtime 读写 |
+| `USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS` | boolean | true | No | All | Yes | commit hook 仅拦截 React 提交，动画属性更新走独立通路（减少 hook 开销） |
+| `ENABLE_SHARED_ELEMENT_TRANSITIONS` | boolean | false | No | All | Yes | 启用共享元素转场引擎与 Experimental 布局动画代理；鸿蒙上需在 CMake 宏中显式置 true 方可生效，真机已验证 |
+| `FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS` | boolean | true | No | All | Yes | 动画结束后（settled）将最终属性经 React 渲染路径重新提交，保持 JS 与原生属性快照一致 |
+| `USE_ANIMATION_BACKEND` | boolean | false | No | All | **No** | 新一代统一动画后端；原生要求 RN ≥ 0.85.2 且开启 RN 侧 useSharedAnimatedBackend 特性开关，RNOH 0.84 无法启用（默认 false，无影响，详见遗留问题） |
+
+#### 日志
+
+| 名称                       | 类型     | 参数类型                                        | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                       |
+| -------------------------- | -------- | ----------------------------------------------- | ------ | ---- | ---- | ----------------- | ------------------------------------------ |
+| `configureReanimatedLogger`| function | (config: { level?: ReanimatedLogLevel, strict?: boolean }) | void | No | All | Yes | 配置 reanimated 日志级别与严格模式，全线程生效 |
+
+#### CSS 动画
+
+| 名称                        | 类型     | 参数类型                                                    | 返回值                | 必填 | 平台 | HarmonyOS平台支持 | 描述                                              |
+| --------------------------- | -------- | ----------------------------------------------------------- | --------------------- | ---- | ---- | ----------------- | ------------------------------------------------- |
+| `css.create`                | function | (styles: NamedStyles)                                        | 样式表对象            | No   | All  | Yes               | 创建含 CSS 过渡 / 动画属性的样式表                |
+| `css.keyframes`             | function | (definitions: CSSAnimationKeyframes)                         | CSSKeyframesRule       | No   | All  | Yes               | 创建 CSS 关键帧动画定义                           |
+| `createCSSAnimatedComponent`| function | (component: ComponentType)                                   | CSS 动画组件           | No   | All  | Yes               | 将 RN 组件封装为支持 CSS 动画 / 过渡的组件        |
+| `cubicBezier`               | function | (x1: number, y1: number, x2: number, y2: number)             | EasingFunctionFactory  | No   | All  | Yes               | CSS 三阶贝塞尔缓动                                |
+| `linear`                    | function | (...points: [number, number][])                              | EasingFunctionFactory  | No   | All  | Yes               | CSS 线性缓动（可带控制点）                        |
+| `steps`                     | function | (stepsNumber: number, modifier?: 'jump-start' \| 'jump-end' \| ...) | EasingFunctionFactory | No | All | Yes | CSS 阶梯缓动                                  |
+
+#### 屏幕转场
+
+| 名称                     | 类型     | 参数类型                                     | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                                        |
+| ------------------------ | -------- | -------------------------------------------- | ------ | ---- | ---- | ----------------- | ----------------------------------------------------------- |
+| `ScreenTransition`       | const    | -                                            | 预设集合 | No | All | Yes | 屏幕转场样式预设集合，成员：SwipeRight / SwipeLeft / SwipeDown / SwipeUp / Horizontal / Vertical / TwoDimensional / SwipeRightFade（每个成员含 topScreenStyle / belowTopScreenStyle 两个 worklet 样式函数） |
+| `startScreenTransition`  | function | (config: ScreenTransitionConfig)             | void   | No   | All  | Yes               | 开始屏幕转场（worklet）                                     |
+| `finishScreenTransition` | function | (config: ScreenTransitionConfig)             | void   | No   | All  | Yes               | 结束屏幕转场（worklet）                                     |
+
+#### Jest 测试工具
+
+| 名称                      | 类型     | 参数类型                    | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述                                                     |
+| ------------------------- | -------- | --------------------------- | ------ | ---- | ---- | ----------------- | -------------------------------------------------------- |
+| `setUpTests`              | function | (userConfig?)               | void   | No   | Jest 环境 | Yes          | 在 Jest 测试环境中初始化 reanimated 模拟 |
+| `withReanimatedTimer`     | function | (fn: () => void)            | void   | No   | Jest 环境 | Yes          | 单测中托管 reanimated 定时器 |
+| `advanceAnimationByTime`  | function | (time: number)              | void   | No   | Jest 环境 | Yes          | 将动画时间虚拟推进指定毫秒 |
+| `advanceAnimationByFrame` | function | (frames: number)            | void   | No   | Jest 环境 | Yes          | 将动画虚拟推进指定帧数   |
+| `getAnimatedStyle`        | function | (animatedRef)               | StyleProps | No | Jest 环境 | Yes          | 读取动画组件当前合成的样式 |
+
+### 枚举与常量
+
+| 名称                  | 类型 | 取值                                                                                          | 必填 | 平台           | HarmonyOS平台支持 | 描述                                       |
+| --------------------- | ---- | --------------------------------------------------------------------------------------------- | ---- | -------------- | ----------------- | ------------------------------------------ |
+| `SensorType`          | enum | ACCELEROMETER = 1, GYROSCOPE = 2, GRAVITY = 3, MAGNETIC_FIELD = 4, ROTATION = 5               | No   | Android and iOS | Yes               | 传感器类型（useAnimatedSensor 使用）       |
+| `IOSReferenceFrame`   | enum | XArbitraryZVertical = 0, XArbitraryCorrectedZVertical = 1, XMagneticNorthZVertical = 2, XTrueNorthZVertical = 3, Auto = 4 | No | iOS | No | iOS 传感器姿态参考系，iOS 专属（详见遗留问题） |
+| `KeyboardState`       | enum | UNKNOWN = 0, OPENING = 1, OPEN = 2, CLOSING = 3, CLOSED = 4                                   | No   | All            | Yes               | 键盘状态（useAnimatedKeyboard 返回）       |
+| `InterfaceOrientation`| enum | ROTATION_0 = 0, ROTATION_90 = 90, ROTATION_180 = 180, ROTATION_270 = 270                      | No   | All            | Yes               | 屏幕方向（传感器数值附带）                 |
+| `ReduceMotion`        | enum | System = 'system', Always = 'always', Never = 'never'                                          | No   | All            | Yes               | 减弱动态效果策略                           |
+| `ReanimatedLogLevel`  | enum | warn = 1, error = 2                                                                            | No   | All            | Yes               | 日志级别（configureReanimatedLogger 使用） |
+| `Extrapolation`       | enum | IDENTITY = 'identity', CLAMP = 'clamp', EXTEND = 'extend'                                      | No   | All            | Yes               | 插值外推方式                               |
+| `Easing`              | const | 见"Easing 缓动函数"章节                                                                        | No   | All            | Yes               | 缓动函数库对象                             |
+| `ScreenTransition`    | const | SwipeRight / SwipeLeft / SwipeDown / SwipeUp / Horizontal / Vertical / TwoDimensional / SwipeRightFade | No | All | Yes      | 屏幕转场样式预设集合                       |
+
+#### 弹簧动画预设常量
+
+| 名称                                       | 参数内容                                              | 必填 | 平台 | HarmonyOS平台支持 | 描述                                     |
+| ------------------------------------------ | ----------------------------------------------------- | ---- | ---- | ----------------- | ---------------------------------------- |
+| `GentleSpringConfig`                       | { damping: 120, mass: 4, stiffness: 900 }              | No   | All  | Yes               | 平缓柔和的弹簧效果（物理参数形式）       |
+| `GentleSpringConfigWithDuration`           | { duration: 550, dampingRatio: 1 }                     | No   | All  | Yes               | 平缓柔和的弹簧效果（时长参数形式）       |
+| `Reanimated3DefaultSpringConfig`           | { damping: 10, mass: 1, stiffness: 100 }               | No   | All  | Yes               | Reanimated 3 默认弹簧（高弹性、振荡明显）|
+| `Reanimated3DefaultSpringConfigWithDuration` | { duration: 1333, dampingRatio: 0.5 }                | No   | All  | Yes               | Reanimated 3 默认弹簧（时长参数形式）    |
+| `SnappySpringConfig`                       | { damping: 110, mass: 4, stiffness: 900, overshootClamping: true } | No | All | Yes       | "干脆利落"的快速弹簧效果                 |
+| `SnappySpringConfigWithDuration`           | { duration: 550, dampingRatio: 0.92, overshootClamping: true } | No | All | Yes       | "干脆利落"的快速弹簧（时长参数形式）     |
+| `WigglySpringConfig`                       | { damping: 90, mass: 4, stiffness: 900 }               | No   | All  | Yes               | "摇摆"回弹效果明显的弹簧                 |
+| `WigglySpringConfigWithDuration`           | { duration: 550, dampingRatio: 0.75 }                  | No   | All  | Yes               | "摇摆"回弹效果明显的弹簧（时长参数形式） |
+
+#### css 类型出口（TypeScript 类型）
+
+4.5.3 起新增的 css 相关类型出口（编译期类型，无运行时值），均可从包顶层直接导入：
+
+| 名称 | 类型 | 取值（结构） | 平台 | HarmonyOS平台支持 | 描述 |
+| ---- | ---- | ------------ | ---- | ----------------- | ---- |
+| `CSSPseudoSelectorKey` | type | 'default' \| ':hover' \| ':active' \| ':active-deepest' \| ':focus' \| ':focus-within'（native）+ 29 个 webonly 键（web） | All | Yes | CSS 样式伪类值的键类型（见"CSS 样式伪类值"章节） |
+| `CSSGradientStop` | type | { offset: NumberProp; color?: ColorValue \| number; opacity?: NumberProp } | All | Yes | SVG 渐变 stop 描述：offset 百分比 / 数值，color 颜色，opacity 透明度（与 color 的 alpha 相乘） |
+| `CSSLinearGradientProps` | type | { x1?, y1?, x2?, y2?, gradientUnits?, id?, gradient?: CSSGradientStop[] } | All | Yes | SVG 线性渐变可动画属性（渐变轴两端坐标、坐标单位、stop 数组），用作 CSS keyframes / animatedProps 的目标属性 |
+| `CSSRadialGradientProps` | type | { r?, rx?, ry?, cx?, cy?, fx?, fy?, gradientUnits?, id?, gradient?: CSSGradientStop[] } | All | Yes | SVG 径向渐变可动画属性（半径、圆心、焦点、stop 数组） |
+
+## 遗留问题
+
+1. `IOSReferenceFrame`（iOS）：该枚举是 iOS CoreMotion `CMAttitudeReferenceFrame` 的逐字映射，"姿态参考系"概念仅存在于 iOS；属于IOS独属概念。
+2. `DynamicColorIOS`（iOS）：`DynamicColorIOS`为 RN 仅 iOS 原生支持的动态颜色 API，JS 包装层调用不报错，但在鸿蒙、Android 等非 iOS 平台经`processColor`处理时会抛出 Reanimated 平台不兼容错误，属于上游通用限制。
+3. 不支持`ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS`（静态特性开关，Android）：Android 专属实验能力，在`performOperations`同步更新 UI 属性，仅 Android 编译分支生效，鸿蒙不支持，属于上游平台差异，已对等实现IOS平台同步更新UI的能力`IOS_SYNCHRONOUSLY_UPDATE_UI_PROPS`。
+4. 不支持`USE_ANIMATION_BACKEND`（静态特性开关）：新一代统一动画后端，要求 RN ≥0.85.2；RNOH 0.84 不满足条件，开启会触发原生断言，默认关闭，不影响现有功能。
+5. 不支持 CSS 过渡回调`onTransitionRun` / `onTransitionStart` / `onTransitionEnd` / `onTransitionCancel`：上游仅 web 端实现派发（映射 DOM `transitionrun` / `transitionstart` / `transitionend` / `transitioncancel` 事件），属于上游三端一致的实现现状。
+
+## 其他
+
+- [React Native 中 LayoutAnimation 与 react-native-reanimated 存在不兼容，推荐使用 react-native-reanimated](https://github.com/software-mansion/react-native-reanimated/issues/6751)
+
+## 目录结构
+
+````
+/rntpc_react-native-reanimated  # 项目根目录
+├── package
+│    ├── react-native-reanimated        # reanimated 鸿蒙适配包
+│    │    ├── harmony                    # 鸿蒙适配代码
+│    │    │    └─ reanimated.har         # har 包
+│    │    │    └─ reanimated             # 鸿蒙适配核心代码
+│    │    │          └─ src/main/cpp     # C++ 适配代码（ReanimatedPackage）
+│    │    │          └─ src/main/ets     # ArkTS 适配代码
+│    │    ├── src
+│    │    │    └─ index.ts               # 适配层入口（重导出上游 JS 导出）
+│    │    └── package.json
+│    └── react-native-worklets           # worklets 鸿蒙适配包（>= 4.0.0 必需）
+├── example                              # 示例工程
+└── README.OpenSource                    # 开源信息
+
+````
+
+## 贡献代码
+
+使用过程中发现任何问题都可以提交 [Issue](https://gitcode.com/CPF-RN/rntpc_react-native-reanimated/issues)，当然，也非常欢迎提交 [PR](https://gitcode.com/CPF-RN/rntpc_react-native-reanimated/pulls)。
+
+## 开源协议
+
+本项目基于 [The MIT License (MIT)](https://github.com/software-mansion/react-native-reanimated/blob/main/LICENSE) ，请自由地享受和参与开源。