Expo SplashScreen

一个用于控制原生启动屏幕显示行为的库。

Android

iOS

tvOS

GitHub

npm

更新日志

Recommended version:

~58.0.0

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

// Set the animation options. This is optional.
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';

// 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>
  );
}

延迟隐藏启动屏幕

在某些情况下，可能需要等到特定资源加载完毕后再隐藏启动屏幕。例如，如果你需要在显示应用内容前加载 API 数据，可以使用 preventAutoHideAsync() 手动控制启动屏幕何时隐藏。目标应当是尽可能早地隐藏启动屏幕。

app/_layout.tsx

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 />;
}

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

// 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>
  );
}

配置

如果你的项目使用配置插件（连续原生生成（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`	A hex color string representing the background color of the splash screen.
`image`	`undefined`	The path to the image file that will be displayed on the splash screen. This should be your app icon or logo.
`enableFullScreenImage_legacy`	`false`	Only for: iOS Enabling this property allows using a full screen image as the splashscreen. This is to help with the transition from the legacy splash screen configuration and will be removed in the future.
`dark`	`undefined`	An object containing properties for configuring the splash screen when the device is in dark mode.
`imageWidth`	`100`	The width to make the image.
`android`	`undefined`	An object containing properties for configuring the splash screen on Android.
`ios`	`undefined`	An object containing properties for configuring the splash screen on iOS.
`resizeMode`	`undefined`	Determines how the image is scaled to fit the container defined by `imageWidth`. Possible values: `contain`, `cover`, or `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`