diff --git a/en/react-native-selectable-text.md b/en/react-native-selectable-text.md new file mode 100644 index 0000000000000000000000000000000000000000..15b67eae062b7a89d865dcf5ddb4aa8e69460be7 --- /dev/null +++ b/en/react-native-selectable-text.md @@ -0,0 +1,222 @@ +> Template version: v0.4.0 + +

+

@astrocoders/react-native-selectable-text

+

+ +This project is based on [@astrocoders/react-native-selectable-text](https://github.com/Astrocoders/react-native-selectable-text). + +This third-party library has been migrated to Gitcode and is now available for direct download from npm, the new package name is: `@react-native-ohos/react-native-selectable-text`, The version correspondence details are as follows: + +| Name | Version | Release Information | Supported RN Version | Supported Autolink | Compile API Version | Community Baseline Version | npm Address | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| @react-native-ohos/react-native-selectable-text | 1.5.2 | [Github Releases](https://github.com/react-native-oh-library/react-native-selectable-text/releases) | 0.72, 0.77 | No | API12+ | 1.5.1 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/react-native-selectable-text) | + +## 1. Installation and Usage + +Go to the project directory and execute the following instruction: + + + +#### **npm** + +```bash +npm install @react-native-ohos/react-native-selectable-text +``` + +#### **yarn** + +```bash +yarn add @react-native-ohos/react-native-selectable-text +``` + + + +The following code demonstrates a basic usage scenario of this library: + +> [!WARNING] The import library name remains unchanged during use. + +```js +import React from "react"; +import { View, Alert } from "react-native"; +import { SelectableText } from "react-native-selectable-text"; + +const App = () => { + return ( + + { + Alert.alert( + eventType, + `Selected: "${content}"\nRange: [${selectionStart}, ${selectionEnd}]` + ); + }} + style={{ fontSize: 16, color: "#333" }} + /> + + ); +}; + +export default App; +``` +## 2. Manual Link + +| | Supports Autolink | RN Framework Version | +|--------------------------------------|-----------------|------------| +| 1.5.2 | No | 0.72/0.77 | + +Projects using AutoLink need to be configured according to this document, AutoLink framework guide.：https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md + +If the version you are using supports Autolink and the project has integrated Autolink, you can skip the ManualLink configuration. + +
+ ManualLink: This step provides guidance for manually configuring native dependencies. + +Open the `harmony` directory of the HarmonyOS project in DevEco Studio. + +### 2.1 Overrides RN SDK + +To ensure the project relies on the same version of the RN SDK, you need to add an `overrides` field in the project's root `oh-package.json5` file, specifying the RN SDK version to be used. The replacement version can be a specific version number, a semver range, or a locally available HAR package or source directory. + +For more information about the purpose of this field, please refer to the [official documentation](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-oh-package-json5-V5#en-us_topic_0000001792256137_overrides). + +```json +{ + "overrides": { + "@rnoh/react-native-openharmony": "^0.72.38" // 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 + } +} +``` + +### 2.2 Introducing Native Code + +Currently, two methods are available: + +- Use the HAR file. +- Directly link to the source code。 + +Method 1 (recommended): Use the HAR file. + +> [!TIP] The HAR file is stored in the `harmony` directory in the installation path of the third-party library. + +Open `entry/oh-package.json5` file and add the following dependencies: + +```json +"dependencies": { + "@rnoh/react-native-openharmony": "file:../react_native_openharmony", + "@react-native-ohos/react-native-selectable-text": "file:../../node_modules/@react-native-ohos/react-native-selectable-text/harmony/selectable_text.har" + } +``` + +Click the `sync` button in the upper right corner. + +Alternatively, run the following instruction on the terminal: + +```bash +cd entry +ohpm install +``` + +Method 2: Directly link to the source code. + +> [!TIP] For details, see [Directly Linking Source Code](/en/link-source-code.md). + +### 2.3 Configuring CMakeLists and Introducing SelectableTextPackage + +Open `entry/src/main/cpp/CMakeLists.txt` and add the following code: + +```diff +project(rnapp) +cmake_minimum_required(VERSION 3.4.1) +set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}") ++ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules") +set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp") + +# RNOH_BEGIN: manual_package_linking_1 ++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-selectable-text/src/main/cpp" ./selectable-text) +# RNOH_END: manual_package_linking_1 + +# RNOH_BEGIN: manual_package_linking_2 ++ target_link_libraries(rnoh_app PUBLIC rnoh_selectable_text) +# RNOH_END: manual_package_linking_2 +``` + +Open `entry/src/main/cpp/PackageProvider.cpp` and add the following code: + +```diff +#include "RNOH/PackageProvider.h" +#include "generated/RNOHGeneratedPackage.h" ++ #include "SelectableTextViewPackage.h" + +using namespace rnoh; + +std::vector> PackageProvider::getPackages(Package::Context ctx) { + return { + std::make_shared(ctx), ++ std::make_shared(ctx), + }; +} +``` + +## 2.4 Running + +Click the `sync` button in the upper right corner. + +Alternatively, run the following instruction on the terminal: + +```bash +cd entry +ohpm install +``` + +Then build and run the code. +
+ +## 3. Constraints + +### 3.1 Compatibility + +Please check the version matching information in the Releases page of the third-party library: [@react-native-ohos/react-native-selectable-text Releases](https://github.com/react-native-oh-library/react-native-selectable-text/releases) + +The content of this document has been verified using the following versions: + +1. RNOH: 0.72.108; SDK: HarmonyOS-6.0.2.129 (API Version 22 Beta1); IDE: DevEco Studio 6.0.2.636; ROM: 6.0.0.129; +2. RNOH: 0.77.18; SDK: HarmonyOS-6.0.2.129 (API Version 22 Beta1); IDE: DevEco Studio 6.0.2.636; ROM: 6.0.0.129; + +### 3.2 API Requirements for Compilation and Runtime + +> [!TIP] All versions of this third-party library have achieved version isolation and support compilation in `API12+` projects, as well as running on `API12+` ROMs. + +> [!TIP] The following features rely on specific API versions. Compiling in projects `lower than API 22` or running on ROMs `lower than API 22` may result in limited functionality. + +1. This library introduces [NODE_TEXT_EDIT_MENU_OPTIONS](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-node-h) to implement the custom popup menu functionality. This API requires compilation in a project supporting `API22+` and must run on a ROM supporting `API22+` to take effect. + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +|--------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|----------|-------------|-------------------| +| value | Text content | string | yes | iOS/Android | yes | +| onSelection | Callback when the user clicks a selection menu item (Supported starting from API version 22) | ({ eventType: string, content: string, selectionStart: int, selectionEnd: int }) => void | no | iOS/Android | yes | +| menuItems | Array of custom menu items (Supported starting from API version 22) | array(string) | no | iOS/Android | yes | +| style | Additional style applied to text | Object | no | iOS/Android | yes | +| highlights | Array of text ranges to highlight, can include id | array({ id: string, start: int, end: int }) | no | iOS/Android | yes | +| highlightColor | Highlight background color | string | no | iOS/Android | yes | +| onHighlightPress | Callback when user clicks a highlighted area | (id: string) => void | no | iOS/Android | yes | +| appendToChildren | Elements appended to the end of the text | ReactNode | no | iOS/Android | yes | +| TextComponent | Custom component used to render text | ReactNode | no | iOS/Android | yes | +| textValueProp | The text property name passed to TextComponent, used with TextComponent, defaults to 'children' | string | no | iOS/Android | yes | +| textComponentProps | Additional properties passed to TextComponent | object | no | iOS/Android | yes | + +## 5. Known Issues + +None + +## 6. Others + +None + +## 7. License + +This project is based on [The MIT License (MIT)](https://github.com/Astrocoders/react-native-selectable-text/blob/master/LICENSE), please freely enjoy and participate in open source. \ No newline at end of file diff --git a/zh-cn/react-native-selectable-text.md b/zh-cn/react-native-selectable-text.md new file mode 100644 index 0000000000000000000000000000000000000000..ece2d10f1c72d078271d935069160f74562862b7 --- /dev/null +++ b/zh-cn/react-native-selectable-text.md @@ -0,0 +1,236 @@ +> 模板版本：v0.4.0 + +

+

@astrocoders/react-native-selectable-text

+

+

+ + Supported platforms + + + License + +

+ +本项目基于 [@astrocoders/react-native-selectable-text](https://github.com/Astrocoders/react-native-selectable-text) 开发。 + +该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-selectable-text` 版本所属关系如下： + +| 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| @react-native-ohos/react-native-selectable-text | 1.5.2 | [Github Releases](https://github.com/react-native-oh-library/react-native-selectable-text/releases) | 0.72, 0.77| 否 | API12+ | 1.5.1 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/react-native-selectable-text) | + +## 1. 安装与使用 + +进入到工程目录并输入以下命令： + + + +#### **npm** + +```bash +npm install @react-native-ohos/react-native-selectable-text +``` + +#### **yarn** + +```bash +yarn add @react-native-ohos/react-native-selectable-text +``` + + + +下面的代码展示了这个库的基本使用场景： + +> [!WARNING] 使用时 import 的库名不变。 + +```js +import React from "react"; +import { View, Alert } from "react-native"; +import { SelectableText } from "react-native-selectable-text"; + +const App = () => { + return ( + + { + Alert.alert( + eventType, + `选中: "${content}"\n范围: [${selectionStart}, ${selectionEnd}]` + ); + }} + style={{ fontSize: 16, color: "#333" }} + /> + + ); +}; + +export default App; +``` +## 2. Link + +| | 是否支持autolink | RN框架版本 | +|--------------------------------------|-----------------|------------| +| 1.5.2 | No | 0.72/0.77 | + +使用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`。 + +### 2.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.72.38" // ohpm 在线版本 + // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径 + // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径 + } +} +``` + +### 2.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-selectable-text": "file:../../node_modules/@react-native-ohos/react-native-selectable-text/harmony/selectable_text.har" + } +``` + +点击右上角的 `sync` 按钮 + +或者在命令行终端执行： + +```bash +cd entry +ohpm install +``` + +方法二：直接链接源码 + +> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](/zh-cn/link-source-code.md) + +### 2.3. 配置 CMakeLists 和引入 SelectableTextPackage + +打开 `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(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules") +set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp") + +# RNOH_BEGIN: manual_package_linking_1 ++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-selectable-text/src/main/cpp" ./selectable-text) +# RNOH_END: manual_package_linking_1 + +# RNOH_BEGIN: manual_package_linking_2 ++ target_link_libraries(rnoh_app PUBLIC rnoh_selectable_text) +# RNOH_END: manual_package_linking_2 +``` + +打开 `entry/src/main/cpp/PackageProvider.cpp`，添加： + +```diff +#include "RNOH/PackageProvider.h" +#include "generated/RNOHGeneratedPackage.h" ++ #include "SelectableTextViewPackage.h" + +using namespace rnoh; + +std::vector> PackageProvider::getPackages(Package::Context ctx) { + return { + std::make_shared(ctx), ++ std::make_shared(ctx), + }; +} +``` + +### 2.4. 运行 + +点击右上角的 `sync` 按钮 + +或者在命令行终端执行： + +```bash +cd entry +ohpm install +``` + +然后编译、运行即可。 +
+ +## 3. 约束与限制 + +### 3.1. 兼容性 + +请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-ohos/react-native-selectable-text Releases](https://github.com/react-native-oh-library/react-native-selectable-text/releases) + +本文档内容基于以下版本验证通过： + +1. RNOH: 0.72.108; SDK: HarmonyOS-6.0.2.129 (API Version 22 Beta1); IDE: DevEco Studio 6.0.2.636; ROM: 6.0.0.129; +2. RNOH: 0.77.18; SDK: HarmonyOS-6.0.2.129 (API Version 22 Beta1); IDE: DevEco Studio 6.0.2.636; ROM: 6.0.0.129; + +### 3.2. 编译运行API要求 + +> [!TIP] 当前三方库所有版本均已实现版本隔离，支持在 `API12+` 工程编译，及 `API12+` ROM运行。 + +> [!TIP] 以下功能依赖特定版本的API，使用 `低于API22版本的工程编译` 或 `低于API22版本的ROM运行` 均可能导致部分功能受限。 +1. 本库引入[NODE_TEXT_EDIT_MENU_OPTIONS](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-node-h)，实现弹出自定义菜单功能，此API需要在支持`API22+`的工程编译，并在支持`API22+`的ROM上运行，方可生效。 + +## 4. 属性 + +> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 + +> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 + +> [!TIP] onSelection和menuItems属性仅在API version 22开始支持。 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +|--------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|----------|-------------|-------------------| +| value | 文本内容 | string | yes | iOS/Android | yes | +| onSelection | 用户点击选择菜单项时的回调(仅在API version 22开始支持) | ({ eventType: string, content: string, selectionStart: int, selectionEnd: int }) => void | no | iOS/Android | yes | +| menuItems | 自定义菜单项数组(仅在API version 22开始支持) | array(string) | no | iOS/Android | yes | +| style | 应用于文本的额外样式 | Object | no | iOS/Android | yes | +| highlights | 需要高亮的文本范围数组，可包含 id | array({ id: string, start: int, end: int }) | no | iOS/Android | yes | +| highlightColor | 高亮背景颜色 | string | no | iOS/Android | yes | +| onHighlightPress | 用户点击高亮区域时的回调 | (id: string) => void | no | iOS/Android | yes | +| appendToChildren | 追加到文本末尾的元素 | ReactNode | no | iOS/Android | yes | +| TextComponent | 用于渲染文本的自定义组件 | ReactNode | no | iOS/Android | yes | +| textValueProp | 传递给 TextComponent 的文本属性名，配合 TextComponent 使用，默认为 'children' | string | no | iOS/Android | yes | +| textComponentProps | 传递给 TextComponent 的额外属性 | object | no | iOS/Android | yes | + +## 5. 遗留问题 + +暂无 + +## 6. 其他 + +暂无 + +## 7. 开源协议 + +本项目基于 [The MIT License (MIT)](https://github.com/Astrocoders/react-native-selectable-text/blob/master/LICENSE) ，请自由地享受和参与开源。