首页指南参考教程

Expo 资源

通用库,允许下载资源并将其与其他库一起使用。

Android
iOS
tvOS
Web

expo-asset 提供了 Expo 资源系统的接口。资源是与应用运行时所需的应用源代码一起存在的任何文件。示例包括图片、字体和声音。Expo 的资源系统与 React Native 集成,这样你就可以引用带有 require('path/to/file') 的文件。例如,这就是你在 React Native 中引用静态图片文件以在 Image 组件中使用的方式。查看 React Native 的 静态图片资源文档 了解更多信息。这种引用静态图片资源的方法在 Expo 中是开箱即用的。

¥expo-asset provides an interface to Expo's asset system. An asset is any file that lives alongside the source code of your app that the app needs at runtime. Examples include images, fonts, and sounds. Expo's asset system integrates with React Native's, so that you can refer to files with require('path/to/file'). This is how you refer to static image files in React Native for use in an Image component, for example. Check out React Native's documentation on static image resources for more information. This method of referring to static image resources works out of the box with Expo.

安装

¥Installation

Terminal
npx expo install expo-asset

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

app.json/app.config.js 中的配置

¥Configuration in app.json/app.config.js

如果你在项目中使用配置插件(EAS 构建npx expo run:[android|ios]),则可以使用其内置的 配置插件 配置 expo-asset。该插件允许你配置无法在运行时设置的各种属性,并且需要构建新的应用二进制文件才能生效。

¥You can configure expo-asset using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

Example app.json with config plugin

app.json
{
  "expo": {
    "plugins": [
      [
        "expo-asset",
        {
          "assets": ["path/to/file.png", "path/to/directory"]
        }
      ]
    ]
  }
}

Configurable properties

NameDefaultDescription
assets[]

An array of asset files or directories to link to the native project. The paths should be relative to the project root so that the file names, whether specified directly or using a directory, will become the resource names.

Supported file types:

  • Images: .png, .jpg, .gif
  • Media: .mp4, .mp3, .lottie
  • SQLite database files: .db

Note: To import an existing database file (.db), see instructions in SQLite API reference. For other file types such as .lottie, see how to add a file extension to assetExts in metro config.

用法

¥Usage

了解有关如何使用 expo-asset 配置插件将资源文件嵌入到 在构建时加载资源 项目中的更多信息。

¥Learn more about how to use the expo-asset config plugin to embed an asset file in your project in Load an asset at build time.

API

import { Asset } from 'expo-asset';

Hooks

useAssets(moduleIds)

NameType
moduleIdsnumber | number[]

Downloads and stores one or more assets locally. After the assets are loaded, this hook returns a list of asset instances. If something went wrong when loading the assets, an error is returned.

Note, the assets are not "reloaded" when you dynamically change the asset list.

Returns:

[Asset[] | undefined, Error | undefined]

Returns an array containing:

  • on the first position, a list of all loaded assets. If they aren't loaded yet, this value is undefined.
  • on the second position, an error which encountered when loading the assets. If there was no error, this value is undefined.

Example

const [assets, error] = useAssets([require('path/to/asset.jpg'), require('path/to/other.png')]);

return assets ? <Image source={assets[0]} /> : null;

Classes

Asset

The Asset class represents an asset in your app. It gives metadata about the asset (such as its name and type) and provides facilities to load the asset data.

Asset Properties

downloaded

Type: boolean • Default: false

Whether the asset has finished downloading from a call to downloadAsync().

hash

Type: null | string • Default: null

The MD5 hash of the asset's data.

height

Type: null | number • Default: null

If the asset is an image, the height of the image data divided by the scale factor. The scale factor is the number after @ in the filename, or 1 if not present.

localUri

Type: null | string • Default: null

If the asset has been downloaded (by calling downloadAsync()), the file:// URI pointing to the local file on the device that contains the asset data.

name

Type: string

The name of the asset file without the extension. Also without the part from @ onward in the filename (used to specify scale factor for images).

type

Type: string

The extension of the asset filename.

uri

Type: string

A URI that points to the asset's data on the remote server. When running the published version of your app, this refers to the location on Expo's asset server where Expo has stored your asset. When running the app from Expo CLI during development, this URI points to Expo CLI's server running on your computer and the asset is served directly from your computer. If you are not using Classic Updates (legacy), this field should be ignored as we ensure your assets are on device before before running your application logic.

width

Type: null | number • Default: null

If the asset is an image, the width of the image data divided by the scale factor. The scale factor is the number after @ in the filename, or 1 if not present.

Asset Methods

downloadAsync()

Downloads the asset data to a local file in the device's cache directory. Once the returned promise is fulfilled without error, the localUri field of this asset points to a local file containing the asset data. The asset is only downloaded if an up-to-date local file for the asset isn't already present due to an earlier download. The downloaded Asset will be returned when the promise is resolved.

Returns:

Promise<Asset>

Returns a Promise which fulfills with an Asset instance.

fromMetadata(meta)

NameType
metaAssetMetadata

Returns:

Asset

fromModule(virtualAssetModule)

NameTypeDescription
virtualAssetModulestring | number

The value of require('path/to/file') for the asset or external network URL


Returns the Asset instance representing an asset given its module or URL.

Returns:

Asset

The Asset instance for the asset.

fromURI(uri)

NameType
uristring

Returns:

Asset

loadAsync(moduleId)

NameTypeDescription
moduleIdstring | number | number[] | string[]

An array of require('path/to/file') or external network URLs. Can also be just one module or URL without an Array.


A helper that wraps Asset.fromModule(module).downloadAsync for convenience.

Returns:

Promise<Asset[]>

Returns a Promise that fulfills with an array of Assets when the asset(s) has been saved to disk.

Example

const [{ localUri }] = await Asset.loadAsync(require('./assets/snack-icon.png'));

Types

AssetDescriptor

NameTypeDescription
hash
(optional)
string | null-
height
(optional)
number | null-
namestring-
typestring-
uristring-
width
(optional)
number | null-

AssetMetadata

Type: Pick<PackagerAsset, 'httpServerLocation' | 'name' | 'hash' | 'type' | 'scales' | 'width' | 'height'> extended by:


NameTypeDescription
fileHashes
(optional)
string[]-
fileUris
(optional)
string[]-
uri
(optional)
string-
Expo 中文网 - 粤ICP备13048890号