diff --git a/en/react-navigation-elements.md b/en/react-navigation-elements.md index 502853e29a85c0e78c22dab350e1bab90e39dd64..87395011594f6850fd56d4a54b7c554945b4d71e 100644 --- a/en/react-navigation-elements.md +++ b/en/react-navigation-elements.md @@ -1,4 +1,4 @@ -> 模板版本：v0.2.2 +> 模板版本：v0.4.0

@react-navigation/elements

@@ -12,46 +12,38 @@

-This project is based on [@react-navigation/bottom-tabs](https://github.com/react-navigation/react-navigation/tree/6.x/packages/bottom-tabs). +This project is developed based on [@react-navigation/bottom-tabs](https://github.com/react-navigation/react-navigation/tree/6.x/packages/bottom-tabs). -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/elements`, The version correspondence details are as follows: +This third-party library has been migrated to GitCode and can be installed directly from npm. The package name is: `@react-native-ohos/elements`. Version mapping is as follows: +| Package Name | Version | Release Notes | Supported RN Version | Autolink | Build API Version | Community Baseline Version | npm | +| --- | --- | --- | --- | --- | --- | --- | --- | +| @react-native-ohos/elements | 2.4.0 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.82.* | No | API12+ | 2.6.0 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/elements) | +| @react-native-ohos/elements | 2.3.9 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.77.* | No | API12+ | 2.3.8 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/elements) | +| @react-native-ohos/elements | 1.3.21 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.72.* | Yes | API12+ | 1.3.20 | [Npm Address](https://www.npmjs.com/@react-native-oh-ohos/elements) | -| Version | Package Name | Repository | Release |Support RN version| -| ------------------------- |----------------------------------------| ------------------ | -------------------------- |-------------------| -| 1.3.21 | @react-native-oh-tpl/elements | [Github](https://github.com/react-native-oh-library/react-navigation/tree/sig/packages/elements) | [Github Releases](https://github.com/react-native-oh-library/react-navigation/tree/sig/packages/elements/releases) |0.72 | -| 2.3.9 |@react-native-ohos/elements | [Github](https://gitcode.com/openharmony-sig/rntpc_react-navigation/tree/br_rnoh0.77/packages/elements) | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) |0.77 | +## 1. Installation & Usage -## 安装与使用 - -进入到工程目录并输入以下命令： +In your project directory, run: #### **npm** ```bash -# 0.72 -npm install @react-native-oh-tpl/elements - -# 0.77 npm install @react-native-ohos/elements ``` #### **yarn** ```bash -# 0.72 -yarn add @react-native-oh-tpl/elements - -# 0.77 yarn add @react-native-ohos/elements ``` -下面的代码展示了这个库的基本使用场景： +The code below shows a basic usage scenario: -> [!WARNING] 使用时 import 的库名不变。 +> [!WARNING] The import name stays the same when using this library. ```js import { Header, getHeaderTitle } from "@react-navigation/elements"; @@ -89,80 +81,142 @@ export function NavigationElements() { export default NavigationElements; ``` -## 兼容性 +## 2. Link + +| | Autolink Supported | RN Version | +|--------------------------------------|-------------------|-----------| +| 2.4.0 | No | 0.82 | +| 2.3.9 | No | 0.77 | +| 1.3.21 | Yes | 0.72 | + +If your project uses Autolink, configure it following this guide: +Autolink framework guide: https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md + +If the version you use supports Autolink and your project has already integrated Autolink, you can skip ManualLink. +
+ ManualLink: A guide for manually configuring native dependencies + +First, open the HarmonyOS project `harmony` in your project using DevEco Studio. -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. +This step is a guide for manually configuring native dependencies. + +First, open the HarmonyOS project `harmony` in your project using DevEco Studio. + +### 2.1. Overrides RN SDK + +To make the project depend on the same RN SDK version, add an `overrides` field in `oh-package.json5` at the project root, pointing to the RN SDK version you want to use. The overridden version can be a specific version, a version range, or a local HAR package / source directory. + +For the purpose of this field, refer to the [official documentation](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 online version + // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // path to local har package + // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // path to source directory + } +} +``` + +### 2.2. Run + +Click the `sync` button in the top-right corner. + +Or run in the command line: + +```bash +cd entry +ohpm install +``` + +Then build and run the project. +
+ +## 3. Constraints & Limitations + +### 3.1. Compatibility + +Please check the Release version mapping at the corresponding releases page: +[ Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) + +This document is verified on the following versions: + +(Example) 1. RNOH: 0.72.27; SDK: HarmonyOS 5.1.1 Release SDK; IDE: DevEco Studio 5.1.1 Release; ROM: 5.0.1.120; 2. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; +3. RNOH: 0.82.1; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; -## 属性 +## 4. Props -> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 +> [!TIP] The "Platform" column indicates platforms supported by the original third-party library. -> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 +> [!TIP] In the "HarmonyOS Support" column, **yes** means the property is supported on HarmonyOS, **no** means not supported, and **partially** means partially supported. Usage is cross-platform consistent, with behavior aligned to iOS or Android. -以下属性已验证，更多使用详情请查看 [react-navigation/elements 的文档介绍](https://reactnavigation.org/docs/elements) +The following props have been verified. For more details, see [react-navigation/elements documentation](https://reactnavigation.org/docs/elements). **Header Props** -| Name | Description | Type | Required | Platform | HarmonyOS Support | -|--------------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------------|----------|----------|-------------------| -| headerTitle | String or a function that returns a React Element to be used by the header.  | string | no | all | yes | -| headerTitleAlign | How to align the header title | 'left'|'center' | no | all | yes | -| headerTitleAllowFontScaling | Whether header title font should scale to respect Text Size accessibility settings. | boolean | no | all | yes | -| headerLeft | Function which returns a React Element to display on the left side of the header. | function | no | all | yes | -| headerRight | Function which returns a React Element to display on the right side of the header. | function | no | all | yes | -| headerShadowVisible | Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header. | boolean | no | all | yes | -| headerStyle | Style object for the header. You can specify a custom background color here | object | no | all | yes | -| headerTitleStyle | Style object for the title component | object | no | all | yes | -| headerLeftContainerStyle | Customize the style for the container of the headerLeft component, for example to add padding. | object | no | all | yes | -| headerRightContainerStyle | Customize the style for the container of the headerRight component, for example to add padding. | object | no | all | yes | -| headerTitleContainerStyle | Customize the style for the container of the headerTitle component, for example to add padding. | object | no | all | yes | -| headerBackgroundContainerStyle | Style object for the container of the headerBackground element. | object | no | all | yes | -| headerTintColor | Tint color for the header | string | no | all | yes | -| headerPressColor | Color for material ripple (Android >= 5.0 only) | string | no | Android | no | -| headerPressOpacity | Press opacity for the buttons in header (Android < 5.0, and iOS) | number | no | all | yes | -| headerTransparent | Defaults to false. If true, the header will not have a background unless you explicitly provide it with headerBackground.  | boolean | no | all | yes | -| headerBackground | Function which returns a React Element to render as the background of the header.  | function | no | all | yes | -| headerStatusBarHeight | Extra padding to add at the top of header to account for translucent status bar. | number | no | all | yes | -| headerSearchBarOptions2.3.8+ | Options for the search bar in the header. | object | no | all | yes | -| HeaderButton2.3.8+ | A component used to show a button in header. | function | no | all | yes | -| Button2.3.8+ | A component that renders a button. | function | no | all | yes | -| Label2.3.8+ | The Label component is used to render small text | function | no | all | yes | + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------------|----------|----------|-------------------| +| headerTitle | String or a function that returns a React Element to be used by the header. | string | no | all | yes | +| headerTitleAlign | How to align the header title | 'left'|'center' | no | all | yes | +| headerTitleAllowFontScaling | Whether header title font should scale to respect Text Size accessibility settings. | boolean | no | all | yes | +| headerLeft | Function which returns a React Element to display on the left side of the header. | function | no | all | yes | +| headerRight | Function which returns a React Element to display on the right side of the header. | function | no | all | yes | +| headerShadowVisible | Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header. | boolean | no | all | yes | +| headerStyle | Style object for the header. You can specify a custom background color here | object | no | all | yes | +| headerTitleStyle | Style object for the title component | object | no | all | yes | +| headerLeftContainerStyle | Customize the style for the container of the headerLeft component, for example to add padding. | object | no | all | yes | +| headerRightContainerStyle | Customize the style for the container of the headerRight component, for example to add padding. | object | no | all | yes | +| headerTitleContainerStyle | Customize the style for the container of the headerTitle component, for example to add padding. | object | no | all | yes | +| headerBackgroundContainerStyle | Style object for the container of the headerBackground element. | object | no | all | yes | +| headerTintColor | Tint color for the header | string | no | all | yes | +| headerPressColor | Color for material ripple (Android >= 5.0 only) | string | no | Android | no | +| headerPressOpacity | Press opacity for the buttons in header (Android < 5.0, and iOS) | number | no | all | yes | +| headerTransparent | Defaults to false. If true, the header will not have a background unless you explicitly provide it with headerBackground. | boolean | no | all | yes | +| headerBackground | Function which returns a React Element to render as the background of the header. | function | no | all | yes | +| headerStatusBarHeight | Extra padding to add at the top of header to account for translucent status bar. | number | no | all | yes | +| headerSearchBarOptions2.3.8+ | Options for the search bar in the header. | object | no | all | yes | +| HeaderButton2.3.8+ | A component used to show a button in header. | function | no | all | yes | +| Button2.3.8+ | A component that renders a button. | function | no | all | yes | +| Label2.3.8+ | The Label component is used to render small text. | function | no | all | yes | +| HeaderButtonRef2.6.0+ | HeaderButton can get the internal ref | function | no | all | yes | +| PlatformPressableRef2.6.0+ | PlatformPressableRef can get the internal ref | function | no | all | yes | **Header Components Props** | Name | Description | Type | Required | Platform | HarmonyOS Support | |--------------------|------------------------------------------------------------------------------------------------------------------------------|----------|----------|----------|-------------------| | HeaderBackground | A component containing the styles used in the background of the header, such as the background color and shadow. | function | no | all | yes | -| HeaderTitle | A component used to show the title text in header. It's the default for headerTitle. It accepts the same props as a Text. | function | no | all | yes | -| HeaderBackButton | A component used to show the back button header. It's the default for headerLeft in the stack navigator.  | function | no | all | yes | -| MissingIcon | A component that renders a missing icon symbol. It can be used as a fallback for icons to show that there's a missing icon.  | function | no | all | yes | -| PlatformPressable | A component which provides an abstraction on top of Pressable to handle platform differences.  | function | no | all | yes | -| ResourceSavingView | A component which aids in improving performance for inactive screens by utilizing removeClippedSubviews. | function | no | all | yes | +| HeaderTitle | A component used to show the title text in header. It's the default for headerTitle. It accepts the same props as a Text. | function | no | all | yes | +| HeaderBackButton | A component used to show the back button header. It's the default for headerLeft in the stack navigator. | function | no | all | yes | +| MissingIcon | A component that renders a missing icon symbol. It can be used as a fallback for icons to show that there's a missing icon. | function | no | all | yes | +| PlatformPressable | A component which provides an abstraction on top of Pressable to handle platform differences. | function | no | all | yes | +| ResourceSavingView | A component which aids in improving performance for inactive screens by utilizing removeClippedSubviews. | function | no | all | yes | **Utilities** -| Name | Description | Type | Required | Platform | HarmonyOS Support | -|------------------------|-------------------------------------------------------------------------------------------------------------------|----------|----------|----------|-------------------| -| SafeAreaProviderCompat | A wrapper over the SafeAreaProvider component from `react-native-safe-area-context which includes initial values. | function | no | all | yes | -| HeaderBackContext | React context that can be used to get the back title of the parent screen. | function | no | all | yes | -| HeaderShownContext | React context that can be used to check if a header is visible in a parent screen. | function | no | all | yes | -| HeaderHeightContext | React context that can be used to get the height of the nearest visible header in a parent screen. | function | no | all | yes | -| useHeaderHeight | Hook that returns the height of the nearest visible header in the parent screen. | function | no | all | yes | -| getDefaultHeaderHeight | Helper that returns the default header height. | function | no | all | yes | -| getHeaderTitle | Helper that returns the title text to use in header.  | function | no | all | yes | +| Name | Description | Type | Required | Platform | HarmonyOS Support | +|------------------------|--------------------------------------------------------------------------------------------------------------------|----------|----------|----------|-------------------| +| SafeAreaProviderCompat | A wrapper over the SafeAreaProvider component from `react-native-safe-area-context` which includes initial values. | function | no | all | yes | +| HeaderBackContext | React context that can be used to get the back title of the parent screen. | function | no | all | yes | +| HeaderShownContext | React context that can be used to check if a header is visible in a parent screen. | function | no | all | yes | +| HeaderHeightContext | React context that can be used to get the height of the nearest visible header in a parent screen. | function | no | all | yes | +| useHeaderHeight | Hook that returns the height of the nearest visible header in the parent screen. | function | no | all | yes | +| getDefaultHeaderHeight | Helper that returns the default header height. | function | no | all | yes | +| getHeaderTitle | Helper that returns the title text to use in header. | function | no | all | yes | -## 遗留问题 +## 5. Known Issues -## 其他 +## 6. Other -示例代码依赖以下三方库，请查看对应文档： +The example code depends on the following third-party libraries. See the related docs: + [@react-navigation/stack](/zh-cn/react-navigation-stack.md) + [@react-navigation/native](/zh-cn/react-navigation-native.md) -+ [@react-native-oh-tpl/react-native-gesture-handler](/zh-cn/react-native-gesture-handler.md) -+ [@react-native-oh-library/react-native-safe-area-context](/zh-cn/react-native-safe-area-context.md) ++ [@react-native-oh-ohos/react-native-gesture-handler](/zh-cn/react-native-gesture-handler.md) ++ [@react-native-oh-ohos/react-native-safe-area-context](/zh-cn/react-native-safe-area-context.md) -## 开源协议 +## 7. License -本项目基于 [The MIT License (MIT)](https://github.com/react-navigation/react-navigation/blob/6.x/packages/elements/LICENSE) ，请自由地享受和参与开源。 \ No newline at end of file +This project is licensed under [The MIT License (MIT)](https://github.com/react-navigation/react-navigation/blob/main/packages/elements/LICENSE). Feel free to use it and contribute. \ No newline at end of file diff --git a/zh-cn/react-navigation-elements.md b/zh-cn/react-navigation-elements.md index a917480fab05f385c894110bf208cdae79bdd694..576170c88660e0ffdda6eb9cb103e8c208ba75ab 100644 --- a/zh-cn/react-navigation-elements.md +++ b/zh-cn/react-navigation-elements.md @@ -1,4 +1,4 @@ -> 模板版本：v0.2.2 +> 模板版本：v0.4.0

@react-navigation/elements

@@ -15,13 +15,14 @@ 本项目基于 [@react-navigation/bottom-tabs](https://github.com/react-navigation/react-navigation/tree/6.x/packages/bottom-tabs) 开发。 该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/elements`，具体版本所属关系如下： +| 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 | +| ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | +| @react-native-ohos/elements | 2.4.0 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.82.* | 否 | API12+ | 2.6.0 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/elements) | +| @react-native-ohos/elements | 2.3.9 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.77.* | 否 | API12+ | 2.3.8 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/elements) | +| @react-native-ohos/elements | 1.3.21 | [Gitcode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) | 0.72.* | 是 | API12+ | 1.3.20 | [Npm Address](https://www.npmjs.com/@react-native-oh-ohos/elements) | -| Version | Package Name | Repository | Release |Support RN version| -| ------------------------- |----------------------------------------| ------------------ | -------------------------- |-------------------| -| 1.3.21 | @react-native-oh-tpl/elements | [Github](https://github.com/react-native-oh-library/react-navigation/tree/sig/packages/elements) | [Github Releases](https://github.com/react-native-oh-library/react-navigation/tree/sig/packages/elements/releases) |0.72 | -| 2.3.9 |@react-native-ohos/elements | [Github](https://gitcode.com/openharmony-sig/rntpc_react-navigation/tree/br_rnoh0.77/packages/elements) | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) |0.77 | -## 安装与使用 +## 1.安装与使用 进入到工程目录并输入以下命令： @@ -30,20 +31,12 @@ #### **npm** ```bash -# 0.72 -npm install @react-native-oh-tpl/elements - -# 0.77 npm install @react-native-ohos/elements ``` #### **yarn** ```bash -# 0.72 -yarn add @react-native-oh-tpl/elements - -# 0.77 yarn add @react-native-ohos/elements ``` @@ -90,14 +83,70 @@ export function NavigationElements() { export default NavigationElements; ``` -## 兼容性 +## 2. Link + +| | 是否支持autolink | RN框架版本 | +|--------------------------------------|------------------|-----------| +| 2.4.0 | No | 0.82 | +| 2.3.9 | No | 0.77 | +| 1.3.21 | Yes | 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`。 + +此步骤为手动配置原生依赖项的指导。 + +首先需要使用 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. 运行 + +点击右上角的 `sync` 按钮 + +或者在命令行终端执行： + +```bash +cd entry +ohpm install +``` -要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。 +然后编译、运行即可。 + +## 3. 约束与限制 + +### 3.1. 兼容性 + +请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[ Releases](https://gitcode.com/openharmony-sig/rntpc_react-navigation/releases) + +本文档内容基于以下版本验证通过： + +(示例) 1. RNOH: 0.72.27; SDK: HarmonyOS 5.1.1 Release SDK; IDE: DevEco Studio 5.1.1 Release; ROM: 5.0.1.120; 2. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; +3. RNOH: 0.82.1; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; -## 属性 +## 4.属性 > [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 @@ -131,7 +180,8 @@ export default NavigationElements; | HeaderButton2.3.8+ | 用于在标题中显示按钮的组件 | function | no | all | yes | | Button2.3.8+ | 渲染按钮的组件 | function | no | all | yes | | Label2.3.8+ | 标签组件用于渲染小段文本 | function | no | all | yes | - +| HeaderButtonRef2.6.0+ | HeaderButton可以拿到内部的ref本 | function | no | all | yes | +| PlatformPressableRef2.6.0+ | PlatformPressableRef可以拿到内部的ref本 | function | no | all | yes | **Header Components Props** @@ -157,16 +207,16 @@ export default NavigationElements; | getHeaderTitle | 返回标题栏中使用的标题文本的辅助工具 | function | no | all | yes | -## 遗留问题 +## 5.遗留问题 -## 其他 +## 6.其他 示例代码依赖以下三方库，请查看对应文档： + [@react-navigation/stack](/zh-cn/react-navigation-stack.md) + [@react-navigation/native](/zh-cn/react-navigation-native.md) -+ [@react-native-oh-tpl/react-native-gesture-handler](/zh-cn/react-native-gesture-handler.md) -+ [@react-native-oh-library/react-native-safe-area-context](/zh-cn/react-native-safe-area-context.md) ++ [@react-native-oh-ohos/react-native-gesture-handler](/zh-cn/react-native-gesture-handler.md) ++ [@react-native-oh-ohos/react-native-safe-area-context](/zh-cn/react-native-safe-area-context.md) -## 开源协议 +## 7.开源协议 本项目基于 [The MIT License (MIT)](https://github.com/react-navigation/react-navigation/blob/main/packages/elements/LICENSE) ，请自由地享受和参与开源。 \ No newline at end of file