This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 启动画面
一个提供控制原生启动画面可见性行为访问能力的库。
expo-splash-screen 库中的 SplashScreen 模块提供了对原生启动屏幕行为的控制。默认情况下,当你的应用准备就绪时,启动屏幕会自动隐藏,但你也可以为更高级的使用场景手动控制其可见性。
从 SDK 52 开始,由于支持最新 Android 启动屏幕 API 的变更,Expo Go 和开发构建无法完全复现用户在你的 独立应用 中看到的启动屏幕体验。Expo Go 会显示你的应用图标而不是启动屏幕,而开发构建上的启动屏幕也不会反映在配置插件中设置的所有属性。强烈建议你在发布构建中测试启动屏幕,以确保其外观符合预期。
另请参阅 创建启动屏幕图片 的指南,或 使用浏览器快速生成图标和启动屏幕。
安装
- npx expo install expo-splash-screenIf you are installing this in an existing React Native app, make sure to install expo in your project.
The with-splash-screen example comes with expo-splash-screen already installed and configured:
- npx create-expo-app --example with-splash-screen用法
对于大多数应用,你无需对启动画面执行任何特殊操作。应用准备就绪后,启动画面会自动隐藏。你也可以选择配置动画选项:
import { Stack } from 'expo-router'; import * as SplashScreen from 'expo-splash-screen'; // 设置动画选项。此项为可选。 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'; // 设置动画选项。此项为可选。 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() 手动控制启动画面的隐藏时机。目标应该是尽早隐藏启动画面。
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 />; }
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> ); }
配置
如果你在项目中使用配置插件(持续原生生成(CNG)),你可以使用 expo-splash-screen 内置的 config plugin 进行配置。该插件允许你配置一些无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。如果你的应用不使用 CNG,那么你需要手动配置该库。
建议使用如下所示的 config plugin 来配置启动屏幕。 其他方法现在都被视为旧版方案,并将在未来移除。
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
| 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 | 决定图像如何缩放以适应由 |
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
Partial<AndroidSplashConfig>Properties for configuring the splash screen on Android.
string • Default: "#ffffff"Hex color for the splash screen background.
{
backgroundColor: string,
image: string
}Properties for configuring the splash screen in dark mode.
boolean • Default: falseWhether to use a full screen image as the splash screen. Legacy transition helper, will be removed.
Methods
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.
voidMakes 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.
Promise<boolean>Example
import * as SplashScreen from 'expo-splash-screen'; SplashScreen.preventAutoHideAsync(); export default function App() { // ... }
| Parameter | Type |
|---|---|
| options | SplashScreenOptions |
Configures the splashscreens default animation behavior.
void