diff --git a/en/react-native-background-timer.md b/en/react-native-background-timer.md index 2039ce45981c9fe319e1516fb10d1007c6230602..091800818679c0ef4afea55797fcb6c0833ea041 100644 --- a/en/react-native-background-timer.md +++ b/en/react-native-background-timer.md @@ -6,12 +6,15 @@ This project is based on [react-native-background-timer@2.4.1](https://github.com/ocetnik/react-native-background-timer)。 -This third-party library has been migrated to Gitee and is now available for direct download from npm, the new package name is: `@react-native-ohos/react-native-linear-gradient`, The version correspondence details are as follows: +This third-party library has been migrated to Gitee and is now available for direct download from npm, the new package name is: `@react-native-ohos/react-native-background-timer`, The version correspondence details are as follows: -| Version | Package Name | Repository | Release | -| ------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| <= 2.4.1-0.0.2@deprecated | @react-native-oh-tpl/react-native-background-timer | [Github(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer/releases) | -| > 2.4.2 | @react-native-ohos/react-native-background-timer | [Gitee](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer) | [Gitee Releases](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/releases) | +| Version | Releases info | Support RN version | +| ---------- | ------------------------------------------------------------ | ---------- | +| <= 2.4.1-0.0.2@deprecated | [@react-native-oh-tpl/react-native-background-timer Releases(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer/releases) | 0.72 | +| > 2.5.0 | [@react-native-ohos/react-native-background-timer Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-background-timer/releases) | 0.77 | + + +For older versions that are not published to npm, please refer to the [installation guide](/en/tgz-usage-en.md) to install the tgz package. ## 1. Installation and Usage @@ -212,7 +215,7 @@ For more information about the purpose of this field, please refer to the [offic ```json { "overrides": { - "@rnoh/react-native-openharmony": "^0.72.38" // ohpm version + "@rnoh/react-native-openharmony": "^0.77.17" // ohpm version // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // a locally available HAR package // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // source code directory } @@ -249,7 +252,7 @@ ohpm install Method 2: Directly link to the source code. -> [!TIP] For details, see [Directly Linking Source Code](/en/link-source-code.md). +**For details, see [Directly Linking Source Code](/en/link-source-code.md).** ### 2.3 Configuring CMakeLists and Introducing BackgroundTimerPackage @@ -301,7 +304,50 @@ export function createRNPackages(ctx: RNPackageContext): RNPackage[] { } ``` -### 2.5 Running +### 2.5 Configure TurboModule to run on worker thread + +Open the `entry/src/main/ets/entryability/EntryAbility.ets`file and add the following code: + +```diff +import {RNAbility} from '@rnoh/react-native-openharmony'; + +export default class EntryAbility extends RNAbility { ++ override getRNOHWorkerScriptUrl() { ++ return "entry/ets/workers/RNOHWorker.ets" ++ } +... +} +``` + +Right click on the ETS path and select the `New` option. Expand the menu on the right and choose the `Woker` option: + + ![create_worker](../img/react-native-background-timer/create-worker.png) + After selection, name `RNOHWorker. ets` in the pop-up window: + + ![christen_RNOHWorker](../img/react-native-background-timer/christen-RNOHWorker.png) + At this point, the directory structure is: + ``` + └── ets + ├── entryability + ├── page + └── workers + └── RNOHWorker.ets + ``` + + Modify `RNOHWorker. ets` to the following code: + ```typescript + // entry/src/main/ets/worker/RNOHWorker.ets + import { setupRNOHWorker } from "@rnoh/react-native-openharmony/src/main/ets/setupRNOHWorker"; + import { createRNPackages } from '../RNPackagesFactory'; + + setupRNOHWorker({ + createWorkerRNInstanceConfig: (_rnInstanceName) => { + return { thirdPartyPackagesFactory: createRNPackages } + } + }) + ``` + +### 2.6 Running Click the `sync` button in the upper right corner. @@ -320,7 +366,7 @@ Then build and run the code. To use this repository, you need to use the correct React-Native and RNOH versions. In addition, you need to use DevEco Studio and the ROM on your phone. -Check the release version information in the release address of the third-party library: [@react-native-ohos/react-native-background-timer Releases](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/releases) +Check the release version information in the release address of the third-party library: [@react-native-ohos/react-native-background-timer Releases](https://GitCode.com/openharmony-sig/rntpc_react-native-background-timer/releases) This document is verified based on the following versions: @@ -345,10 +391,10 @@ RNOH: 0.72.38; SDK: HarmonyOS-5.0.0(API12); ROM: 5.0.0.107; ## 5. Known Issues -- [ ] The underlying OS does not support RNOHContext serialized transfer in the new thread created by Worker. As a result, events cannot be sent in the new thread. The underlying OS framework needs to implement related service functionality. If no thread is started, the timer is not affected because **setTimeout** is an asynchronous method. The **start** and **stop** APIs of the Worker thread are not supported in HarmonyOS RN: [issue](https://github.com/react-native-oh-library/react-native-background-timer/issues/3). +- [ ] The underlying OS does not support RNOHContext serialized transfer in the new thread created by Worker. As a result, events cannot be sent in the new thread. The underlying OS framework needs to implement related service functionality. If no thread is started, the timer is not affected because **setTimeout** is an asynchronous method. The **start** and **stop** APIs of the Worker thread are not supported in HarmonyOS RN: [issue](https://gitcode.com/openharmony-sig/rntpc_react-native-background-timer/issues/2). ## 6. Others ## 7. License -This project is licensed under (https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/blob/master/LICENSE). +This project is licensed under (https://GitCode.com/openharmony-sig/rntpc_react-native-background-timer/blob/master/LICENSE). diff --git a/img/react-native-background-timer/christen-RNOHWorker.png b/img/react-native-background-timer/christen-RNOHWorker.png new file mode 100644 index 0000000000000000000000000000000000000000..ba94848bf354ec2343bfc75b28d0c89754385391 Binary files /dev/null and b/img/react-native-background-timer/christen-RNOHWorker.png differ diff --git a/img/react-native-background-timer/create-worker.png b/img/react-native-background-timer/create-worker.png new file mode 100644 index 0000000000000000000000000000000000000000..d52836671b473c0d14afd11c125f6c790a443193 Binary files /dev/null and b/img/react-native-background-timer/create-worker.png differ diff --git a/zh-cn/react-native-background-timer.md b/zh-cn/react-native-background-timer.md index 54c4423d06161a86c1ebab07b3e76b4c9d489cca..1cc7986b2c111ed8746ba389e7ef312aa9e85802 100644 --- a/zh-cn/react-native-background-timer.md +++ b/zh-cn/react-native-background-timer.md @@ -6,12 +6,15 @@ 本项目基于 [react-native-background-timer@2.4.1](https://github.com/ocetnik/react-native-background-timer) 开发。 -该第三方库的仓库已迁移至 Gitee，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-background-timer`，具体版本所属关系如下： +该第三方库的仓库已迁移至 GitCode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-background-timer`，具体版本所属关系如下： -| Version | Package Name | Repository | Release | -| ------------------------- | ------------------------------------------------- | ------------------ | -------------------------- | -| <= 2.4.1-0.0.2@deprecated | @react-native-oh-tpl/react-native-background-timer | [Github(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer/releases) | -| > 2.4.2 | @react-native-ohos/react-native-background-timer | [Gitee](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer) | [Gitee Releases](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/releases) | +| 三方库版本 | 发布信息 | 支持RN版本 | +| ---------- | ------------------------------------------------------------ | ---------- | +| <= 2.4.1-0.0.2@deprecated | [@react-native-oh-tpl/react-native-background-timer Releases(deprecated)](https://github.com/react-native-oh-library/react-native-background-timer/releases) | 0.72 | +| > 2.5.0 | [@react-native-ohos/react-native-background-timer Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-background-timer/releases) | 0.77 | + + +对于未发布到npm的旧版本，请参考[安装指南](/zh-cn/tgz-usage.md)安装tgz包。 ## 1. 安装与使用 @@ -215,7 +218,7 @@ const styles = StyleSheet.create({ ```json { "overrides": { - "@rnoh/react-native-openharmony": "^0.72.38" // ohpm 在线版本 + "@rnoh/react-native-openharmony": "^0.77.17" // ohpm 在线版本 // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径 // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径 } @@ -252,7 +255,7 @@ ohpm install 方法二：直接链接源码 -> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](/zh-cn/link-source-code.md) +**如需使用直接链接源码，请参考[直接链接源码说明](/zh-cn/link-source-code.md)** ### 2.3 配置 CMakeLists 和引入 BackgroundTimerPackage @@ -304,7 +307,49 @@ export function createRNPackages(ctx: RNPackageContext): RNPackage[] { } ``` -### 2.5 运行 +### 2.5 配置TurboModule运行在worker线程 + +打开 `entry/src/main/ets/entryability/EntryAbility.ets`，添加： + +```diff +import {RNAbility} from '@rnoh/react-native-openharmony'; + +export default class EntryAbility extends RNAbility { ++ override getRNOHWorkerScriptUrl() { ++ return "entry/ets/workers/RNOHWorker.ets" ++ } +... +} +``` + +在ets路径下右击，选择 `New` 选项，右侧展开菜单选择 `Woker` 选项： + + ![create_worker](../img/react-native-background-timer/create-worker.png) + 选择后在弹出的窗口中取名 `RNOHWorker.ets`： + + ![christen_RNOHWorker](../img/react-native-background-timer/christen-RNOHWorker.png) + 此时目录结构为: + ``` + └── ets + ├── entryability + ├── page + └── workers + └── RNOHWorker.ets + ``` + 修改 `RNOHWorker.ets` 为下列代码： + ```typescript + // entry/src/main/ets/worker/RNOHWorker.ets + import { setupRNOHWorker } from "@rnoh/react-native-openharmony/src/main/ets/setupRNOHWorker"; + import { createRNPackages } from '../RNPackagesFactory'; + + setupRNOHWorker({ + createWorkerRNInstanceConfig: (_rnInstanceName) => { + return { thirdPartyPackagesFactory: createRNPackages } + } + }) + ``` + +### 2.6 运行 点击右上角的 `sync` 按钮 @@ -324,7 +369,7 @@ ohpm install 要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。 -请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-ohos/react-native-background-timer Releases](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/releases) +请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-ohos/react-native-background-timer Releases](https://GitCode.com/openharmony-sig/rntpc_react-native-background-timer/releases) 本文档内容基于以下版本验证通过： @@ -335,11 +380,11 @@ RNOH: 0.72.38; SDK: HarmonyOS-5.0.0(API12); ROM: 5.0.0.107; ## 4. API -> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 +> [!TIP] "支持平台"列表示该属性在原三方库上支持的平台。 -> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 +> [!TIP] "鸿蒙支持"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 -| Name | Description | Required | Platform | HarmonyOS Support | +| 属性名 | 描述 | 类型 | 支持平台 | 鸿蒙支持 | | ---- | ----------- | -------- | -------- | ------------------ | | runBackgroundTimer | 开启定时器，以固定的时间间隔重复执行指定代码 | no | all | yes | | stopBackgroundTimer | 结束runBackgroundTimer开启的定时器 | no | all | yes | @@ -352,12 +397,12 @@ RNOH: 0.72.38; SDK: HarmonyOS-5.0.0(API12); ROM: 5.0.0.107; ## 5. 遗留问题 -- [ ] 使用worker开的新线程中不支持RNOHContext序列化传参，底层OS暂不支持，导致无法在新线程中发送事件，需要底层OS框架实现相关业务功能。不开线程的情况下，因setTimeout属于异步方法，定时器效果不受影响。[worker线程遗留问题:start和stop接口， HarmonyOS RN框架暂不支持](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/issues/IB8QGJ) +- [ ] 使用worker开的新线程中不支持RNOHContext序列化传参，底层OS暂不支持，导致无法在新线程中发送事件，需要底层OS框架实现相关业务功能。不开线程的情况下，因setTimeout属于异步方法，定时器效果不受影响。[worker线程遗留问题:start和stop接口， HarmonyOS RN框架暂不支持](https://gitcode.com/openharmony-sig/rntpc_react-native-background-timer/issues/2) ## 6. 其他 ## 7. 开源协议 -本项目基于 [The MIT License (MIT)](https://gitee.com/openharmony-sig/rntpc_react-native-background-timer/blob/master/LICENSE) ，请自由地享受和参与开源。 +本项目基于 [The MIT License (MIT)](https://GitCode.com/openharmony-sig/rntpc_react-native-background-timer/blob/master/LICENSE) ，请自由地享受和参与开源。