文档模板：v0.4.2

@react-navigation/native-stack

本项目基于 @react-navigation/native-stack 开发。

！！！主推新的鸿蒙版@react-native-ohos/native-stack和@react-native-ohos/react-native-screens组合，其余的组合方式不再支持。

该第三方库的仓库已迁移至 GitCode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/native-stack，具体版本所属关系如下：

三方库名称	三方库版本（npm地址）	发布信息	支持RN版本	Autolink	编译API版本	社区基线版本	源码地址
@react-native-ohos/native-stack	~6.9.28（开发中）	GitCode Releases	0.72.*	否	API12+	6.9.27	br_rnoh0.72
@react-native-oh-tpl/native-stack	~6.9.26-0.0.2@deprecated	Github Releases(deprecated)	0.72.*	否	API12+	6.9.26	sig

简介

@react-native-ohos/native-stack 是基于 @react-navigation/native-stack 进行鸿蒙化适配的原生堆栈导航器组件库，需与鸿蒙化的 @react-native-ohos/react-native-screens 组合使用，提供基于原生转场动画的页面切换能力，支持卡片式/模态页面呈现、自定义头部（Header）、转场动画、手势返回等特性，使用方式与跨平台一致，效果对标 iOS 或 Android 平台。

下载安装

请到三方库的 Releases 发布地址查看配套的版本信息：@react-native-ohos/native-stack Releases 。对于未发布到npm的旧版本，请参考安装指南安装tgz包。

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

npm

npm install @react-native-ohos/native-stack

yarn

yarn add @react-native-ohos/native-stack

依赖关系说明

请根据应用工程使用的 RN 框架版本，选择对应版本的三方库进行引入，版本对应关系如下：

RN 框架版本	鸿蒙化依赖库	支持版本范围
0.72	@react-native-ohos/react-native-screens	>=3.34.1 && < 4.8.1
0.72	@react-native-ohos/react-native-safe-area-context	>=4.7.5 && < 5.1.0

本库鸿蒙侧实现依赖上述鸿蒙化三方库，如已在鸿蒙应用工程中引入，可跳过本章节步骤，直接使用。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

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;

权限要求

无特殊权限要求。

编译运行API要求

使用示例

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

import * as React from 'react';
import { Button, View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { enableScreens } from "react-native-screens";
enableScreens(false);

function HomeScreen({ navigation }) {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button
        title="Go to Profile"
        onPress={() => navigation.navigate('Profile')}
      />
    </View>
  );
}

function ProfileScreen({ navigation }) {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button
        title="Go to Notifications"
        onPress={() => navigation.navigate('Notifications')}
      />
      <Button title="Go back" onPress={() => navigation.goBack()} />
    </View>
  );
}

function NotificationsScreen({ navigation }) {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button
        title="Go to Settings"
        onPress={() => navigation.navigate('Settings')}
      />
      <Button title="Go back" onPress={() => navigation.goBack()} />
    </View>
  );
}

function SettingsScreen({ navigation }) {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="Go back" onPress={() => navigation.goBack()} />
    </View>
  );
}

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator
      initialRouteName="Home"
      screenOptions={{
        headerTintColor: 'white',
        headerStyle: { backgroundColor: 'tomato' },
      }}
    >
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Notifications" component={NotificationsScreen} />
      <Stack.Screen name="Profile" component={ProfileScreen} />
      <Stack.Screen name="Settings" component={SettingsScreen} />
    </Stack.Navigator>
  );
}

export default function App() {
  return (
    <NavigationContainer>
      <MyStack />
    </NavigationContainer>
  );
}

使用说明

以下为 @react-native-ohos/native-stack 的常用使用场景：

自定义头部与屏幕选项

通过 screenOptions 或单个屏幕的 options 配置标题栏的显示与样式：

<Stack.Navigator
  screenOptions={{
    headerShown: true,
    headerStyle: { backgroundColor: '#f4511e' },
    headerTintColor: '#fff',
  }}
>
  <Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>

模态与透明页面

通过 presentation 设置页面的呈现方式（card / modal / transparentModal）：

<Stack.Screen
  name="Modal"
  component={ModalScreen}
  options={{ presentation: 'modal' }}
/>

转场动画

通过 animation 设置页面切换时的转场动画（fade / slide_from_bottom / none 等）：

<Stack.Screen
  name="Details"
  component={DetailsScreen}
  options={{ animation: 'slide_from_bottom' }}
/>

隐藏标题栏

通过 headerShown: false 隐藏页面标题栏，实现全屏内容展示：

<Stack.Screen
  name="FullScreen"
  component={FullScreenScreen}
  options={{ headerShown: false }}
/>

接口说明

以下为@react-native-ohos/native-stack结合鸿蒙化@react-native-ohos/react-native-screens使用的基本属性，属性已验证，更多属性详情请查看 react-navigation/native-stack 的文档介绍

Props

Name	Description	Type	Required	Platform	OpenHarmony平台支持
id	为导航器设置一个可选的唯一标识符。该 ID 可用于在子导航器中通过 navigation.getParent 方法引用此导航器	string	no	all	yes
initialRouteName	指定导航器首次加载时要渲染的初始路由名称.	string	no	all	yes
screenOptions	为此导航器中所有屏幕配置默认的选项对象，用于统一设置屏幕的呈现方式.	object	no	all	yes

Options & screenOptions

Name	Description	Type	Required	Platform	OpenHarmony平台支持
title	可用作headerTitle回退的字符串.	string	no	all	yes
headerBackButtonMenuEnabled	布尔值，指示在长按 iOS 14 及以上版本的返回按钮时是否显示菜单，默认为 true	boolean	no	iOS	no
headerBackVisible	返回按钮在标题栏中是否可见。如果已指定 headerLeft，可以使用此属性在 headerLeft 旁边显示返回按钮.	boolean	no	Android,iOS	yes
headerBackTitle	iOS 上返回按钮使用的标题字符串。默认为上一个场景的标题，如果空间不足则为 "Back"。使用 headerBackTitleVisible: false 可隐藏.	string	no	iOS	yes
headerBackTitleStyle	标题栏返回标题的样式对象.	object	no	iOS	yes
headerBackImageSource	在标题栏中显示为返回按钮图标的图像.	string	no	all	yes
headerLargeStyle	显示大标题时的标题栏样式.	object	no	iOS	no
headerLargeTitle	是否启用大标题，滚动时折叠为常规标题.	string	no	iOS	no
headerLargeTitleShadowVisible	显示大标题时标题栏的投影是否可见.	boolean	no	iOS	no
headerLargeTitleStyle	标题栏中大标题的样式对象.	object	no	iOS	no
headerShown	是否显示标题栏。默认显示标题栏。设置为 false 可隐藏标题栏.	boolean	no	all	yes
headerStyle	标题栏的样式对象.	object	no	all	yes
headerShadowVisible	是否隐藏标题上的标高阴影 (Android) 或底部边框 (iOS)。	boolean	no	Android,iOS	yes
headerTransparent	指示导航栏是否半透明的布尔值.	boolean	no	all	yes
headerBlurEffect	半透明标题的模糊效果。 headerTransparent 选项需要设置为 true 才能正常工作.	string	no	iOS	no
headerBackground	返回一个 React 元素以呈现为标题背景的函数。这对于使用图像或渐变等背景非常有用.	function	no	all	yes
headerTintColor	标题的色调颜色。更改后退按钮和标题的颜色.	string	no	all	yes
headerLeft	返回一个 React 元素以显示在标题左侧的函数。这取代了后退按钮。请参阅 headerBackVisible 以显示左侧元素的后退按钮.	function	no	all	yes
headerRight	返回一个 React 元素以显示在标题右侧的函数.	function	no	all	yes
headerTitle	字符串或返回要由标头使用的 React 元素的函数。默认为屏幕的标题或名称.	string | function	no	all	yes
headerTitleAlign	如何对齐标题标题。在 iOS 以外的平台上默认为左对齐。iOS 不支持。它始终以 iOS 为中心，无法更改.	'left' | 'center'	no	Android	yes
headerTitleStyle	标题的样式对象.	object	no	all	yes
headerSearchBarOptions	在 iOS 上呈现本机搜索栏的选项.	object	no	Android,iOS	yes
header	使用自定义标头代替默认标头.	function	no	all	yes
statusBarAnimation	设置状态栏动画（类似于 StatusBar 组件）。默认在 iOS 上淡入淡出，在 Android 上不淡入淡出.	'fade' | 'none' | 'slide'	no	Android,iOS	no
statusBarHidden	状态栏是否应在此屏幕上隐藏.	boolean	no	Android,iOS	yes
statusBarStyle	设置状态栏颜色（类似于 StatusBar 组件）。默认为自动.	string	no	Android,iOS	yes
statusBarColor	设置状态栏颜色（类似于 StatusBar 组件）。默认为初始状态栏颜色。	string	no	Android	yes
statusBarTranslucent	设置状态栏的半透明度（类似于StatusBar组件）。默认为 false.	boolean	no	Android	yes
contentStyle	场景内容的样式对象.	object	no	all	yes
customAnimationOnGesture	关闭手势是否应使用提供给动画道具的动画。默认为 false	boolean	no	iOS	yes
fullScreenGestureEnabled	关闭手势是否适用于整个屏幕。使用手势来关闭此选项会产生与 simple_push 相同的过渡动画。可以通过设置 customAnimationOnGesture 属性来更改此行为。由于平台限制，无法实现默认的 iOS 动画。默认为 false。	boolean	no	iOS	yes
gestureEnabled	是否可以使用手势关闭此屏幕。默认为 true。	boolean	no	iOS	yes
animationTypeForReplace	当此屏幕替换另一个屏幕时要使用的动画类型。默认为弹出。	'push' | 'pop'	no	Android,iOS	yes
animation	按下或弹出时屏幕应如何呈现动画。(ios_from_left,ios_from_right，6.9.26版本不支持，flip实际效果为位移动画，与default效果一致。)	'default' | 'fade' | 'fade_from_bottom' | 'simple_push' | 'slide_from_bottom' | 'slide_from_right' | 'slide_from_left' | 'none' | 'flip' | 'ios_from_left' | 'ios_from_right'	no	Android,iOS	yes
presentation	画面应该如何呈现。	'card' | 'modal' | 'transparentModal' | 'containedModal' | 'fullScreenModal' | 'formSheet'	no	Android,iOS	yes
orientation	屏幕使用的显示方向。	'default' | 'all' | 'portrait' | 'portrait_up' | 'portrait_down' | 'landscape' | 'landscape_left' | 'landscape_right'	no	Android,iOS	yes
autoHideHomeIndicator	指示主页指示器是否应该保持隐藏的布尔值。默认为 false。	boolean	no	iOS	yes
gestureDirection	设置滑动以关闭屏幕的方向。	'vertical' | 'horizontal'	no	iOS	yes
animationDuration	slide_from_bottom、fade_from_bottom、fade 和 simple_push 过渡的持续时间（以毫秒为单位）。默认为 350。	number	no	iOS	yes
navigationBarColor	设置导航栏颜色。默认为初始状态栏颜色。	string	no	Android	no
navigationBarHidden	指示是否应隐藏导航栏的布尔值。默认为 false。	boolean	no	Android	no
freezeOnBlur	布尔值，指示是否阻止非活动屏幕重新渲染。默认为 false。当react-native-screens包中的enableFreeze()在应用程序顶部运行时，默认为true。	boolean	no	Android,iOS	yes

Events

Name	Description	Type	Required	Platform	OpenHarmony平台支持
transitionStart	当当前屏幕的过渡动画开始时，会触发此事件。	function	no	all	yes
transitionEnd	当当前屏幕的过渡动画结束时，会触发此事件。	function	no	all	yes

遗留问题

无

其他

无

目录结构

/rntpc_react-navigation  # 项目根目录
├── packages             # 多包工程（workspace）
│    ├── native-stack    # @react-native-oh-tpl/native-stack
│    │    ├── src        # RN 代码
│    │    │    └── index.tsx  # 入口文件
│    │    ├── README.md  # 中文安装使用方法
│    │    └── README_en.md  # 英文安装使用方法
│    ├── stack           # @react-native-oh-tpl/stack
│    ├── drawer          # @react-native-oh-tpl/drawer
│    ├── elements        # @react-native-oh-tpl/elements
│    ├── react-native-drawer-layout  # react-native-drawer-layout
│    ├── react-native-tab-view  # @react-native-oh-tpl/react-native-tab-view
│    └── react-navigation-tabs  # @react-native-oh-tpl/react-navigation-tabs
├── README.md           # 仓库说明
└── LICENSE             # 开源协议

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

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