Expo NavigationBar

一个库，提供对 Android 原生导航栏的各种交互访问。

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.0

expo-navigation-bar 提供了一个组件和一个命令式 API，用于控制 Android 设备上的应用导航栏，允许你更改其按钮的颜色或将其隐藏。

安装

Terminal

- npx expo install expo-navigation-bar

If you are installing this in an existing React Native app, make sure to install expo in your project.

应用配置中的配置

如果你在项目中使用配置插件（Continuous Native Generation (CNG)），你可以使用 expo-navigation-bar 自带的 config plugin 进行配置。该插件允许你配置某些无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-navigation-bar",
        {
          "enforceContrast": true,
          "hidden": false,
          "style": "light"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`enforceContrast`	`true`	Only for: Android 确定操作系统是否应保持导航栏半透明，以便在导航按钮和应用内容之间提供对比度。对 Android 9 及以下版本无效。
`hidden`	`undefined`	Only for: Android 确定状态栏是否在启动时隐藏。可接受 `true` 和 `false` 作为值。
`style`	`undefined`	Only for: Android 确定导航栏启动时使用的样式。可接受 `light` 和 `dark` 作为值。

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation (CNG)，或者你是手动使用原生 android 项目，那么你需要将以下配置添加到你的原生项目中：

要在 Android 上隐藏导航栏，请将 expoNavigationBarHidden 添加到 android/app/src/main/res/values/styles.xml 中：

<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
  <!-- ... -->
  <item name="expoNavigationBarHidden">true</item>
</style>

用法

Example

import { StyleSheet, Text, View } from 'react-native';
import { NavigationBar } from 'expo-navigation-bar';

export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>请注意，导航栏有浅色按钮！</Text>
      <NavigationBar style="light" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#000',
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    color: '#fff',
  },
});

API

import { NavigationBar } from 'expo-navigation-bar';

Component

`NavigationBar`

Type: React.Element<NavigationBarProps>

A component that allows you to configure your navigation bar declaratively.

You will likely have multiple NavigationBar components mounted in the same app at the same time. For example, if you have multiple screens in your app, you may end up using one per screen. The props of each NavigationBar component will be merged in the order that they were mounted.

NavigationBarProps

`hidden`

Optional • Type: boolean

If the navigation bar is hidden.

`style`

Optional • Type: NavigationBarStyle • Default: 'auto'

Sets the color of the navigation bar buttons. Default value is "auto" which picks the appropriate value according to the active color scheme, eg: if your app is dark mode, the style will be "light".

This will have an effect when the following conditions are met:

The device navigation bar is using buttons.

The enforceContrast option of the expo-navigation-bar plugin is set to false.

Due to a bug in the Android 15 emulator this function may have no effect. Try a physical device or an emulator with a different version of Android.

Component methods

`setHidden(hidden)`

Only for:

Android

Parameter	Type	Description
hidden	`boolean`	If the navigation bar should be hidden.

Set the navigation bar's visibility.

Returns:

void

Example

NavigationBar.setHidden(true);

`setStyle(style)`

Only for:

Android

Parameter	Type	Description
style	`NavigationBarStyle`	The color of the navigation bar buttons.

Sets the style of the navigation bar.

This will have an effect when the following conditions are met:

The device navigation bar is using buttons.

The enforceContrast option of the expo-navigation-bar plugin is set to false.

Due to a bug in the Android 15 emulator this function may have no effect. Try a physical device or an emulator with a different version of Android.

Returns:

void

Example

NavigationBar.setStyle("dark");

Hooks

Deprecated: This will be removed in a future release.

`useVisibility()`

React hook that statefully updates with the visibility of the system navigation bar.

Returns:

NavigationBarVisibility | null

Visibility of the navigation bar, null during async initialization.

Methods

Deprecated: This will be removed in a future release.

`NavigationBar.getVisibilityAsync()`

Get the navigation bar's visibility.

Returns:

Promise<NavigationBarVisibility>

Navigation bar's current visibility status. Returns hidden on unsupported platforms (iOS, web).

Deprecated: Use NavigationBar.setStyle instead. This will be removed in a future release.

`NavigationBar.setStyle(style)`

Parameter	Type	Description
style	`NavigationBarStyle`	The color of the navigation bar buttons.

Returns:

void

Deprecated: Use NavigationBar.setHidden instead. This will be removed in a future release.

`NavigationBar.setVisibilityAsync(visibility)`

Only for:

Android

Parameter	Type	Description
visibility	`NavigationBarVisibility`	Based on CSS visibility property.

Set the navigation bar's visibility.

Returns:

Promise<void>

Event subscriptions

Deprecated: This will be removed in a future release.

`NavigationBar.addVisibilityListener(listener)`

Parameter	Type
listener	`(event: NavigationBarVisibilityEvent) => void`

Observe changes to the system navigation bar. Due to platform constraints, this callback will also be triggered when the status bar visibility changes.

Returns:

EventSubscription

Types

`NavigationBarStyle`

Literal type: string

Navigation bar style.

auto will automatically adjust based on the current theme.
light a light navigation bar with dark content.
dark a dark navigation bar with light content.
inverted the bar colors are inverted in relation to the current theme.

Acceptable values are: 'auto' | 'inverted' | 'light' | 'dark'

Deprecated: This will be removed in a future release.

`NavigationBarVisibility`

Literal type: string

Visibility of the navigation bar.

Acceptable values are: 'visible' | 'hidden'

Deprecated: This will be removed in a future release.

`NavigationBarVisibilityEvent`

Current system UI visibility state. Due to platform constraints, this will return when the status bar visibility changes as well as the navigation bar.

Property	Type	Description
rawVisibility	`number`	Native Android system UI visibility state, returned from the native Android `setOnSystemUiVisibilityChangeListener` API.
visibility	`NavigationBarVisibility`	Current navigation bar visibility.