This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

Expo 启动画面

一个用于控制原生启动画面可见性行为的库。

Android

iOS

tvOS

GitHub

npm

更新日志

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

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

另请参阅关于创建启动画面图片的指南。

安装

Terminal

- npx expo install expo-splash-screen

- yarn expo install expo-splash-screen

- pnpm expo install expo-splash-screen

- bun expo install expo-splash-screen

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

用法

对于大多数应用来说，你不需要对启动画面做任何特殊处理。它会在应用准备就绪时自动隐藏。你也可以选择配置动画选项：

app/_layout.tsx

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

// 设置动画选项。这是可选的。
SplashScreen.setOptions({
  duration: 1000,
  fade: true,
});

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

App.tsx

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

// 设置动画选项。这是可选的。
SplashScreen.setOptions({
  duration: 1000,
  fade: true,
});

export default function App() {
  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>启动画面演示！👋</Text>
      <Entypo name="rocket" size={30} />
    </View>
  );
}

延迟隐藏启动画面

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

app/_layout.tsx

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

// 在我们获取资源期间保持启动画面可见
SplashScreen.preventAutoHideAsync();

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

  useEffect(() => {
    async function doAsyncStuff() {
      try {
        // 在这里执行一些异步操作
      } catch (e) {
        console.warn(e);
      } finally {
        setIsReady(true);
      }
    }

    doAsyncStuff();
  }, []);

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

  if (!isReady) {
    return null;
  }

  return <Stack />;
}

App.tsx

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';

// 在我们获取资源期间保持启动画面可见
SplashScreen.preventAutoHideAsync();

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

  useEffect(() => {
    async function doAsyncStuff() {
      try {
        // 在这里执行一些异步操作
      } 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>启动画面演示！👋</Text>
      <Entypo name="rocket" size={30} />
    </View>
  );
}

配置

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

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

Example app.json with config plugin

app.json

{
  "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

Name	Default	Description
`backgroundColor`	`#ffffff`	表示启动画面背景颜色的十六进制颜色字符串。
`image`	`undefined`	将在启动画面上显示的图片文件路径。这应该是你的应用图标或徽标。
`enableFullScreenImage_legacy`	`false`	Only for: iOS 启用此属性后，可以将全屏图片用作启动画面。这有助于从旧版启动画面配置过渡，并将在未来移除。
`dark`	`undefined`	包含在设备处于深色模式时用于配置启动画面的属性的对象。
`imageWidth`	`100`	设置图片宽度。
`android`	`undefined`	包含用于配置 Android 上启动画面的属性的对象。
`ios`	`undefined`	包含用于配置 iOS 上启动画面的属性的对象。
`resizeMode`	`undefined`	决定图片如何缩放以适应由 `imageWidth` 定义的容器。可选值：`contain`、`cover` 或 `native`。

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

查看 expo-splash-screen 仓库中的安装说明，了解如何配置原生项目。

启动画面动画

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

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

如果你更喜欢使用自定义动画，请查看 with-splash-screen 示例，了解如何为启动画面应用任意动画。你可以通过运行 npx create-expo-app --example with-splash-screen 基于此示例初始化一个新项目。

API

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

Props

`android`

Android

Optional • Type: Partial<AndroidSplashConfig>

Properties for configuring the splash screen on Android.

`backgroundColor`

Android

iOS

tvOS

Optional • Type: string • Default: "#ffffff"

Hex color for the splash screen background.

`dark`

Android

iOS

tvOS

Optional • Type:

{
  backgroundColor: string, 
  image: string
}

Properties for configuring the splash screen in dark mode.

`enableFullScreenImage_legacy`

Android

iOS

tvOS

Optional • Type: boolean • Default: false

Whether to use a full screen image as the splash screen. Legacy transition helper, will be removed.

`image`

Android

iOS

tvOS

Optional • Type: string

Path to the image displayed on the splash screen.

`imageWidth`

Android

iOS

tvOS

Optional • Type: number • Default: 100

The width to make the image.

`ios`

iOS

Optional • Type: Partial<IOSSplashConfig>

Properties for configuring the splash screen on iOS.

`resizeMode`

Android

iOS

tvOS

Optional • Literal type: string • Default: "contain"

How the image is scaled. Accepts contain, cover, native.

Acceptable values are: 'contain' | 'cover' | 'native'

Methods

`SplashScreen.hide()`

Android

iOS

tvOS

Hides the native splash screen immediately. Be careful to ensure that your app has content ready to display when you hide the splash screen, or you may see a blank screen briefly. See the "Usage" section for an example.

Returns:

void

`SplashScreen.hideAsync()`

Android

iOS

tvOS

Hides the native splash screen immediately. This method is provided for backwards compatibility. See the "Usage" section for an example.

Returns:

Promise<void>

`SplashScreen.preventAutoHideAsync()`

Android

iOS

tvOS

Makes the native splash screen (configured in app.json) remain visible until hideAsync is called.

Important note: It is recommended to call this in global scope without awaiting, rather than inside React components or hooks, because otherwise this might be called too late, when the splash screen is already hidden.

Returns:

Promise<boolean>

Example

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

SplashScreen.preventAutoHideAsync();

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

`SplashScreen.setOptions(options)`

Android

iOS

tvOS

Parameter	Type
options	`SplashScreenOptions`

Configures the splashscreens default animation behavior.

Returns:

void

Types

`SplashScreenOptions`

Android

iOS

tvOS

Property	Type	Description
duration(optional)	`number`	The duration of the fade out animation in milliseconds. Default:`400`
fade(optional)	`boolean`	Only for: iOS Whether to hide the splash screen with a fade out animation. Default:`false`