模板版本:v0.4.0

react-native-worklets-core

本项目基于 react-native-worklets-core 开发。

该第三方库的仓库已迁移至 Gitcode,且支持直接从 npm 下载,新的包名为:@react-native-ohos/react-native-worklets-core。版本所属关系如下:

三方库名称 三方库版本 发布信息 支持RN版本 Autolink 编译API版本 社区基线版本 npm地址
@react-native-ohos/react-native-worklets-core ~ 1.6.0 Gitcode Releases 0.82.* API12+ 1.6.2 Npm Address
@react-native-ohos/react-native-worklets-core ~ 1.5.1 Gitcode Releases 0.77.* API12+ 1.5.0 Npm Address
@react-native-ohos/react-native-worklets-core ~ 1.3.4 Gitcode Releases 0.72.* API12+ 1.3.3 Npm Address
@react-native-oh-tpl/react-native-worklets-core <= 1.3.3-0.0.4@deprecated Github Releases(deprecated) 0.72.* API12+ 1.3.3 Npm Address

1. 安装与使用

进入到工程目录并输入以下命令:

npm

npm install @react-native-ohos/react-native-worklets-core

yarn

yarn add @react-native-ohos/react-native-worklets-core

在项目根目录下的 babel.config.js 中添加 babel 插件

module.exports = {
  plugins: [
    ["@react-native-ohos/react-native-worklets-core/plugin"],
    // ...
  ],
  // ...
};

重置缓存重启项目

yarn start --reset-cache

下面的代码展示了这个库的基本使用场景:

使用时 import 的库名不变。

import { useState } from "react";
import { Button, Text, View } from "react-native";
import { useRunOnJS, useWorklet } from "react-native-worklets-core";

const App = () => {
  // 计数器
  const [count, setCount] = useState(0);
  // 定义一个useRunJS方法
  const setCountRunInJS = useRunOnJS(() => {
    setCount(Math.random());
  }, [count]);
  // 在worklets线程使用RunInJS方法
  const countInWorkLet = useWorklet(
    "default",
    () => {
      "worklet";
      setCountRunInJS();
    },
    [setCountRunInJS]
  );

  return (
    <View>
      <View style={{ flexDirection: "row", gap: 10 }}>
        <Button title="SetCount" onPress={() => countInWorkLet()} />
      </View>
      <Text>count:{count}</Text>
    </View>
  );
};

export default App;
是否支持autolink RN框架版本
~1.6.0 0.82
~1.5.1 0.77
~1.3.4 0.72
<= 1.3.3-0.0.4@deprecated 0.72

使用AutoLink的工程需要根据该文档配置,Autolink框架指导文档:https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink,并且工程已接入 Autolink,可跳过ManualLink配置。

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony

1.在工程根目录的 oh-package.json5 添加 overrides 字段

{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
  }
}

2.引入原生端代码

目前有两种方法:

  1. 通过 har 包引入(在 IDE 完善相关功能后该方法会被遗弃,目前首选此方法);
  2. 直接链接源码。

方法一:通过 har 包引入

har 包位于三方库安装路径的 `harmony` 文件夹下。

打开 entry/oh-package.json5,添加以下依赖

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-worklets-core": "file:../../node_modules/@react-native-ohos/react-native-worklets-core/harmony/rn_worklets.har"
  }

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

方法二:直接链接源码

如需使用直接链接源码,请参考[直接链接源码说明](./link-source-code.md)

3.配置 CMakeLists 和引入 WorkletsPackage

若使用的是 <= 1.3.3-0.0.4 版本,请跳过本章。

打开 entry/src/main/cpp/CMakeLists.txt,添加:

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
>若使用RN框架版本是0.72或0.77,路径如下:
+ add_subdirectory("${OH_MODULE_DIR}/@react-native-ohos/react-native-worklets-core/src/main/cpp" ./worklets)
>若使用RN框架版本是0.82,路径如下:
+ add_subdirectory("${OH_MODULE_DIR}/@react-native-ohos/react-native-worklets-core/src/main/cpp" ./worklets_core)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./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)
>若使用RN框架版本是0.72或0.77,路径如下:
+ target_link_libraries(rnoh_app PUBLIC rnoh_worklets)
>若使用RN框架版本是0.82,路径如下:
+ target_link_libraries(rnoh_app PUBLIC rnoh_worklets_core)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp,添加:

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
>若使用RN框架版本是0.72或0.77,头文件路径如下:
+ #include "WorkletsPackage.h"
>若使用RN框架版本是0.82,头文件路径如下:
+ #include "WorkletsCorePackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
      std::make_shared<SamplePackage>(ctx),
      >若使用RN框架版本是0.72或0.77,请使用:
+     std::make_shared<WorkletsPackage>(ctx)
      >若使用RN框架版本是0.82,请使用:
+     std::make_shared<WorkletsCorePackage>(ctx)
    };
}

4.在 ArkTs 侧引入 WorkletsPackage

打开 entry/src/main/ets/RNPackagesFactory.ts,添加:

  ...
  >若使用RN框架版本是0.72或0.77,路径如下:
+ import { WorkletsPackage } from "@react-native-ohos/react-native-worklets-core/ts";
  >若使用RN框架版本是0.82,路径如下:
+ import { WorkletsCorePackage } from "@react-native-ohos/react-native-worklets-core/ts";

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    >若使用RN框架版本是0.72或0.77,路径如下:
+   new WorkletsPackage(ctx)
    >若使用RN框架版本是0.82,路径如下:
+   new WorkletsCorePackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

然后编译、运行即可。

3. 约束与限制

兼容性

要使用此库,需要使用正确的 React-Native 和 RNOH 版本。另外,还需要使用配套的 DevEco Studio 和 手机 ROM。

在以下版本验证通过:

  1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  2. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;
  3. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  4. RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.120 SP7;

API

"Platform"列表示该属性在原三方库上支持的平台。

"HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。

NAME Description Type Required Platform HarmonyOS Support
createContext 使用给定名称创建一个新的 worklet 上下文。 function no All yes
createSharedValue 创建一个可在不同运行时之间共享的值。 function no All yes
createRunOnJS 创建一个可在默认 React-JS 上下文中异步执行的函数。 function no All yes
runOnJS 在默认 React-JS 上下文中异步执行给定函数。 function no All yes
getCurrentThreadId 返回调用此方法的线程的唯一标识符。 function no All yes
defaultContext 获取默认的 Worklet 上下文。 interface no All yes
currentContext 获取当前的 Worklet 上下文,如果在主 React JS 上下文中调用则返回 undefined interface no All yes
__jsi_is_array 如果 jsi/cpp 认为传入的值是数组则返回 true。 function no All yes
__jsi_is_object 如果 jsi/cpp 认为传入的值是对象则返回 true。 function no All yes
context.addDecorator 向 worklet 上下文添加一个对象。该对象将在所有 worklet 中可用。 function no All yes
context.createRunAsync 创建一个可在 Worklet 上下文中异步执行的函数。 function no All yes
context.runAsync 在此 Worklet 上下文中异步运行给定的函数。 function no All yes
useWorklet 创建一个 Worklet 函数,该函数使用自动捕获的闭包自动记忆自身。 function no All yes
useRunOnJS 创建一个在 JS 上下文中运行给定函数的 Worklet 函数。 function no All yes
useSharedValue 创建一个在重新渲染之间持久存在的共享值。 function no All yes
isWorklet 检查给定函数是否为 Worklet。 function no All yes
worklet 确保给定函数是 Worklet,如果不是则抛出错误。 function no All yes
getWorkletDependencies 获取给定 worklet 的依赖项。 function no All yes

4. 遗留问题

5. 其他

6. 开源协议

本项目基于 The MIT License (MIT) ,请自由地享受和参与开源。