Expo NavigationBar

一个用于访问 Android 原生导航栏各种交互的库。

Android

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~5.0.10

expo-navigation-bar 使你能够修改并观察 Android 设备上的原生导航栏。由于某些 Android 平台限制，此 API 的部分功能与 expo-status-bar API 重叠。

属性以样式属性命名；例如 visibility、position、backgroundColor、borderColor 等。

当 Android 设备启用“手势导航”时，此包中的 API 不会产生任何影响。目前没有原生 Android API 可以检测是否启用了“手势导航”。

安装

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.

在 app config 中配置

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

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-navigation-bar",
        {
          "backgroundColor": "#0f172a",
          "barStyle": "light",
          "borderColor": "#1f2937",
          "visibility": "visible",
          "behavior": "inset-swipe",
          "position": "relative"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`backgroundColor`	`undefined`	设置导航栏背景颜色。接受 React Native 支持的颜色字符串。例如，`"#0f172a"`。
`barStyle`	`undefined`	控制 Android 显示浅色还是深色的导航栏按钮。可接受 `light` 和 `dark` 作为值。
`borderColor`	`undefined`	设置导航栏上方分隔线的颜色。
`visibility`	`undefined`	决定导航栏初始时是显示还是隐藏。接受 `visible` 表示立即显示导航栏，接受 `hidden` 表示隐藏导航栏，直到用户通过系统手势将其显示出来。
`behavior`	`undefined`	控制隐藏的系统栏被重新显示时的行为。可接受 `overlay-swipe`、`inset-swipe` 或 `inset-touch` 作为值。
`position`	`undefined`	设置你的布局是否为导航栏预留内边距。接受 `relative` 表示将导航栏保留在内容之外，接受 `absolute` 表示让内容边缘到边缘地绘制在导航栏下方。
`legacyVisible`	`undefined`	`androidNavigationBar.visible` 的旧版等价项。可接受 `leanback`、`immersive` 或 `sticky-immersive` 作为值。

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

如果你没有使用 Continuous Native Generation（CNG），或者你是手动使用原生 android 项目，则需要向原生项目添加以下配置：

要将 backgroundColor 应用于导航栏，请在 android/app/src/main/res/values/colors.xml 中添加 navigationBarColor：

<resources>
  <!-- ... -->
  <color name="navigationBarColor">#0f172a</color>
</resources>

然后，在 android/app/src/main/res/values/styles.xml 中应用 android:navigationBarColor：

<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
  <!-- ... -->
  <item name="android:navigationBarColor">@color/navigationBarColor</item>
</style>

要将 borderColor、visibility、position 和 behavior 应用于导航栏，请在 android/app/src/main/res/values/strings.xml 中添加 expo_navigation_bar_border_color、expo_navigation_bar_visibility、expo_navigation_bar_position 和 expo_navigation_bar_behavior：

<resources>
  <!-- ... -->
  <!-- 对于 `expo_navigation_bar_border_color`，请将颜色字符串转换为 32 位整数。 -->
  <string name="expo_navigation_bar_border_color"
  translatable="false">-14735049</string>
  <string name="expo_navigation_bar_visibility" translatable="false">visible</string>
  <string name="expo_navigation_bar_position" translatable="false">relative</string>
  <string name="expo_navigation_bar_behavior" translatable="false">inset-swipe</string>
</resources>

要将 legacyVisible 应用于导航栏，请在 android/app/src/main/res/values/strings.xml 中添加 expo_navigation_bar_legacy_visible：

<resources>
  <!-- ... -->
  <string name="expo_navigation_bar_legacy_visible" translatable="false">immersive</string>
</resources>

API

import * as NavigationBar from 'expo-navigation-bar';

Hooks

`useVisibility()`

Android

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.

Example

function App() {
  const visibility = NavigationBar.useVisibility()
  // React Component...
}

Methods

`NavigationBar.getBackgroundColorAsync()`

Android

Gets the navigation bar's background color.

Returns:

Promise<string>

Current navigation bar color in hex format. Returns #00000000 (transparent) on unsupported platforms (iOS, web).

Example

const color = await NavigationBar.getBackgroundColorAsync();

`NavigationBar.getBehaviorAsync()`

Android

Gets the behavior of the status and navigation bars when the user swipes or touches the screen.

Returns:

Promise<NavigationBarBehavior>

Navigation bar interaction behavior. Returns inset-touch on unsupported platforms (iOS, web).

Example

await NavigationBar.getBehaviorAsync()

`NavigationBar.getBorderColorAsync()`

Android

Gets the navigation bar's top border color, also known as the "divider color".

Returns:

Promise<string>

Navigation bar top border color in hex format. Returns #00000000 (transparent) on unsupported platforms (iOS, web).

Example

const color = await NavigationBar.getBorderColorAsync();

`NavigationBar.getButtonStyleAsync()`

Android

Gets the navigation bar's button color styles.

Returns:

Promise<NavigationBarButtonStyle>

Navigation bar foreground element color settings. Returns light on unsupported platforms (iOS, web).

Example

const style = await NavigationBar.getButtonStyleAsync();

`NavigationBar.getVisibilityAsync()`

Android

Get the navigation bar's visibility.

Returns:

Promise<NavigationBarVisibility>

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

Example

const visibility = await NavigationBar.getVisibilityAsync("hidden");

`NavigationBar.setBackgroundColorAsync(color)`

Android

Parameter	Type	Description
color	`string`	Any valid CSS 3 (SVG) color.

Changes the navigation bar's background color.

Returns:

Promise<void>

Example

NavigationBar.setBackgroundColorAsync("white");

`NavigationBar.setBehaviorAsync(behavior)`

Android

Parameter	Type	Description
behavior	`NavigationBarBehavior`	Dictates the interaction behavior of the navigation bar.

Sets the behavior of the status bar and navigation bar when they are hidden and the user wants to reveal them.

For example, if the navigation bar is hidden (setVisibilityAsync(false)) and the behavior is 'overlay-swipe', the user can swipe from the bottom of the screen to temporarily reveal the navigation bar.

'overlay-swipe': Temporarily reveals the System UI after a swipe gesture (bottom or top) without insetting your App's content.
'inset-swipe': Reveals the System UI after a swipe gesture (bottom or top) and insets your App's content (Safe Area). The System UI is visible until you explicitly hide it again.
'inset-touch': Reveals the System UI after a touch anywhere on the screen and insets your App's content (Safe Area). The System UI is visible until you explicitly hide it again.

Returns:

Promise<void>

Example

await NavigationBar.setBehaviorAsync('overlay-swipe')

`NavigationBar.setBorderColorAsync(color)`

Android

Parameter	Type	Description
color	`string`	Any valid CSS 3 (SVG) color.

Changes the navigation bar's border color.

Returns:

Promise<void>

Example

NavigationBar.setBorderColorAsync("red");

`NavigationBar.setButtonStyleAsync(style)`

Android

Parameter	Type	Description
style	`NavigationBarButtonStyle`	Dictates the color of the foreground element color.

Changes the navigation bar's button colors between white (light) and a dark gray color (dark).

Returns:

Promise<void>

Example

NavigationBar.setButtonStyleAsync("light");

`NavigationBar.setPositionAsync(position)`

Android

Parameter	Type	Description
position	`NavigationBarPosition`	Based on CSS position property.

Sets positioning method used for the navigation bar (and status bar). Setting position absolute will float the navigation bar above the content, whereas position relative will shrink the screen to inline the navigation bar.

When drawing behind the status and navigation bars, ensure the safe area insets are adjusted accordingly.

Returns:

Promise<void>

Example

// enables edge-to-edge mode
await NavigationBar.setPositionAsync('absolute')
// transparent backgrounds to see through
await NavigationBar.setBackgroundColorAsync('#ffffff00')

`NavigationBar.setStyle(style)`

Android

Parameter	Type
style	`NavigationBarStyle`

Sets the style of the navigation bar.

Returns:

void

`NavigationBar.setVisibilityAsync(visibility)`

Android

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

Set the navigation bar's visibility.

Returns:

Promise<void>

Example

NavigationBar.setVisibilityAsync("hidden");

`NavigationBar.unstable_getPositionAsync()`

Android

Whether the navigation and status bars float above the app (absolute) or sit inline with it (relative). This value can be incorrect if androidNavigationBar.visible is used instead of the config plugin position property.

This method is unstable because the position can be set via another native module and get out of sync. Alternatively, you can get the position by measuring the insets returned by react-native-safe-area-context.

Returns:

Promise<NavigationBarPosition>

Navigation bar positional rendering mode. Returns relative on unsupported platforms (iOS, web).

Example

await NavigationBar.unstable_getPositionAsync()

Event Subscriptions

`NavigationBar.addVisibilityListener(listener)`

Android

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

Example

NavigationBar.addVisibilityListener(({ visibility }) => {
  // ...
});

Types

`NavigationBarBehavior`

Android

Literal Type: string

Interaction behavior for the system navigation bar.

Acceptable values are: 'overlay-swipe' | 'inset-swipe' | 'inset-touch'

`NavigationBarButtonStyle`

Android

Literal Type: string

Appearance of the foreground elements in the navigation bar, i.e. the color of the menu, back, home button icons.

dark makes buttons darker to adjust for a mostly light nav bar.
light makes buttons lighter to adjust for a mostly dark nav bar.

Acceptable values are: 'light' | 'dark'

`NavigationBarPosition`

Android

Literal Type: string

Navigation bar positional mode.

Acceptable values are: 'relative' | 'absolute'

`NavigationBarStyle`

Android

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'

`NavigationBarVisibility`

Android

Literal Type: string

Visibility of the navigation bar.

Acceptable values are: 'visible' | 'hidden'

`NavigationBarVisibilityEvent`

Android

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.