This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).
Expo FileSystem
一个提供对设备本地文件系统访问的库。
For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.
expo-file-system 提供了对存储在设备上或作为资源打包进原生项目中的文件和目录的访问。它还允许从网络下载文件。
安装
- npx expo install expo-file-systemIf you are installing this in an existing React Native app, make sure to install expo in your project.
app 配置中的配置
如果你在项目中使用配置插件(Continuous Native Generation (CNG)),你可以使用 expo-file-system 内置的 config plugin 来进行配置。该插件允许你配置各种无法在运行时设置的属性,并且这些设置需要构建新的应用二进制文件后才会生效。如果你的应用不使用 CNG,那么你需要手动配置该库。
Example app.json with config plugin
{ "expo": { "plugins": [ [ "expo-file-system", { "supportsOpeningDocumentsInPlace": true, "enableFileSharing": true } ] ] } }
Configurable properties
| Name | Default | Description |
|---|---|---|
supportsOpeningDocumentsInPlace | false | Only for: iOS 一个布尔值,用于在 Info.plist 中启用 |
enableFileSharing | false | Only for: iOS 一个布尔值,用于在 Info.plist 中启用 |
Are you using this library in an existing React Native app?
如果你没有使用 Continuous Native Generation(CNG),或者你正在手动使用原生 ios 项目,那么你需要将 LSSupportsOpeningDocumentsInPlace 和 UIFileSharingEnabled 键添加到项目的 ios/[app]/Info.plist 中:
<key>LSSupportsOpeningDocumentsInPlace</key> <true/> <key>UIFileSharingEnabled</key> <true/>
用法
import { File, Directory, Paths } from 'expo-file-system';
File 和 Directory 实例持有对文件、内容或资源 URI 的引用。
文件或目录不需要已经存在 — 只有当使用了错误的类来表示一个已存在的路径时,构造函数才会抛出错误(例如,如果你尝试创建一个 File 实例,并传入一个已存在目录的路径)。
特性
- 同步和异步的文件内容读写访问
- 创建、修改和删除
- 可用属性,例如
type、size、creationDate等 - 可以通过流或使用
FileHandle类来读取和写入文件 - 使用
downloadFileAsync或expo/fetch轻松下载/上传文件
示例
写入和读取文本文件
import { File, Paths } from 'expo-file-system'; try { const file = new File(Paths.cache, 'example.txt'); file.create(); // 如果文件已存在或没有创建权限,这里可能会抛出错误 file.write('Hello, world!'); console.log(file.textSync()); // Hello, world! } catch (error) { console.error(error); }
使用系统选择器选择文件
与 expo-document-picker 一起使用:
import { File } from 'expo-file-system'; import * as DocumentPicker from 'expo-document-picker'; try { const result = await DocumentPicker.getDocumentAsync({ copyToCacheDirectory: true }); if (!result.canceled) { const { uri } = result.assets[0]; const file = new File(uri); console.log(file.textSync()); } } catch (error) { console.error(error); }
在 Android 上使用内置的 pickFileAsync 或 pickDirectoryAsync 方法:
import { File } from 'expo-file-system'; try { const file = new File.pickFileAsync(); console.log(file.textSync()); } catch (error) { console.error(error); }
下载文件
使用 downloadFileAsync:
import { Directory, File, Paths } from 'expo-file-system'; const url = 'https://pdfobject.com/pdf/sample.pdf'; const destination = new Directory(Paths.cache, 'pdfs'); try { destination.create(); const output = await File.downloadFileAsync(url, destination); console.log(output.exists); // true console.log(output.uri); // 下载文件的路径,例如 '${cacheDirectory}/pdfs/sample.pdf' } catch (error) { console.error(error); }
或者使用 expo/fetch:
import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system'; const url = 'https://pdfobject.com/pdf/sample.pdf'; const response = await fetch(url); const src = new File(Paths.cache, 'file.pdf'); src.write(await response.bytes());
使用 expo/fetch 上传文件
你可以直接使用 Expo 包内置的 fetch 将文件作为 blob 上传:
import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system'; const file = new File(Paths.cache, 'file.txt'); file.write('Hello, world!'); const response = await fetch('https://example.com', { method: 'POST', body: file, });
或者使用 FormData 构造函数:
import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system'; const file = new File(Paths.cache, 'file.txt'); file.write('Hello, world!'); const formData = new FormData(); formData.append('data', file); const response = await fetch('https://example.com', { method: 'POST', body: formData, });
移动和复制文件
import { Directory, File, Paths } from 'expo-file-system'; try { const file = new File(Paths.document, 'example.txt'); file.create(); console.log(file.uri); // '${documentDirectory}/example.txt' const copiedFile = new File(Paths.cache, 'example-copy.txt'); file.copy(copiedFile); console.log(copiedFile.uri); // '${cacheDirectory}/example-copy.txt' file.move(Paths.cache); console.log(file.uri); // '${cacheDirectory}/example.txt' file.move(new Directory(Paths.cache, 'newFolder')); console.log(file.uri); // '${cacheDirectory}/newFolder/example.txt' } catch (error) { console.error(error); }
使用旧版 FileSystem API
import * as FileSystem from 'expo-file-system/legacy'; import { File, Paths } from 'expo-file-system'; try { const file = new File(Paths.cache, 'example.txt'); const content = await FileSystem.readAsStringAsync(file.uri); console.log(content); } catch (error) { console.error(error); }
递归列出目录内容
import { Directory, Paths } from 'expo-file-system'; function printDirectory(directory: Directory, indent: number = 0) { console.log(`${' '.repeat(indent)} + ${directory.name}`); const contents = directory.list(); for (const item of contents) { if (item instanceof Directory) { printDirectory(item, indent + 2); } else { console.log(`${' '.repeat(indent + 2)} - ${item.name} (${item.size} bytes)`); } } } try { printDirectory(new Directory(Paths.cache)); } catch (error) { console.error(error); }
API
Classes
Type: Class extends FileSystemDirectory
Represents a directory on the filesystem.
A Directory instance can be created for any path, and does not need to exist on the filesystem during creation.
The constructor accepts an array of strings that are joined to create the directory URI. The first argument can also be a Directory instance (like Paths.cache).
Example
const directory = new Directory(Paths.cache, "subdirName");
Directory Properties
unionA size of the directory in bytes. Null if the directory does not exist, or it cannot be read.
Acceptable values are: number | null
stringRepresents the directory URI. The field is read-only, but it may change as a result of calling some methods such as move.
Directory Methods
| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Copies a directory.
Promise<void>| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Copies a directory synchronously.
void| Parameter | Type |
|---|---|
| options(optional) | DirectoryCreateOptions |
Creates a directory that the current uri points to.
voidDeletes a directory. Also deletes all files and directories inside the directory.
voidRetrieves an object containing properties of a directory.
DirectoryInfoAn object with directory metadata (for example, size, creation date, and so on).
| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Moves a directory. Updates the uri property that now points to the new location.
Promise<void>| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Moves a directory synchronously. Updates the uri property that now points to the new location.
voidType: Class extends FileSystemFile implements Blob
Represents a file on the filesystem.
A File instance can be created for any path, and does not need to exist on the filesystem during creation.
The constructor accepts an array of strings that are joined to create the file URI. The first argument can also be a Directory instance (like Paths.cache) or a File instance (which creates a new reference to the same file).
Example
const file = new File(Paths.cache, "subdirName", "file.txt");
File Properties
unionA creation time of the file expressed in milliseconds since the epoch. Returns a null if the file does not exist, cannot be read or the Android version is earlier than API 26.
Acceptable values are: number | null
booleanA boolean representing if a file exists. true if the file exists, false otherwise.
Also, false if the application does not have read access to the file.
unionA last modification time of the file expressed in milliseconds since the epoch. Returns a null if the file does not exist, or if it cannot be read.
Acceptable values are: number | null
unionA md5 hash of the file. Null if the file does not exist, or it cannot be read.
Acceptable values are: string | null
Deprecated: In favor of
lastModifiedto be more in line with webFile
unionA last modification time of the file expressed in milliseconds since the epoch. Returns a null if the file does not exist, or if it cannot be read.
Acceptable values are: number | null
numberA size of the file in bytes. 0 if the file does not exist, or it cannot be read.
stringA mime type of the file. An empty string if the file does not exist, or it cannot be read.
File Methods
The arrayBuffer() method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer.
Promise<ArrayBuffer>Retrieves content of the file as base64.
Promise<string>A promise that resolves with the contents of the file as a base64 string.
Retrieves content of the file as base64.
stringThe contents of the file as a base64 string.
Retrieves byte content of the entire file.
Promise<Uint8Array<ArrayBuffer>>A promise that resolves with the contents of the file as a Uint8Array.
Retrieves byte content of the entire file.
Uint8ArrayThe contents of the file as a Uint8Array.
| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Copies a file.
Promise<void>| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Copies a file synchronously.
void| Parameter | Type |
|---|---|
| options(optional) | InfoOptions |
Retrieves an object containing properties of a file
FileInfoAn object with file metadata (for example, size, creation date, and so on).
| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Moves a directory. Updates the uri property that now points to the new location.
Promise<void>| Parameter | Type |
|---|---|
| destination | Directory | File |
| options(optional) | RelocationOptions |
Moves a file synchronously. Updates the uri property that now points to the new location.
void| Parameter | Type | Description |
|---|---|---|
| mode(optional) | FileMode | The
|
Returns A FileHandle object that can be used to read and write data to the file.
FileHandle| Parameter | Type | Description |
|---|---|---|
| options(optional) | PickSingleFileOptions | options |
An overload of the pickFileAsync method, which picks and returns a single File.
This overload requires options to have multipleFiles flag be undefined or false.
Promise<PickSingleFileResult>| Parameter | Type | Description |
|---|---|---|
| options(optional) | PickMultipleFilesOptions | options |
An overload of the pickFileAsync method, which picks and returns a list of File's.
This overload requires options to have multipleFiles flag be true.
Promise<PickMultipleFilesResult>Deprecated: Use
pickFileAsync({initialUri, mimeTypes: mimeType})instead.
| Parameter | Type | Description |
|---|---|---|
| initialUri(optional) | string | An optional URI pointing to an initial folder on which the file picker is opened. |
| mimeType(optional) | string | A mime type that is used to filter out files that can be picked out. |
ReadableStream<Uint8Array<ArrayBuffer>>| Parameter | Type |
|---|---|
| start(optional) | number |
| end(optional) | number |
| contentType(optional) | string |
The slice() method of the Blob interface creates and returns a new Blob object which contains data from a subset of the blob on which it's called.
BlobThe stream() method of the Blob interface returns a ReadableStream which upon reading returns the data contained within the Blob.
ReadableStream<Uint8Array<ArrayBuffer>>Retrieves text from the file.
Promise<string>A promise that resolves with the contents of the file as string.
Retrieves text from the file.
stringThe contents of the file as string.
WritableStream<Uint8Array<ArrayBufferLike>>| Parameter | Type | Description |
|---|---|---|
| content | string | Uint8Array<ArrayBufferLike> | The content to write into the file. |
| options(optional) | FileWriteOptions | - |
Writes content to the file.
voidType: Class extends PathUtilities
Paths Properties
Record<string, Directory>numberA property that represents the available space on device's internal storage, represented in bytes.
DirectoryA property containing the bundle directory – the directory where assets bundled with the application are stored.
DirectoryA property containing the cache directory – a place to store files that can be deleted by the system when the device runs low on storage.
DirectoryA property containing the document directory – a place to store files that are safe from being deleted by the system.
Paths Methods
| Parameter | Type | Description |
|---|---|---|
| path | string | File | Directory | The path to get the base name from. |
| ext(optional) | string | An optional file extension. |
Returns the base name of a path.
stringA string representing the base name.
Returns the directory name of a path.
stringA string representing the directory name.
Returns the extension of a path.
stringA string representing the extension.
| Parameter | Type |
|---|---|
| ...uris | string[] |
Returns an object that indicates if the specified path represents a directory.
PathInfoChecks if a path is absolute.
booleantrue if the path is absolute, false otherwise.
Joins path segments into a single path.
stringA string representing the joined path.
Normalizes a path.
stringA string representing the normalized path.
Parses a path into its components.
{
base: string,
dir: string,
ext: string,
name: string,
root: string
}An object containing the parsed path components.
FileHandle Properties
unionA property that indicates the current byte offset in the file. Calling readBytes or writeBytes will read or write a specified amount of bytes starting from this offset. The offset is incremented by the number of bytes read or written.
The offset can be set to any value within the file size. If the offset is set to a value greater than the file size, the next write operation will append data to the end of the file.
Null if the file handle is closed.
Acceptable values are: number | null
FileHandle Methods
Closes the file handle. This allows the file to be deleted, moved or read by a different process. Subsequent calls to readBytes or writeBytes will throw an error.
void| Parameter | Type | Description |
|---|---|---|
| length | number | The number of bytes to read. |
Reads the specified amount of bytes from the file at the current offset. Max amount of bytes read at once is capped by ArrayBuffer max size (32 bit signed MAX_INT on Android and 64 bit on iOS), but you can read from a FileHandle multiple times.
Uint8Array<ArrayBuffer>| Parameter | Type | Description |
|---|---|---|
| bytes | Uint8Array | A |
Writes the specified bytes to the file at the current offset.
voidMethods
Deprecated: Use
new File().copy()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| options | RelocatingOptions |
Promise<void>Deprecated: Import this method from
expo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| uri | string |
| fileUri | string |
| options(optional) | DownloadOptions |
| callback(optional) | FileSystemNetworkTaskProgressCallback<DownloadProgressData> |
| resumeData(optional) | string |
anyDeprecated: Import this method from
expo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| url | string |
| fileUri | string |
| options(optional) | FileSystemUploadOptions |
| callback(optional) | FileSystemNetworkTaskProgressCallback<UploadProgressData> |
anyDeprecated: Use
new File().delete()ornew Directory().delete()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
| options(optional) | DeletingOptions |
Promise<void>Deprecated: Use
File.downloadFileAsyncor import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| uri | string |
| fileUri | string |
| options(optional) | DownloadOptions |
Promise<FileSystemDownloadResult>Deprecated: Import this method from
expo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
Promise<string>Deprecated: Use
Paths.availableDiskSpaceor import this method fromexpo-file-system/legacy. This method will throw in runtime.
Promise<number>Deprecated: Use
new File().infoor import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
| options(optional) | InfoOptions |
Deprecated: Use
Paths.totalDiskSpaceor import this method fromexpo-file-system/legacy. This method will throw in runtime.
Promise<number>Deprecated: Use
new Directory().create()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
| options(optional) | MakeDirectoryOptions |
Promise<void>Deprecated: Use
new File().move()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| options | RelocatingOptions |
Promise<void>Deprecated: Use
new File().text()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
| options(optional) | ReadingOptions |
Promise<string>Deprecated: Use
new Directory().list()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
Promise<string[]>Deprecated: Use
@expo/fetchor import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| url | string |
| fileUri | string |
| options(optional) | FileSystemUploadOptions |
Promise<FileSystemUploadResult>Deprecated: Use
new File().write()or import this method fromexpo-file-system/legacy. This method will throw in runtime.
| Parameter | Type |
|---|---|
| fileUri | string |
| contents | string |
| options(optional) | WritingOptions |
Promise<void>Types
| Property | Type | Description |
|---|---|---|
| idempotent(optional) | boolean | This flag controls whether the If Default: false |
| intermediates(optional) | boolean | Whether to create intermediate directories if they do not exist. Default: false |
| overwrite(optional) | boolean | Whether to overwrite the directory if it exists. Default: false |
| Property | Type | Description |
|---|---|---|
| creationTime(optional) | number | A creation time of the directory expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26. |
| exists | boolean | Indicates whether the directory exists. |
| files(optional) | string[] | A list of file names contained within a directory. |
| modificationTime(optional) | number | The last modification time of the directory expressed in milliseconds since epoch. |
| size(optional) | number | The size of the file in bytes. |
| uri(optional) | string | A |
| Property | Type | Description |
|---|---|---|
| headers(optional) | undefined | The headers to send with the request. |
| idempotent(optional) | boolean | This flag controls whether the If Default: false |
| onProgress(optional) | (data: DownloadProgress) => void | A callback that is invoked with progress updates during the download. |
| signal(optional) | AbortSignal | An |
Data provided to the onProgress callback during a file download.
| Property | Type | Description |
|---|---|---|
| bytesWritten | number | The number of bytes written so far. |
| totalBytes | number | The total number of bytes expected to be downloaded. |
| Property | Type | Description |
|---|---|---|
| intermediates(optional) | boolean | Whether to create intermediate directories if they do not exist. Default: false |
| overwrite(optional) | boolean | Whether to overwrite the file if it exists. Default: false |
| Property | Type | Description |
|---|---|---|
| creationTime(optional) | number | A creation time of the file expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26. |
| exists | boolean | Indicates whether the file exists. |
| md5(optional) | string | Present if the |
| modificationTime(optional) | number | The last modification time of the file expressed in milliseconds since epoch. |
| size(optional) | number | The size of the file in bytes. |
| uri(optional) | string | A URI pointing to the file. This is the same as the |
| Property | Type | Description |
|---|---|---|
| md5(optional) | boolean | Whether to return the MD5 hash of the file. Default: false |
| Property | Type | Description |
|---|---|---|
| exists | boolean | Indicates whether the path exists. Returns true if it exists; false if the path does not exist or if there is no read permission. |
| isDirectory | boolean | null | Indicates whether the path is a directory. Returns true or false if the path exists; otherwise, returns null. |
Result type for a canceled file pick.
| Property | Type | Description |
|---|---|---|
| canceled | true | - |
| result | null | - |
| Property | Type | Description |
|---|---|---|
| initialUri(optional) | string | A URI pointing to an initial folder in which the file picker is opened. |
| mimeTypes(optional) | string | string[] | The MIME type(s) of the documents that are available
to be picked. It also supports wildcards like Default: '*/*' |
| multipleFiles(optional) | boolean | Allows multiple files to be selected from the system UI. Default: false |
Options for picking multiple files.
Type: PickFileGeneralOptions extended by:
| Property | Type | Description |
|---|---|---|
| multipleFiles | true | - |
Literal Type: union
Result type for picking multiple files.
Acceptable values are: PickMultipleFilesSuccessResult | PickFileCanceledResult
Result type for a successful picking multiple files.
| Property | Type | Description |
|---|---|---|
| canceled | false | - |
| result | File[] | - |
Options for picking a single file.
Type: PickFileGeneralOptions extended by:
| Property | Type | Description |
|---|---|---|
| multipleFiles(optional) | false | - |
Literal Type: union
Result type for picking a single file.
Acceptable values are: PickSingleFileSuccessResult | PickFileCanceledResult
Result type for successfully picking a single file.
| Property | Type | Description |
|---|---|---|
| canceled | false | - |
| result | File | - |
Enums
Specifies the access mode when opening a file handle.
FileMode.ReadOnly = "r"Opens the file for reading only. The cursor is positioned at the beginning of the file.
FileMode.ReadWrite = "rw"Opens the file for both reading and writing. The cursor is positioned at the beginning of the file.
Note: This mode cannot be used with SAF (Storage Access Framework)
content://URIs.
FileMode.WriteOnly = "w"Opens the file for writing only. The cursor is positioned at the beginning of the file.
FileMode.Append = "wa"Opens the file for writing only. The cursor is positioned at the end of the file.
Note: For SAF files, this is a strict append-only mode. The cursor cannot be moved; calling
seek()will have no effect.