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

package/README.md

@@ -0,0 +1,470 @@
+> 文档模板：v0.4.2
+
+<p align="center">
+  <h1 align="center"> <code>react-native-reanimated</code> </h1>
+</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.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/CPF-RN/rntpc_react-native-reanimated/tree/br_rnoh0.82) |
+
+## 简介
+
+react-native-reanimated 是面向 React Native 生态的第三方原生库，重构实现跨平台动画底层能力，提供声明式 JS 动画 API，实现运行在 UI 线程的高性能流畅动画交互。
+
+## 下载安装
+
+> [!TIP] 注意：
+ `react-native-worklets` 已单独独立成库，需要单独引入，参照[@react-native-ohos/react-native-worklets文档](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/zh-cn/react-native-worklets.md)，目前只支持 Hermes，不支持切换至其他 JS 引擎切换。
+
+进入到工程目录并输入以下命令：
+
+**npm**
+
+```bash
+npm install react-native-reanimated@4.2.1
+npm install @react-native-ohos/react-native-reanimated
+```
+
+**yarn**
+
+```bash
+yarn add react-native-reanimated@4.2.1
+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.0.0                              | No             |  0.82     |
+
+首先需要使用 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" : "./react_native_openharmony",
+    "@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": "file:../react_native_openharmony",
+    "@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='[EXPERIMENTAL_CSS_ANIMATIONS_FOR_SVG_COMPONENTS:true][ENABLE_SHARED_ELEMENT_TRANSITIONS:false][DISABLE_COMMIT_PAUSING_MECHANISM:false][ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS:false][IOS_SYNCHRONOUSLY_UPDATE_UI_PROPS:false][USE_SYNCHRONIZABLE_FOR_MUTABLES:false][USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS:false][FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS:false]')
+
+add_subdirectory("${RNOH_CPP_DIR}" ./rn)
+
+# RNOH_BEGIN: 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_END: 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),
+  ];
+}
+```
+
+### 运行
+
+点击右上角的 `sync` 按钮
+
+或者在命令行终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+然后编译、运行即可。
+
+## 约束与限制
+
+### 兼容性
+
+本文档内容基于以下版本验证通过：
+
+1. RNOH: 0.82.7;  SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1.260; ROM: 6.0.0.130 SP15;
+
+### 权限要求
+
+> [!Tip] 使用传感器的功能，需要使用 >=4.0.0 的版本。如需使用传感器（如加速度传感器、陀螺仪），需要添加对应的传感器权限。
+
+在 `entry` 目录下的 `module.json5` 中添加权限
+
+```
+"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`，添加：
+```
+{
+  "string": [
++    {
++      "name": "accele_reason",
++      "value": "使用加速度传感器"
++    },
++    {
++      "name": "gyr_reason",
++      "value": "使用陀螺仪传感器"
++    },
+  ]
+}
+```
+
+### 编译运行API要求
+
+> [!TIP] 当前三方库所有版本均已实现版本隔离，支持在 `API12+` 工程编译，及 `API12+` ROM 运行。
+
+> [!TIP] 以下功能依赖特定版本的API，使用 `低于指定API版本的工程编译` 或 `低于指定API版本的ROM运行` 均可能导致部分功能受限。
+1. `4.0.2+` 版本新增支持 `useReducedMotion` API。该能力依托系统提供的 `isAnimationReduceEnabledSync` API 实现，用于检测设备是否开启减弱动效（reduced motion）辅助功能；该接口仅在 `API23 及以上版本的` ROM 环境中生效
+
+## 使用示例
+
+下面的代码展示了这个库的基本使用场景：
+
+> [!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] "平台"列表示该属性在原三方库上支持的平台。
+
+> [!TIP] "HarmonyOS平台支持"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
+
+### API
+
+| 名称               | 类型     | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
+| ------------------ |----------| -------- | ------ | -------- | -------- | ----------------- | ---- |
+| `withTiming`       | function | `(toValue: T, userConfig?: TimingConfig, callback?: AnimationCallback)` | `T` | No       | All      | yes | withTiming 可基于时长和缓动函数创建动画。 |
+| `withSpring`       | function | `(toValue: T, userConfig?: SpringConfig, callback?: AnimationCallback)` | `T` | No       | All      | yes | withSpring 可创建基于弹簧物理的动画。 |
+| `withDecay`        | function | `(userConfig: DecayConfig, callback?: AnimationCallback)` | `number` | No       | All      | yes | withDecay 可创建模拟带有摩擦力的运动物体的动画。动画将以给定的初速度开始，并根据给定的减速率随时间逐渐减速，直至停止。 |
+| `withRepeat`       | function | `(_animation: T, numberOfRepeats?: number, reverse?: boolean, callback?: AnimationCallback)` | `T` | No       | All      | yes | withRepeat 是一个动画修饰器，可将动画重复指定次数，或无限循环运行。 |
+| `useSharedValue`   | function | `(initialValue: Value)` | `SharedValue<Value>` | No       | All      | yes | useSharedValue 可在组件中定义共享值。 |
+| `useAnimatedStyle` | function | `(updater: () => Style, dependencies?: DependencyList)` | `Style` | No       | All      | yes | useAnimatedStyle 可创建一个样式对象（类似于 StyleSheet 样式），并可通过共享值对其进行动画处理。 |
+| `useAnimatedRef`   | function | `/` | `AnimatedRef<T>` | No       | All      | yes | useAnimatedRef 可获取视图的引用。可与 measure、scrollTo 和 useScrollViewOffset 函数配合使用。 |
+| `useDerivedValue`  | function | `(updater: () => Value, dependencies?: DependencyList)` | `DerivedValue<Value>` | No       | All      | yes | useDerivedValue 可基于已有的共享值创建新的共享值，并保持其响应性。 |
+| `cancelAnimation`  | function | `(sharedValue: SharedValue<TValue>)` | `void` | No       | All      | yes | cancelAnimation 可取消与某个共享值关联的正在运行的动画。 |
+| `runOnJS`<sup>deprecated</sup>           | function | `(fn: Function)` | `(...args: any[]) => void` | No       | All      | yes | runOnJS 可异步运行未被 worklet 化的函数（这些函数通常无法在 UI 线程上运行）。这适用于大多数外部库，因为它们的函数未标记 "worklet" 指令。 |
+| `runOnUI`<sup>deprecated</sup>            | function | `(fn: Function)` | `(...args: any[]) => void` | No       | All      | yes | runOnUI 可在 UI 线程上异步运行被 worklet 化的函数。 |
+| `measure`          | function | `(animatedRef: AnimatedRef<TRef>)` | `MeasuredDimensions \| null` | No       | All      | yes | measure 可在 UI 线程上同步获取屏幕上视图的尺寸和位置。 |
+| `Easing`           | object | `/` | `/` | No       | All      | yes | 缓动函数，用于设置运动的轨迹。 |
+| `useAnimatedKeyboard`           | function | `(options?: AnimatedKeyboardOptions)` | `AnimatedKeyboardInfo` | No       | All      | yes | useAnimatedKeyboard 可基于虚拟键盘的状态和高度创建动画。 |
+| `useComposedEventHandler`| function | `(handlers: (EventHandlerProcessed \| null)[])` | `ComposedHandlerProcessed` | No       | All      | yes | 这是一个 Hook，可将基于 useEvent 的事件处理器（如 useAnimatedScrollHandler 或自定义事件处理器）组合为一个单一的事件处理器。 |
+| `makeMutable` | function | `(initial: Value)` | `Mutable<Value>` | No       | All      | yes | makeMutable 是 useSharedValue Hook 内部用于创建共享值的函数。 |
+| `ReducedMotionConfig` | function | `(config: ReducedMotionConfig)` | `null` | No       | All      | yes | 根据设备的减弱动效辅助功能设置改变行为。 |
+| `useAnimatedGestureHandler`<sup>deprecated</sup> | function | `(handlers: GestureHandlers, config?: Config)` | `OnGestureEvent` | No | All | No | 可基于手势处理器创建动画。 |
+| `useScrollViewOffset` <sup> deprecated </sup> | function | `(animatedRef: AnimatedRef<AnimatedScrollView>, providedOffset?: SharedValue<number>)` | `SharedValue<number>` | No | All | yes | 可基于 ScrollView 的偏移量创建动画。 |
+| `useScrollOffset`  | function | `(animatedRef: AnimatedRef<TRef>, providedOffset?: SharedValue<number>)` | `SharedValue<number>` | No | All | yes | 可基于可滚动组件（如 ScrollView、FlatList、FlashList）的偏移量创建动画。 |
+| `createAnimatedComponent `  | function | `(Component: React.ComponentType, options?: Options)` | `AnimatedComponentType` | No | All | yes | 可为任意 React Native 组件创建动画版本。 |
+| `getStaticFeatureFlag`  | function | `(name: keyof StaticFeatureFlagsSchema)` | `boolean` | No | All | yes | 用于获取静态功能标志（feature flags）的函数。 |
+| `setDynamicFeatureFlag`  | function | `(name: DynamicFlagName, value: boolean)` | `void` | No | All | yes | 用于动态设置功能标志的函数。 |
+| `reanimatedVersion`  | string | `/` | `/` | No | All | yes | 获取动画库的版本号。 |
+| `useAnimatedProps`  | function | `(updater: () => AnimatedProps, dependencies?: DependencyList)` | `AnimatedProps` | No | All | yes | React Native Reanimated 库中的一个自定义 Hook，用于创建可动画化的组件属性。 |
+| `useReducedMotion`<sup>API>=23</sup>  | function | `/` | `boolean` | No | All | yes | React Native Reanimated 库中的一个 Hook，用于检测设备是否启用了减弱动效（reduced motion）辅助功能设置。 |
+
+### 属性
+
+**WithSpringConfig**
+
+| 名称                    | 参数类型                                                  | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ----------------------- | ------------------------------------------------------------ | ---------------- | -------- | --------------- | ------------------ | ---- |
+| clamp | `{ min?: number; max?: number }` | None | No       | Android and iOS | yes | 限制运动范围。如果弹簧动画会超出此限制，则会降低 `dampingRatio`（使弹簧的弹性减弱） |
+
+**SharedValue**
+
+| 名称                  | 参数类型                                                  | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| --------------------- | ------------------------------------------------------------ | -------- | -------- | --------------- | ------------------ | ---- |
+| 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 | 注册值变化监听器 |
+| modify                | `(modifier?: (value: Value) => Value, forceUpdate?: boolean) => void` | None | No       | Android and iOS | yes | 对当前值应用变换 |
+
+**DerivedValue**
+
+| 名称                                 | 参数类型                 | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------ | --------------------------- | -------- | -------- | --------------- | ------------------ | ---- |
+| set<sup>deprecated</sup> | None | None | No       | Android and iOS | No | 派生值为只读 |
+
+**CurrentLayoutAnimationsValues**
+
+| 名称                                  | 参数类型           | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------- | --------------------- | ------ | -------- | --------------- | ------------------ | ---- |
+| currentBorderRadius | number | 0 | No       | Android and iOS | No | 视图的圆角半径 |
+
+**EntryAnimationsValues**
+
+| 名称                                 | 参数类型           | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------ | --------------------- | ------ | -------- | --------------- | ------------------ | ---- |
+| targetBorderRadius | number | 0 | No       | Android and iOS | No | 视图的圆角半径 |
+
+**itemLayoutAnimation**
+
+| 名称                                  | 参数类型                               | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------- | ----------------------------------------- | --------------- | -------- | --------------- | ------------------ | ---- |
+| itemLayoutAnimation | `ILayoutAnimationBuilder` | None | No       | Android and iOS | yes | 定义列表项的布局过渡动画 |
+
+
+**CSS Transitions**
+| 名称                                  | 参数类型                               | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------- | ----------------------------------------- | --------------- | -------- | --------------- | ------------------ | ---- |
+| transitionProperty | `'all' \| 'none' \| keyof S \| string[]` | None | No       | Android and iOS | yes | 用于指定要进行过渡动画的样式属性名称。 |
+| transitionDuration | `TimeUnit`（`${number}s` / `${number}ms` / number） | None | No       | Android and iOS | yes | 用于指定过渡动画持续的时间长度。 |
+| transitionDelay | `TimeUnit`（`${number}s` / `${number}ms` / number） | None | No       | Android and iOS | yes | 用于指定过渡动画开始前的等待时间。 |
+| transitionTimingFunction | `CSSTimingFunction` | None | No | Android and iOS | yes | 用于调整过渡过程中中间值的计算方式。 |
+| transitionBehavior | `'normal' \| 'allow-discrete'` | None | No | Android and iOS | yes | 用于确定过渡动画是否应用于离散属性。 |
+
+
+**CSS Animations**
+| 名称                                  | 参数类型                               | 默认值 | 必填 | 平台        | HarmonyOS平台支持 | 描述 |
+| ------------------------------------- | ----------------------------------------- | --------------- | -------- | --------------- | ------------------ | ---- |
+| animationName  | `CSSKeyframesRule \| CSSAnimationKeyframes \| 'none'` | None | No       | Android and iOS | yes | 用于指定动画的关键帧。 |
+| animationDuration | `TimeUnit`（`${number}s` / `${number}ms` / number） | None | No    | Android and iOS | yes | 用于指定动画持续的时间长度。 |
+| animationDelay | `TimeUnit`（`${number}s` / `${number}ms` / number） | None | No       | Android and iOS | yes | 用于指定动画开始前的等待时间。 |
+| animationTimingFunction | `CSSTimingFunction` | None | No | Android and iOS | yes | 用于调整动画过程中中间值的计算方式。 |
+| animationDirection  | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` | None | No | Android and iOS | yes | 用于指定动画的运行方向。 |
+| animationIterationCount  | `'infinite' \| number` | 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 | 用于播放和暂停动画。 |
+
+**Common object**
+| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
+| ------- | --------------------- | --------------- | -------- | --------------- | ------------------ | ---- |
+| `GentleSpringConfig`  |  `SpringConfig` | `{ damping: 120, mass: 4, stiffness: 900 }` | No | All | yes | 这是一个预定义的弹簧动画配置，用于创建平滑、柔和的弹簧效果。 |
+| `GentleSpringConfigWithDuration`  |  `SpringConfig` | `{ duration: 550, dampingRatio: 1 }` | No | All | yes | 这是 GentleSpringConfig 的另一种形式，使用 duration 和 dampingRatio 参数来定义弹簧动画。 |
+| `Reanimated3DefaultSpringConfig`  |  `SpringConfig` | `{ damping: 10, mass: 1, stiffness: 100 }` | No | All | yes | 会生成一个高弹性且具有明显振荡的动画。 |
+| `Reanimated3DefaultSpringConfigWithDuration`  | `SpringConfig` | `{ duration: 1333, dampingRatio: 0.5 }` | No | All | yes | 会生成一个灵活的动画。 |
+| `SnappySpringConfig`  | `SpringConfig` | `{ damping: 110, mass: 4, stiffness: 900, overshootClamping: true }` | No | All | yes | 该配置定义了“敏捷”（Snappy）的弹簧动画。 |
+| `SnappySpringConfigWithDuration`  | `SpringConfig` | `{ duration: 550, dampingRatio: 0.92, overshootClamping: true }` | No | All | yes | 该配置定义了“快速”（Snappy）的弹簧动画。 |
+| `WigglySpringConfig` | `SpringConfig` | `{ damping: 90, mass: 4, stiffness: 900 }` | No | All | yes | 该配置定义了“摇摆”（Wiggly）的弹簧动画，会产生明显的摇摆/弹跳效果。 |
+| `WigglySpringConfigWithDuration` | `SpringConfig` | `{ duration: 550, dampingRatio: 0.75 }` | No | All | yes | 该配置定义了“摇摆”（Wiggly）的弹簧动画，会在 550ms 内完成动画，并产生明显的振荡效果（欠阻尼） |
+| `EasingFunctionFactory`  | `{ factory: () => EasingFunction }` | None | No | All | yes | 库中的一个类型定义，用作创建缓动函数的工厂函数 |
+| `EntryOrExitLayoutType`  | `BaseAnimationBuilder \| typeof BaseAnimationBuilder \| EntryExitAnimationFunction \| ReanimatedKeyframe` | None | No | All | yes | 一个组合类型，用于定义进入或退出动画的类型 |
+| `DynamicColorIOS`  | `(tuple: DynamicColorIOSTuple) => OpaqueColorValue` | None | No | iOS | no | 专为在 Reanimated 中使用而设计，用于定义能够自动适应 iOS 浅色和深色模式的颜色 |
+
+## 遗留问题
+
+## 其他
+- [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               # 鸿蒙适配核心代码
+│   │   │       ├── index.ets            # 鸿蒙适配代码入口
+│   │   │       └── src/main
+│   │   │           ├── cpp              # C++ 原生层（ReanimatedPackage、ReanimatedModule 等）
+│   │   │           ├── ets              # ArkTS 层
+│   │   │           └── module.json5
+│   │   ├── src                          # RN / TS 代码
+│   │   │   └── index.ts                 # 入口文件
+│   │   └── package.json
+│   └── react-native-worklets            # worklets 依赖（需单独引入）
+│       ├── harmony                      # 鸿蒙适配代码
+│       │   ├── worklets.har             # har 包
+│       │   └── worklets                 # 鸿蒙适配核心代码
+│       │       ├── index.ets            # 鸿蒙适配代码入口
+│       │       └── src/main
+│       │           ├── cpp              # C++ 原生层
+│       │           ├── ets              # ArkTS 层
+│       │           └── module.json5
+│       ├── src                          # RN / TS 代码
+│       │   └── index.ts                 # 入口文件
+│       └── package.json
+├── example                              # 示例工程
+├── README.md                            # 中文安装使用方法
+├── README_en.md                         # 英文安装使用方法
+├── CHANGELOG.md                         # 更新日志
+└── OAT.xml                              # 开源合规
+````
+
+## 贡献代码
+
+使用过程中发现任何问题都可以提交 [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) ，请自由地享受和参与开源。

package/harmony/reanimated/BuildProfile.ets

@@ -1,7 +1,7 @@
 /**
  * Use these variables when you tailor your ArkTS code. They must be of the const type.
  */
-export const HAR_VERSION = '4.0.2';
+export const HAR_VERSION = '4.0.3-beta.1';
 export const BUILD_MODE_NAME = 'debug';
 export const DEBUG = true;
 export const TARGET_NAME = 'default';

package/harmony/reanimated/oh-package.json5

@@ -1,6 +1,6 @@
 {
   name: '@react-native-ohos/react-native-reanimated',
-  version: '4.0.2',
+  version: '4.0.3-beta.1',
   description: "",
   type: 'module',
   main: 'index.ets',

package/harmony/reanimated/src/main/cpp/ReanimatedModule.cpp

@@ -115,11 +115,12 @@ void ReanimatedModule::installTurboModule(facebook::jsi::Runtime &rt) {
             self->keyboardEventDataUpdater_ = std::move(keyboardEventDataUpdater);
             auto weakExecutor = std::weak_ptr(self->m_ctx.taskExecutor);
             if (auto taskExecutor = weakExecutor.lock()) {
-                taskExecutor->runTask(TaskThread::MAIN, [ctx = self->m_ctx, isStatusBarTranslucent]() {
+                taskExecutor->runTask(TaskThread::MAIN, [ctx = self->m_ctx, isStatusBarTranslucent, isNavigationBarTranslucent]() {
                     ArkJS arkJs(ctx.env);
-                    // arkJs.createBoolean(isStatusBarTranslucent);
+                    auto napiStatusBarTranslucent = arkJs.createBoolean(isStatusBarTranslucent);
+                    auto napiNavigationBarTranslucent = arkJs.createBoolean(isNavigationBarTranslucent);
                     auto napiTurboModuleObject = arkJs.getObject(ctx.arkTSTurboModuleInstanceRef);
-                    napiTurboModuleObject.call("subscribeKeyBordListeners", {});
+                    napiTurboModuleObject.call("subscribeKeyBordListeners", {napiStatusBarTranslucent, napiNavigationBarTranslucent});
                 });
             }
             return 0;

package/harmony/reanimated/src/main/cpp/ReanimatedSensor.cpp

@@ -52,54 +52,21 @@ void SensorDataCallbackImpl(Sensor_Event *event) {
     }
 
     switch (sensorType) {
-    case SENSOR_TYPE_ACCELEROMETER: {
-        double sendData[] = {
-            data[0],
-            data[1],
-            data[2],
-        };
-        sensorInstance->runSensor(sendData);
-        return;
-    }
-    case SENSOR_TYPE_GYROSCOPE: {
-        double sendData[] = {
-            data[0],
-            data[1],
-            data[2],
-        };
-        sensorInstance->runSensor(sendData);
-        return;
-    }
-    case SENSOR_TYPE_GRAVITY: {
-        double sendData[] = {
-            data[0],
-            data[1],
-            data[2],
-        };
-        sensorInstance->runSensor(sendData);
-        return;
-    }
+    case SENSOR_TYPE_ACCELEROMETER:
+    case SENSOR_TYPE_GYROSCOPE:
+    case SENSOR_TYPE_GRAVITY:
     case SENSOR_TYPE_MAGNETIC_FIELD: {
-        double sendData[] = {
-            data[0],
-            data[1],
-            data[2],
-        };
-        sensorInstance->runSensor(sendData);
+        if (length < 3) {
+            return;
+        }
+        sensorInstance->runSensor({data[0], data[1], data[2]});
         return;
     }
     case SENSOR_TYPE_ROTATION_VECTOR: {
-        double sendData[] = {
-            data[0], // x
-            data[1], // y
-            data[2], // z
-            data[3], // w
-            // ios
-            0, // yaw
-            0, // pitch
-            0  // roll
-        };
-        sensorInstance->runSensor(sendData);
+        if (length < 4) {
+            return;
+        }
+        sensorInstance->runSensor({data[0], data[1], data[2], data[3], 0, 0, 0});
         return;
     }
     default:
@@ -214,18 +181,48 @@ bool rnoh::ReanimatedSensor::isSupportSensor() {
     return isSupport;
 }
 
-void rnoh::ReanimatedSensor::runSensor(double *value) {
-    if (value && setter_ && runOnTheMainThread_) {
-        runOnTheMainThread_([weakSelf = weak_from_this(), value]() {
+void rnoh::ReanimatedSensor::runSensor(std::vector<double> value) {
+    if (!value.empty() && setter_ && runOnTheMainThread_) {
+        runOnTheMainThread_([weakSelf = weak_from_this(), value = std::move(value)]() mutable {
             auto self = weakSelf.lock();
             if (!self) {
                 return;
             }
-            self->setter_(value, self->getInterfaceOrientation());
+            try {
+                self->setter_(value.data(), self->getInterfaceOrientation());
+            } catch (const std::exception& e) {
+                LOG(ERROR) << "ReanimatedSensor::runSensor: setter_ exception: " << e.what();
+            }
         });
     }
 }
 
+/**
+ * @deprecated: 改用 `runSensor(std::vector<double> value)`。
+ * 按 sensorType_ 推导元素个数，拷贝到堆上 vector 后委托给新接口，
+ * 避免外部旧调用方因签名变更编译失败。
+ */
+void rnoh::ReanimatedSensor::runSensor(double *value) {
+    if (value == nullptr) {
+        return;
+    }
+    size_t length = 0;
+    switch (sensorType_) {
+    case SENSOR_TYPE_ACCELEROMETER:
+    case SENSOR_TYPE_GYROSCOPE:
+    case SENSOR_TYPE_GRAVITY:
+    case SENSOR_TYPE_MAGNETIC_FIELD:
+        length = 3;
+        break;
+    case SENSOR_TYPE_ROTATION_VECTOR:
+        length = 7;
+        break;
+    default:
+        return;
+    }
+    runSensor(std::vector<double>(value, value + length));
+}
+
 int rnoh::ReanimatedSensor::getInterfaceOrientation() {
     NativeDisplayManager_Rotation rotation;
     auto ret = OH_NativeDisplayManager_GetDefaultDisplayRotation(&rotation);

package/harmony/reanimated/src/main/cpp/ReanimatedSensor.h

@@ -6,6 +6,7 @@
 #define HARMONY_REANIMATEDSENSOR_H
 #include <functional>
 #include <mutex>
+#include <vector>
 #include <sensors/oh_sensor_type.h>
 #include "RNOH/TaskExecutor/TaskExecutor.h"
 
@@ -18,6 +19,17 @@ public:
     bool initialize();
     void cancel();
     void castSensorType(int sensorType);
+    /**
+     * @brief 传入传感器数据，异步投递到主线程执行 setter_。
+     * @param value 传感器数据（按值捕获，生命周期随 lambda 绑定）。
+     */
+    void runSensor(std::vector<double> value);
+    /**
+     * @deprecated: 改用 `runSensor(std::vector<double> value)`。
+     * 保留以免外部 C++ 插件因签名变更编译失败。内部按 sensorType_ 推导
+     * 数据元素个数后拷贝到堆上 vector，再委托给新接口。
+     * 调用方需保证 value 在本函数返回前有效（返回后已拷贝无需保持）。
+     */
     void runSensor(double *value);
     std::function<void(double[], int)> setter_;
     Sensor_Type sensorType_{SENSOR_TYPE_ACCELEROMETER};