Expo
Expo 和相关包的一组常用方法和类型。
安装
¥Installation
-
npx expo install expo
API
import * as Expo from 'expo';
expo/fetch
API
expo/fetch
提供可在 Web 和移动环境中一致工作的 符合 WinterCG 标准的 Fetch API,确保 Expo 应用中标准化和跨平台的获取体验。
¥expo/fetch
provides a WinterCG-compliant Fetch API that works consistently across web and mobile environments, ensuring a standardized and cross-platform fetch experience within Expo applications.
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
API 编码
¥Encoding APIs
TextEncoder
和 TextDecoder
是内置 API,提供以各种字符编码对文本进行编码和解码的方法。它们适用于所有平台。请参阅 Web 和 Node.js 的 浏览器和服务器运行时支持。
¥TextEncoder
and TextDecoder
are built-in APIs that provide a way to encode and decode text in various character encodings. They are available on all platforms. Refer to the browser and server runtime support for web and Node.js.
// [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 中的源代码。
¥The TextEncoder
API is included in the Hermes engine. See the source code in TextEncoder.cpp inside the Hermes GitHub repository.
TextDecoder
API 不是原生平台上的 spec-compliant。仅支持 UTF-8 编码。如果你需要支持更多编码,请使用像 text-encoding
这样的 polyfill。
¥The TextDecoder
API is not spec-compliant on native platforms. Only the UTF-8 encoding is supported. If you need support for more encodings, use a polyfill like text-encoding
.
Streams API
原生平台提供对标准 Web 流的全局支持,以匹配 Web 和服务器平台的行为。有关具体的 Web 和 Node.js 支持,请参阅 浏览器和服务器运行时支持。EAS Hosting 服务器运行时还支持标准 Web 流 API。
¥Global support for standard web streams is available on native platforms to match the behavior of web and server platforms. Refer to the browser and server runtime support for specific web and Node.js support. EAS Hosting server runtime also includes support for the standard web streams API.
全局访问 ReadableStream
、WritableStream
和 TransformStream
类。
¥Globally access ReadableStream
, WritableStream
, and TransformStream
classes.
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。
¥URL
provides the standard API on all platforms.
在原生平台上,内置 URL
和 URLSearchParams
实现取代了 react-native
中的垫片。请参阅 Web 和 Node.js 的 浏览器和服务器运行时支持。
¥On native platforms, built-in URL
and URLSearchParams
implementations replace the shims in react-native
. Refer to the browser and server runtime support for web and Node.js.
const url = new URL('https://expo.dev');
const params = new URLSearchParams();
Expo 内置的 URL
支持试图完全兼容 符合规范。唯一缺少的例外是原生平台当前不支持主机名中的 非 ASCII 字符。
¥Expo's built-in URL
support attempts to be fully spec compliant. The only missing exception is that native platforms do not currently support non-ASCII characters in the hostname.
console.log(new URL('http://🥓').toString());
// This outputs the following:
// - Web, Node.js: http://xn--pr9h/
// - Android, iOS: http://🥓/
Constants
Hooks
Parameter | Type | Description |
---|---|---|
eventEmitter | EventEmitter<TEventsMap> | An object that emits events. For example, a native module or shared object or an instance of |
eventName | TEventName | Name of the event to listen to. |
initialValue(optional) | null | TInitialValue | 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.
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>;
}
Parameter | Type | Description |
---|---|---|
eventEmitter | EventEmitter<TEventsMap> | An object that emits events. For example, a native module or shared object or an instance of |
eventName | TEventName | Name of the event to listen to. |
listener | TEventListener | 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.
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
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
Parameter | Type |
---|---|
eventName | EventName |
listener | TEventsMap[EventName] |
Adds a listener for the given event name.
EventSubscription
Parameter | Type |
---|---|
eventName | EventName |
...args | Parameters<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.
void
Parameter | Type |
---|---|
eventName | EventName |
Returns a number of listeners added to the given event.
number
Parameter | Type |
---|---|
eventName | keyof TEventsMap |
Removes all listeners for the given event name.
void
Parameter | Type |
---|---|
eventName | EventName |
listener | TEventsMap[EventName] |
Removes a listener for the given event name.
void
Parameter | Type |
---|---|
eventName | EventName |
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.
void
Type: Class extends EventEmitter<TEventsMap>
A class for all native modules. Extends the EventEmitter class.
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
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
.
void
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
Methods
Returns a boolean value whether the app is running in Expo Go.
boolean
Parameter | Type | Description |
---|---|---|
component | ComponentType<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 rootindex.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 toreact-native-web
when running in the browser.
void
See: For information on how to setup
registerRootComponent
in an existing (bare) React Native app, see Common questions below.
Parameter | Type | Description |
---|---|---|
moduleImplementation | ModuleType | A class that extends |
moduleName | string | – a name to register the module under |
Registers a web module.
ModuleType
A singleton instance of the class passed into arguments.
Parameter | Type | Description |
---|---|---|
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.
Promise<void>
Parameter | Type | Description |
---|---|---|
moduleName | string | 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.
ModuleType
Object representing the native module.
Parameter | Type |
---|---|
moduleName | string |
viewName(optional) | string |
A drop-in replacement for requireNativeComponent
.
React.ComponentType<P>
Parameter | Type | Description |
---|---|---|
moduleName | string | 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.
ModuleType | null
Object representing the native module or null
when it cannot be found.
Event Subscriptions
Parameter | Type | Description |
---|---|---|
eventEmitter | EventEmitter<TEventsMap> | An object that emits events. For example, a native module or shared object or an instance of |
eventName | TEventName | Name of the event to listen to. |
listener | TEventListener | 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.
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} />;
}
常见问题
¥Common questions
关于在项目中使用 expo
包的一些常见问题。
¥Some common questions about using the expo
package in your project.
rootRegisterComponent
setup for existing React Native projects
If you are managing your React Native project's native directories (android and ios) manually, you need to follow the instructions below to set up the registerRootComponent
function. This is necessary for the Expo modules to work correctly.
Android
Update the android/app/src/main/your-package/MainActivity.java file to use the name main
in the getMainComponentName
function.
!!!IG6!!!
iOS
Update the iOS ios/your-project/AppDelegate.(m|mm|swift) file to use the moduleName main
in the createRootViewWithBridge:bridge moduleName:@"main" initialProperties:initProps
line of the application:didFinishLaunchingWithOptions:
function.
What if I want to name my main app file something other than App.js or app/_layout.tsx?
For projects that do not use Expo Router, you can set the "main"
in package.json to any file within your project. If you do this, then you need to use registerRootComponent
. The export default
will not make this component the root for the app if you are using a custom entry file.
For example, let's say you want to make src/main.jsx the entry file for your app — maybe you don't like having JavaScript files in the project root. First, set this in package.json:
!!!IG7!!!
Then, in src/main.jsx, make sure you call registerRootComponent
and pass in the component you want to render at the root of the app:
!!!IG8!!!
For projects that use Expo Router, you can create a custom entry point by following these steps from Expo Router's installation guide. To use the top-level src directory in your Expo Router project, see src directory reference for more information.