Reference version

Expo 启动画面 iconExpo 启动画面

一个提供控制原生启动画面可见性行为访问权限的库。

Android
iOS
tvOS
Bundled version:
~0.30.10

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

expo-splash-screen 库中的 SplashScreen 模块用于通知启动画面保持可见,直到显式告知它隐藏为止。这对于在后台执行诸如 API 调用、预加载字体、为启动画面添加动画等任务很有用。

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

另请参阅 创建启动画面图片 的指南,或者 使用浏览器快速生成图标和启动画面

安装

Terminal
npx 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 { useFonts } from 'expo-font'; import { Stack } from 'expo-router'; import * as SplashScreen from 'expo-splash-screen'; import { useEffect } from 'react'; // 设置动画选项。这是可选的。 SplashScreen.setOptions({ duration: 1000, fade: true, }); SplashScreen.preventAutoHideAsync(); export default function RootLayout() { const [loaded] = useFonts({ SpaceMono: require('../assets/fonts/SpaceMono-Regular.ttf'), }); useEffect(() => { if (loaded) { SplashScreen.hide(); } }, [loaded]); if (!loaded) { return null; } return <Stack />; }
App.js
import { useEffect } from 'react'; import { Text, View } from 'react-native'; import Entypo from '@expo/vector-icons/Entypo'; import * as SplashScreen from 'expo-splash-screen'; import * as Font from 'expo-font'; // 在我们获取资源时保持启动画面可见 SplashScreen.preventAutoHideAsync(); // 设置动画选项。这是可选的。 SplashScreen.setOptions({ duration: 1000, fade: true, }); export default function App() { const [loaded] = useFonts({ SpaceMono: require('../assets/fonts/SpaceMono-Regular.ttf'), }); useEffect(() => { if (loaded) { SplashScreen.hideAsync(); } }, [loaded]); if (!loaded) { return null; } return ( <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}> <Text>SplashScreen 演示!👋</Text> <Entypo name="rocket" size={30} /> </View> ); }

配置

如果你的项目使用 config plugin(Continuous Native Generation (CNG)),你可以使用 expo-splash-screen 内置的 config plugin 来配置它。该插件允许你配置各种无法在运行时设置、且需要构建新的应用二进制文件才会生效的属性。如果你的应用使用 CNG,那么你需要手动配置该库。

如下面所示,使用 config plugin 是配置启动画面的推荐方式。 其他方式现在被视为旧版方案,并将在未来移除。

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

NameDefaultDescription
backgroundColor#ffffff

表示启动画面背景颜色的十六进制颜色字符串。

imageundefined

将在启动画面上显示的图片文件路径。这应该是你的应用图标或 logo。

enableFullScreenImage_legacyfalse
Only for:
iOS

启用此属性后,可将全屏图片用作启动画面。这用于帮助从旧版启动画面配置过渡,未来将被移除。

darkundefined

包含在设备处于深色模式时用于配置启动画面的属性的对象。

imageWidth100

图片的宽度。

androidundefined

包含用于配置 Android 上启动画面的属性的对象。

iosundefined

包含用于配置 iOS 上启动画面的属性的对象。

resizeModeundefined

决定图片如何缩放以适配由 imageWidth 定义的容器。可能的值:containcovernative

你也可以使用以下 app config 属性来配置 expo-splash-screen,但应优先使用 config plugin。

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

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 compatability. 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
ParameterType
optionsSplashScreenOptions

Configures the splashscreens default animation behavior.

Returns:
void

Types

SplashScreenOptions

Android
iOS
tvOS
PropertyTypeDescription
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