Reference version

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

Expo Expo iconExpo

Expo 及相关包的一组常用方法和类型。

Android
iOS
tvOS
Web
Included in Expo Go

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

安装

Terminal
npx expo install expo

API

import * as Expo from 'expo';

expo/fetch API

expo/fetch 提供了一个 符合 WinterCG 的 Fetch API,可在 Web 和移动端环境中一致运行,确保在 Expo 应用中拥有标准化、跨平台的 fetch 体验。

Streaming fetch
import { fetch } from 'expo/fetch'; const resp = await fetch('https://httpbin.org/drip?numbytes=512&duration=2', { headers: { Accept: 'text/event-stream' }, }); const reader = resp.body.getReader(); const chunks = []; while (true) { const { done, value } = await reader.read(); if (done) { break; } chunks.push(value); } const buffer = new Uint8Array(chunks.reduce((acc, chunk) => acc + chunk.length, 0)); console.log(buffer.length); // 512

注意: 在 Android 和 iOS 上,expo/fetch 也会作为全局 fetch 安装。这意味着任何未从 expo/fetch 导入而直接调用的 fetch(...) 都会使用同样符合 WinterCG 的实现。若要保留 React Native 内置的 fetch 作为全局方法,请在你的 环境变量 中设置 EXPO_PUBLIC_USE_RN_FETCH=1。无论此标志如何,从 expo/fetch 的命名导入始终可用。

编码 API

TextEncoderTextDecoder 是内置 API,提供了在各种字符编码中对文本进行编码和解码的方法。它们在所有平台上都可用。Web 和 Node.js 请参考 浏览器和服务器运行时支持

TextEncoder and TextDecoder
// [104, 101, 108, 108, 111] const hello = new TextEncoder().encode('hello'); // "hello" const text = new TextDecoder().decode(hello);

TextEncoder API 已包含在 Hermes 引擎中。请参阅 Hermes GitHub 仓库中 TextEncoder.cpp 的源代码

TextDecoder API 在原生平台上并不 符合规范。目前仅支持 UTF-8 编码。如果你需要支持更多编码,请使用类似 text-encoding 的 polyfill。

这些 API 的流式对应版本 TextEncoderStreamTextDecoderStream 也可在所有平台上使用。它们允许你以流式方式对文本进行编码和解码,这对于处理大量数据而无需一次性将其全部加载到内存中非常有用。

TextEncoderStream
const encoder = new TextEncoderStream(); const stream = new ReadableStream({ start(controller) { controller.enqueue('Hello'); controller.enqueue('World'); controller.close(); }, }); const reader = stream.pipeThrough(encoder).getReader(); reader.read().then(({ done, value }) => { console.log(value); // Uint8Array [72, 101, 108, 108, 111] });

Streams API

原生平台提供了标准 Web 流的全局支持,以匹配 Web 和服务器平台的行为。Web 和 Node.js 的具体支持情况请参考 浏览器和服务器运行时支持。EAS Hosting 服务器运行时也包含对标准 Web streams API 的支持。

可全局访问 ReadableStreamWritableStreamTransformStream 类。

ReadableStream
const stream = new ReadableStream({ start(controller) { controller.enqueue('Hello'); controller.enqueue('World'); controller.close(); }, }); const reader = stream.getReader(); reader.read().then(({ done, value }) => { console.log(value); // Hello }); reader.read().then(({ done, value }) => { console.log(value); // World });

URL API

URL 在所有平台上都提供标准 API。

在原生平台上,内置的 URLURLSearchParams 实现会替代 react-native 中的 shim。Web 和 Node.js 的具体支持情况请参考 浏览器和服务器运行时支持

URL and URLSearchParams
const url = new URL('https://expo.dev'); const params = new URLSearchParams();

Expo 内置的 URL 支持力求完全 符合规范。唯一缺少的例外是,原生平台当前不支持主机名中的 非 ASCII 字符

Non-ASCII characters
console.log(new URL('http://🥓').toString()); // 这将输出以下内容: // - Web, Node.js: http://xn--pr9h/ // - Android, iOS: http://🥓/

structuredClone

structuredClone 是一个内置函数,允许你创建值的深拷贝,包括 MapSetArrayBuffer 之类的复杂对象。它在所有平台上都可用。

const original = { name: 'Expo', date: new Date() }; const clone = structuredClone(original); console.log(clone); // { name: 'Expo', date: Date }

ArrayBufferTypedArraytransfer 选项尚未实现。

请移除任何用于 structuredClone 的自定义 polyfill,以避免体积膨胀。有关 structured clone 算法 的更多信息,请参阅标准文档。

Constants

SharedRef

Android
iOS
tvOS
Web

Type: SharedRef

Hooks

useEvent(eventEmitter, eventName, initialValue)

Android
iOS
tvOS
Web
ParameterTypeDescription
eventEmitterEventEmitter<TEventsMap>

An object that emits events. For example, a native module or shared object or an instance of EventEmitter.

eventNameTEventName

Name of the event to listen to.

initialValue(optional)TInitialValue | null

An event parameter to use until the event is called for the first time.

Default:null

React hook that listens to events emitted by the given object. The returned value is an event parameter that gets updated whenever a new event is dispatched.

Returns:
InferEventParameter<TEventListener, TInitialValue>

A parameter of the event listener.

Example

import { useEvent } from 'expo'; import { VideoPlayer } from 'expo-video'; export function PlayerStatus({ videoPlayer }: { videoPlayer: VideoPlayer }) { const { status } = useEvent(videoPlayer, 'statusChange', { status: videoPlayer.status }); return <Text>{`Player status: ${status}`}</Text>; }

useEventListener(eventEmitter, eventName, listener)

Android
iOS
tvOS
Web
ParameterTypeDescription
eventEmitterEventEmitter<TEventsMap>

An object that emits events. For example, a native module or shared object or an instance of EventEmitter.

eventNameTEventName

Name of the event to listen to.

listenerTEventListener

A function to call when the event is dispatched.


React hook that listens to events emitted by the given object and calls the listener function whenever a new event is dispatched. The event listener is automatically added during the first render and removed when the component unmounts.

Returns:
void

Example

import { useEventListener } from 'expo'; import { useVideoPlayer, VideoView } from 'expo-video'; export function VideoPlayerView() { const player = useVideoPlayer(videoSource); useEventListener(player, 'playingChange', ({ isPlaying }) => { console.log('Player is playing:', isPlaying); }); return <VideoView player={player} />; }

Classes

EventEmitterType

Android
iOS
tvOS
Web

A class that provides a consistent API for emitting and listening to events. It shares many concepts with other emitter APIs, such as Node's EventEmitter and fbemitter. When the event is emitted, all of the functions attached to that specific event are called synchronously. Any values returned by the called listeners are ignored and discarded. Its implementation is written in C++ and common for all the platforms.

EventEmitterType Methods

addListener(eventName, listener)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName
listenerTEventsMap[EventName]

Adds a listener for the given event name.

Returns:
EventSubscription

emit(eventName, ...args)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName
...argsParameters<TEventsMap[EventName]>

Synchronously calls all the listeners attached to that specific event. The event can include any number of arguments that will be passed to the listeners.

Returns:
void

listenerCount(eventName)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName

Returns a number of listeners added to the given event.

Returns:
number

removeAllListeners(eventName)

Android
iOS
tvOS
Web
ParameterType
eventNamekeyof TEventsMap

Removes all listeners for the given event name.

Returns:
void

removeListener(eventName, listener)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName
listenerTEventsMap[EventName]

Removes a listener for the given event name.

Returns:
void

startObserving(eventName)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName

Function that is automatically invoked when the first listener for an event with the given name is added. Override it in a subclass to perform some additional setup once the event started being observed.

Returns:
void

stopObserving(eventName)

Android
iOS
tvOS
Web
ParameterType
eventNameEventName

Function that is automatically invoked when the last listener for an event with the given name is removed. Override it in a subclass to perform some additional cleanup once the event is no longer observed.

Returns:
void

NativeModuleType

Android
iOS
tvOS
Web

Type: Class extends EventEmitter<TEventsMap>

A class for all native modules. Extends the EventEmitter class.

SharedObjectType

Android
iOS
tvOS
Web

Type: Class extends EventEmitter<TEventsMap> implements EventEmitter<TEventsMap>

Base class for all shared objects that extends the EventEmitter class. The implementation is written in C++, installed through JSI and common for mobile platforms.

SharedObjectType Methods

release()

Android
iOS
tvOS
Web

A function that detaches the JS and native objects to let the native object deallocate before the JS object gets deallocated by the JS garbage collector. Any subsequent calls to native functions of the object will throw an error as it is no longer associated with its native counterpart.

In most cases, you should never need to use this function, except some specific performance-critical cases when manual memory management makes sense and the native object is known to exclusively retain some native memory (such as binary data or image bitmap). Before calling this function, you should ensure that nothing else will use this object later on. Shared objects created by React hooks are usually automatically released in the effect's cleanup phase, for example: useVideoPlayer() from expo-video and useImage() from expo-image.

Returns:
void

SharedRefType

Android
iOS
tvOS
Web

Type: Class extends SharedObject<TEventsMap> implements SharedObject<TEventsMap>

A SharedObject that holds a reference to any native object. Allows passing references to native instances among different independent libraries.

For instance, ImageRef from expo-image references a Drawable on Android and an UIImage on iOS. Since both types are common on these platforms, different native modules can use them without depending on each other. In particular, this enables the expo-image-manipulator to pass the resulted image directly to the image view from expo-image without any additional writes and reads from the file system.

SharedRefType Properties

nativeRefType

Android
iOS
tvOS
Web
Type: string

The type of the native reference.

Methods

installOnUIRuntime()

Android
iOS
tvOS
Web
Returns:
void

isRunningInExpoGo()

Android
iOS
tvOS
Web

Returns a boolean value whether the app is running in Expo Go.

Returns:
boolean

registerRootComponent(component)

Android
iOS
tvOS
Web
ParameterTypeDescription
componentComponentType<P>

The React component class that renders the rest of your app.


Sets the initial React component to render natively in the app's root React Native view on Android, iOS, tvOS and the web.

This method does the following:

  • Invokes React Native's AppRegistry.registerComponent.
  • Invokes React Native web's AppRegistry.runApplication on web to render to the root index.html file.
  • Polyfills the process.nextTick function globally.

This method also adds the following dev-only features that are removed in production bundles.

  • Adds the Fast Refresh and bundle splitting indicator to the app.
  • Asserts if the expo-updates package is misconfigured.
  • Asserts if react-native is not aliased to react-native-web when running in the browser.
Returns:
void

See: For information on how to setup registerRootComponent in an existing (bare) React Native app, see Common questions below.

registerWebModule(moduleImplementation, moduleName)

Android
iOS
tvOS
Web
ParameterTypeDescription
moduleImplementationModuleType

A class that extends NativeModule. The class is registered under globalThis.expo.modules[className].

moduleNamestring

A name to register the module under globalThis.expo.modules[className].


Registers a web module.

Returns:
ModuleType

A singleton instance of the class passed into arguments.

reloadAppAsync(reason)

Android
iOS
tvOS
Web
ParameterTypeDescription
reason(optional)string

The reason for reloading the app. This is used only for some platforms.


Reloads the app. This method works for both release and debug builds.

Unlike Updates.reloadAsync(), this function does not use a new update even if one is available. It only reloads the app using the same JavaScript bundle that is currently running.

Returns:
Promise<void>

requireNativeModule(moduleName)

Android
iOS
tvOS
Web
ParameterTypeDescription
moduleNamestring

Name of the requested native module.


Imports the native module registered with given name. In the first place it tries to load the module installed through the JSI host object and then falls back to the bridge proxy module. Notice that the modules loaded from the proxy may not support some features like synchronous functions.

Returns:
ModuleType

Object representing the native module.

requireNativeView(moduleName, viewName)

Android
iOS
tvOS
Web
ParameterType
moduleNamestring
viewName(optional)string

A drop-in replacement for requireNativeComponent.

Returns:
ComponentType<P>

requireOptionalNativeModule(moduleName)

Android
iOS
tvOS
Web
ParameterTypeDescription
moduleNamestring

Name of the requested native module.


Imports the native module registered with the given name. The same as requireNativeModule, but returns null when the module cannot be found instead of throwing an error.

Returns:
ModuleType | null

Object representing the native module or null when it cannot be found.

Event Subscriptions

useEventListener(eventEmitter, eventName, listener)

Android
iOS
tvOS
Web
ParameterTypeDescription
eventEmitterEventEmitter<TEventsMap>

An object that emits events. For example, a native module or shared object or an instance of EventEmitter.

eventNameTEventName

Name of the event to listen to.

listenerTEventListener

A function to call when the event is dispatched.


React hook that listens to events emitted by the given object and calls the listener function whenever a new event is dispatched. The event listener is automatically added during the first render and removed when the component unmounts.

Returns:
void

Example

import { useEventListener } from 'expo'; import { useVideoPlayer, VideoView } from 'expo-video'; export function VideoPlayerView() { const player = useVideoPlayer(videoSource); useEventListener(player, 'playingChange', ({ isPlaying }) => { console.log('Player is playing:', isPlaying); }); return <VideoView player={player} />; }

Types

常见问题

关于在你的项目中使用 expo 包的一些常见问题。

rootRegisterComponent 为现有 React Native 项目进行设置

如果你正在手动管理 React Native 项目的原生目录(androidios),则需要按照下面的说明设置 registerRootComponent 函数。这对于 Expo 模块正确工作是必要的。

Android

更新 android/app/src/main/your-package/MainActivity.java 文件,在 getMainComponentName 函数中使用名为 main 的名称。

android/app/src/main/your-package/MainActivity.java
@Override protected String getMainComponentName() { + return "main"; }

iOS

更新 iOS ios/your-project/AppDelegate.(m|mm|swift) 文件,在 application:didFinishLaunchingWithOptions: 函数中的 createRootViewWithBridge:bridge moduleName:@"main" initialProperties:initProps 这一行使用 moduleName main

如果我想将主应用文件命名为 App.js 或 app/_layout.tsx 之外的其他名称,该怎么办?

对于不使用 Expo Router 的项目,你可以将 package.json 中的 "main" 设置为项目内的任意文件。如果这样做,你就需要使用 registerRootComponent。如果你使用自定义入口文件,export default 不会让这个组件成为应用的根组件。

例如,假设你想把 src/main.jsx 作为应用的入口文件——也许你不喜欢在项目根目录中放置 JavaScript 文件。首先,在 package.json 中这样设置:

package.json
{ "main": "src/main.jsx" }

然后,在 src/main.jsx 中,确保调用 registerRootComponent 并传入你希望在应用根部渲染的组件:

src/main.jsx
import { registerRootComponent } from 'expo'; import { View } from 'react-native'; function App() { return <View />; } registerRootComponent(App);

对于使用 Expo Router 的项目,你可以按照 Expo Router 安装指南 中的这些步骤创建自定义入口点。要在你的 Expo Router 项目中使用顶层 src 目录,请参阅 src 目录参考 获取更多信息。