Expo SplashScreen

expo-splash-screen 库中的 SplashScreen 模块提供了对原生启动屏行为的控制。默认情况下，当应用准备好时，启动屏会自动隐藏，但你也可以在高级使用场景中手动控制其可见性。

🌐 The SplashScreen module from the expo-splash-screen library provides control over the native splash screen behavior. By default, the splash screen will automatically hide when your app is ready, but you can also manually control its visibility for advanced use cases.

从 SDK 52 开始，由于支持最新 Android 启动画面 API 的更改，Expo Go 和开发构建无法完全复制用户在你的 独立应用 中看到的启动画面体验。Expo Go 将显示你的应用图标而不是启动画面，并且开发构建中的启动画面不会反映配置插件中设置的所有属性。强烈建议你在发布构建上测试启动画面，以确保其显示效果符合预期。

另外，请参阅关于创建启动画面图片的指南，或使用浏览器快速生成图标和启动画面。

🌐 Also, see the guide on creating a splash screen image, or quickly generate an icon and splash screen using your browser.

安装

🌐 Installation

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

用法

🌐 Usage

对于大多数应用，你无需对启动屏做任何特殊操作。当应用准备就绪时，它会自动隐藏。你可以选择配置动画选项：

🌐 For most apps, you don't need to do anything special with the splash screen. It will automatically hide when your app is ready. You can optionally configure animation options:

import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';

// Set the animation options. This is optional.
SplashScreen.setOptions({
  duration: 1000,
  fade: true,
});

export default function RootLayout() {
  return <Stack />;
}

import { Text, View } from 'react-native';
import Entypo from '@expo/vector-icons/Entypo';
import * as SplashScreen from 'expo-splash-screen';

// Set the animation options. This is optional.
SplashScreen.setOptions({
  duration: 1000,
  fade: true,
});

export default function App() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>SplashScreen Demo! 👋</Text>
      <Entypo name="rocket" size={30} />
    </View>
  );
}

延迟隐藏启动画面

🌐 Delay hiding the splash screen

在某些情况下，可能需要延迟隐藏启动画面，直到某些资源加载完成。例如，如果你需要在显示应用内容之前加载 API 数据，可以使用 preventAutoHideAsync() 来手动控制启动画面何时隐藏。目标应该是尽快隐藏启动画面。

🌐 In some cases, it may be necessary to delay hiding the splash screen until certain resources are loaded. For example, if you need to load API data before displaying the app content, you can use preventAutoHideAsync() to manually control when the splash screen hides. The goal should be to hide the splash screen as soon as possible.

import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';
import { useEffect, useState } from 'react';

// Keep the splash screen visible while we fetch resources
SplashScreen.preventAutoHideAsync();

export default function RootLayout() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    async function doAsyncStuff() {
      try {
        // do something async here
      } catch (e) {
        console.warn(e);
      } finally {
        setIsReady(true);
      }
    }

    doAsyncStuff();
  }, []);

  useEffect(() => {
    if (isReady) {
      SplashScreen.hide();
    }
  }, [isReady]);

  if (!isReady) {
    return null;
  }

  return <Stack />;
}

import { useCallback, useEffect, useState } from 'react';
import { Text, View } from 'react-native';
import Entypo from '@expo/vector-icons/Entypo';
import * as SplashScreen from 'expo-splash-screen';

// Keep the splash screen visible while we fetch resources
SplashScreen.preventAutoHideAsync();

export default function App() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    async function doAsyncStuff() {
      try {
        // do something async here
      } catch (e) {
        console.warn(e);
      } finally {
        setIsReady(true);
      }
    }

    doAsyncStuff();
  }, []);

  useEffect(() => {
    if (isReady) {
      SplashScreen.hideAsync();
    }
  }, [isReady]);

  if (!isReady) {
    return null;
  }

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>SplashScreen Demo! 👋</Text>
      <Entypo name="rocket" size={30} />
    </View>
  );
}

配置

🌐 Configuration

如果你在项目中使用配置插件（连续原生生成 (CNG)），可以使用其内置的 配置插件 来配置 expo-splash-screen。该插件允许你配置无法在运行时设置并且需要构建新的应用二进制文件才能生效的各种属性。如果你的应用不使用 CNG，则需要手动配置该库。

🌐 You can configure expo-splash-screen using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

使用如下所示的配置插件，是配置启动画面的推荐方法。 其他方法现在被认为是过时的，将来会被移除。

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-splash-screen",
        {
          "backgroundColor": "#232323",
          "image": "./assets/splash-icon.png",
          "dark": {
            "image": "./assets/splash-icon-dark.png",
            "backgroundColor": "#000000"
          },
          "imageWidth": 200
        }
      ]
    ],
  }
}

Configurable properties

你也可以使用以下 应用配置 属性来配置 expo-splash-screen，但建议优先使用配置插件。

🌐 You can also configure expo-splash-screen, using the following app config properties but the config plugin should be preferred.

• splash
• android.splash
• ios.splash

动画启动画面

🌐 Animating the splash screen

SplashScreen 提供了开箱即用的淡出动画。可以使用 setOptions 方法进行配置。

SplashScreen.setOptions({
  duration: 1000,
  fade: true,
});

如果你希望使用自定义动画，请参阅 with-splash-screen 示例，了解如何将任意动画应用到启动屏幕上。你可以通过运行 npx create-expo-app --example with-splash-screen 从此示例初始化一个新项目。

🌐 If you prefer to use custom animation, see the with-splash-screen example on how to apply any arbitrary animations to your splash screen. You can initialize a new project from this example by running npx create-expo-app --example with-splash-screen.

应用接口

🌐 API

import * as SplashScreen from 'expo-splash-screen';

Methods

import * as SplashScreen from 'expo-splash-screen';

SplashScreen.preventAutoHideAsync();

export default function App() {
 // ...
}

Types