Skip to main content
Version: 7.x

主题

主题允许你更改 React Navigation 提供的各种组件的颜色和字体。你可以使用主题来：

¥Themes allow you to change the colors and fonts of various components provided by React Navigation. You can use themes to:

  • 自定义颜色和字体以匹配你的品牌

    ¥Customize the colors and fonts to match your brand

  • 根据一天中的时间或用户偏好提供浅色和深色主题

    ¥Provide light and dark themes based on the time of the day or user preference

基本用法​

¥Basic usage

要传递自定义主题，你可以将 theme 属性传递给导航容器。

¥To pass a custom theme, you can pass the theme prop to the navigation container.

import * as React from 'react';
import {
  useNavigation,
  createStaticNavigation,
  DefaultTheme,
} from '@react-navigation/native';

const MyTheme = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    background: 'rgb(140, 201, 125)',
    primary: 'rgb(255, 45, 85)',
  },
};

const Navigation = createStaticNavigation(Drawer);

export default function App() {
  return <Navigation theme={MyTheme} />;
}
Try on Snack

你可以动态更改主题属性，所有组件将自动更新以反映新主题。如果你尚未提供 theme 属性，则将使用默认主题。

¥You can change the theme prop dynamically and all the components will automatically update to reflect the new theme. If you haven't provided a theme prop, the default theme will be used.

属性​

¥Properties

主题是一个 JS 对象，包含要使用的颜色列表。它包含以下属性：

¥A theme is a JS object containing a list of colors to use. It contains the following properties:

  • dark (boolean):这是深色主题还是浅色主题

    ¥dark (boolean): Whether this is a dark theme or a light theme

  • colors (object):React 导航组件使用的各种颜色：

    ¥colors (object): Various colors used by react navigation components:

    • primary (string):应用的主要颜色用于为各种元素着色。通常你需要为此使用你的品牌颜色。

      ¥primary (string): The primary color of the app used to tint various elements. Usually you'll want to use your brand color for this.

    • background (string):各种背景的颜色，例如屏幕的背景颜色。

      ¥background (string): The color of various backgrounds, such as the background color for the screens.

    • card (string):卡片式元素的背景颜色，例如标题、选项卡栏等。

      ¥card (string): The background color of card-like elements, such as headers, tab bars etc.

    • text (string):各种元素的文本颜色。

      ¥text (string): The text color of various elements.

    • border (string):边框的颜色，例如标题边框、标签栏边框等

      ¥border (string): The color of borders, e.g. header border, tab bar border etc.

    • notification (string):通知和徽章的颜色（例如底部选项卡中的徽章）。

      ¥notification (string): The color of notifications and badge (e.g. badge in bottom tabs).

  • fonts (object):React 导航组件使用的各种字体：

    ¥fonts (object): Various fonts used by react navigation components:

    • regular (object):应用中使用的主要字体的样式对象。

      ¥regular (object): Style object for the primary font used in the app.

    • medium (object):主要字体的半粗体变体的样式对象。

      ¥medium (object): Style object for the semi-bold variant of the primary font.

    • bold (object):主要字体的粗体变体的样式对象。

      ¥bold (object): Style object for the bold variant of the primary font.

    • heavy (object):主要字体的超粗体变体的样式对象。

      ¥heavy (object): Style object for the extra-bold variant of the primary font.

字体的样式对象包含以下属性：

¥The style objects for fonts contain the following properties:

  • fontFamily (string):要使用的字体系列（或 Web 上的字体堆栈）的名称，例如 Roboto 或 Helvetica Neue。默认使用系统字体。

    ¥fontFamily (string): The name of the font family (or font stack on Web) to use, e.g. Roboto or Helvetica Neue. The system fonts are used by default.

  • fontWeight (string):要使用的字体粗细。有效值为 normal、bold、100、200、300、400、500、600、700、800、900。

    ¥fontWeight (string): The font weight to use. Valid values are normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900.

创建自定义主题时，你需要提供所有这些属性。

¥When creating a custom theme, you will need to provide all of these properties.

主题示例：

¥Example theme:

const WEB_FONT_STACK =
  'system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"';

const MyTheme = {
  dark: false,
  colors: {
    primary: 'rgb(255, 45, 85)',
    background: 'rgb(242, 242, 242)',
    card: 'rgb(255, 255, 255)',
    text: 'rgb(28, 28, 30)',
    border: 'rgb(199, 199, 204)',
    notification: 'rgb(255, 69, 58)',
  },
  fonts: Platform.select({
    web: {
      regular: {
        fontFamily: WEB_FONT_STACK,
        fontWeight: '400',
      },
      medium: {
        fontFamily: WEB_FONT_STACK,
        fontWeight: '500',
      },
      bold: {
        fontFamily: WEB_FONT_STACK,
        fontWeight: '600',
      },
      heavy: {
        fontFamily: WEB_FONT_STACK,
        fontWeight: '700',
      },
    },
    ios: {
      regular: {
        fontFamily: 'System',
        fontWeight: '400',
      },
      medium: {
        fontFamily: 'System',
        fontWeight: '500',
      },
      bold: {
        fontFamily: 'System',
        fontWeight: '600',
      },
      heavy: {
        fontFamily: 'System',
        fontWeight: '700',
      },
    },
    default: {
      regular: {
        fontFamily: 'sans-serif',
        fontWeight: 'normal',
      },
      medium: {
        fontFamily: 'sans-serif-medium',
        fontWeight: 'normal',
      },
      bold: {
        fontFamily: 'sans-serif',
        fontWeight: '600',
      },
      heavy: {
        fontFamily: 'sans-serif',
        fontWeight: '700',
      },
    },
  }),
};

提供主题将负责所有官方导航器的样式。React Navigation 还提供了多种工具来帮助你自定义这些导航器，并且导航器中的屏幕也可以使用该主题。

¥Providing a theme will take care of styling of all the official navigators. React Navigation also provides several tools to help you make your customizations of those navigators and the screens within the navigators can use the theme too.

内置主题​

¥Built-in themes

随着操作系统添加了对浅色和夜间模式的内置支持，支持夜间模式不再是为了跟上潮流，而是为了符合普通用户对应用工作方式的期望。为了以与操作系统默认值相当一致的方式提供对浅色和夜间模式的支持，这些主题内置于 React Navigation 中。

¥As operating systems add built-in support for light and dark modes, supporting dark mode is less about keeping hip to trends and more about conforming to the average user expectations for how apps should work. In order to provide support for light and dark mode in a way that is reasonably consistent with the OS defaults, these themes are built in to React Navigation.

你可以像这样导入默认主题和深色主题：

¥You can import the default and dark themes like so:

import { DefaultTheme, DarkTheme } from '@react-navigation/native';

保持原生主题同步​

¥Keeping the native theme in sync

如果你正在更改应用中的主题，则原生 UI 元素（如 Alert、ActionSheet 等）将不会反映新主题。你可以执行以下操作以保持原生主题同步：

¥If you're changing the theme in the app, native UI elements such as Alert, ActionSheet etc. won't reflect the new theme. You can do the following to keep the native theme in sync:

React.useEffect(() => {
  const colorScheme = theme.dark ? 'dark' : 'light';

  if (Platform.OS === 'web') {
    document.documentElement.style.colorScheme = colorScheme;
  } else {
    Appearance.setColorScheme(colorScheme);
  }
}, [theme.dark]);

或者，你可以使用 useColorScheme 钩子获取当前原生配色方案并相应地更新主题。

¥Alternatively, you can use the useColorScheme hook to get the current native color scheme and update the theme accordingly.

使用操作系统首选项​

¥Using the operating system preferences

在 iOS 13+ 和 Android 10+ 上，你可以使用 (useColorScheme 钩) 获取用户首选的配色方案（'dark' 或 'light'）。

¥On iOS 13+ and Android 10+, you can get user's preferred color scheme ('dark' or 'light') with the (useColorScheme hook).

import {
  useNavigation,
  createStaticNavigation,
  DefaultTheme,
  DarkTheme,
  useTheme,
} from '@react-navigation/native';
import { View, Text, TouchableOpacity, useColorScheme } from 'react-native';

const Navigation = createStaticNavigation(Drawer);

export default function App() {
  const scheme = useColorScheme();

  return <Navigation theme={scheme === 'dark' ? DarkTheme : DefaultTheme} />;
}

Try on Snack

在你自己的组件中使用当前主题​

¥Using the current theme in your own components

要访问导航容器内渲染的任何组件中的主题：，你可以使用 useTheme 钩子。它返回主题对象：

¥To gain access to the theme in any component that is rendered inside the navigation container:, you can use the useTheme hook. It returns the theme object:

import {
  useNavigation,
  createStaticNavigation,
  DefaultTheme,
  DarkTheme,
  useTheme,
} from '@react-navigation/native';
import { View, Text, TouchableOpacity, useColorScheme } from 'react-native';

function MyButton() {
  const { colors } = useTheme();

  return (
    <TouchableOpacity style={{ backgroundColor: colors.card }}>
      <Text style={{ color: colors.text }}>Button!</Text>
    </TouchableOpacity>
  );
}
Try on Snack