Expo 文件系统(下一步) iconExpo 文件系统(下一步)

提供对设备上本地文件系统的访问的库。

Android
iOS
tvOS

next 版本的 FileSystem API 包含在 expo-file-system 库中。它可以与以前的 API 一起使用,并提供一种简化的面向对象的方式来执行文件系统操作。

expo-file-system/next 提供对设备本地存储的文件系统的访问。它还可以从网络下载文件。

¥expo-file-system/next provides access to the file system stored locally on the device. It can also download files from the network.

为了提供更快的更新,Expo Go 和 Snack 目前不支持 expo-file-system/next。要使用它,请创建一个 开发构建

安装

¥Installation

Terminal
npx expo install expo-file-system

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

用法

¥Usage

编写和读取文本文件

¥Writing and reading text files

example.ts
import { File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.cache, 'example.txt');
  file.create(); // can throw an error if the file already exists or no permission to create it
  file.write('Hello, world!');
  console.log(file.text()); // Hello, world!
} catch (error) {
  console.error(error);
}

下载文件

¥Downloading files

example.ts
import { File, Paths } from 'expo-file-system/next';

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); // path to the downloaded file, e.g. '${cacheDirectory}/pdfs/sample.pdf'
} catch (error) {
  console.error(error);
}

移动和复制文件

¥Moving and copying files

example.ts
import { File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.document, 'example.txt');
  file.create();
  console.log(file.uri); // '${documentDirectory}/example.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);
}

使用包含原生代码的库

¥Using legacy FileSystem API

example.ts
import * as FileSystem from 'expo-file-system';
import { File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.cache, 'example.txt');
  const content = await FileSystem.readAsStringAsync(file.uri);
  console.log(content);
} catch (error) {
  console.error(error);
}

递归列出目录内容

¥Listing directory contents recursively

example.ts
import { Directory, Paths } from 'expo-file-system/next';

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

Directory

Android
iOS
tvOS

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.

Directory Properties

exists

Android
iOS
tvOS
Type: boolean

A boolean representing if a directory exists. true if the directory exists, false otherwise. Also false if the application does not have read access to the file.

uri

Android
iOS
tvOS
Read Only • Type: string

Represents the directory URI. The field is read-only, but it may change as a result of calling some methods such as move.

name

Android
iOS
tvOS
Type: string

Directory name.

parentDirectory

Android
iOS
tvOS
Type: Directory

Directory containing the file.

Directory Methods

copy(destination)

Android
iOS
tvOS
ParameterType
destinationDirectory | File

Copies a directory.

Returns:
any

create()

Android
iOS
tvOS

Creates a directory that the current uri points to.

Returns:
void

delete()

Android
iOS
tvOS

Deletes a directory. Also deletes all files and directories inside the directory.

Returns:
void

list()

Android
iOS
tvOS

Lists the contents of a directory. Calling this method if the parent directory does not exist will throw an error.

Returns:
(File | Directory)[]

An array of Directory and File instances.

move(destination)

Android
iOS
tvOS
ParameterType
destinationDirectory | File

Moves a directory. Updates the uri property that now points to the new location.

Returns:
any

File

Android
iOS
tvOS

Type: Class extends FileSystemFile

File Properties

exists

Android
iOS
tvOS
Type: boolean

A 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.

md5

Android
iOS
tvOS
Type: null | string

An md5 hash of the file. Null if the file does not exist or it cannot be read.

size

Android
iOS
tvOS
Type: null | number

A size of the file in bytes. Null if the file does not exist or it cannot be read.

uri

Android
iOS
tvOS
Read Only • Type: string

Represents the file URI. The field is read-only, but it may change as a result of calling some methods such as move.

extension

Android
iOS
tvOS
Type: string

File extension.

Example

'.png'

name

Android
iOS
tvOS
Type: string

File name. Includes the extension.

parentDirectory

Android
iOS
tvOS
Type: Directory

Directory containing the file.

File Methods

base64()

Android
iOS
tvOS

Retrieves content of the file as base64.

Returns:
string

The contents of the file as a base64 string.

bytes()

Android
iOS
tvOS

Retrieves byte content of the entire file.

Returns:
Uint8Array

The contents of the file as a Uint8Array.

copy(destination)

Android
iOS
tvOS
ParameterType
destinationDirectory | File

Copies a file.

Returns:
any

create()

Android
iOS
tvOS

Creates a file.

Returns:
void

delete()

Android
iOS
tvOS

Deletes a file.

Returns:
void

downloadFileAsync(url, destination)

Android
iOS
tvOS
ParameterTypeDescription
urlstring

The URL of the file to download.

destinationDirectory | File

The destination directory or file. If a directory is provided, the resulting filename will be determined based on the response headers.


A static method that downloads a file from the network.

Returns:
Promise<File>

A promise that resolves to the downloaded file.

Example

const file = await File.downloadFileAsync("https://example.com/image.png", new Directory(Paths.document));

move(destination)

Android
iOS
tvOS
ParameterType
destinationDirectory | File

Moves a directory. Updates the uri property that now points to the new location.

Returns:
any

open()

Android
iOS
tvOS

Returns a FileHandle object that can be used to read and write data to the file.

Returns:
FileHandle

readableStream()

Android
iOS
tvOS

text()

Android
iOS
tvOS

Retrieves text from the file.

Returns:
string

The contents of the file as string.

writableStream()

Android
iOS
tvOS

write(content)

Android
iOS
tvOS
ParameterTypeDescription
contentstring | Uint8Array

The content to write into the file.


Writes content to the file.

Returns:
void

Paths

Android
iOS
tvOS

Type: Class extends PathUtilities

Paths Properties

appleSharedContainers

Android
iOS
tvOS
Type: Record<string, Directory>

cache

Android
iOS
tvOS
Type: Directory

A property containing the cache directory – a place to store files that can be deleted by the system when the device runs low on storage.

document

Android
iOS
tvOS
Type: Directory

A property containing the document directory – a place to store files that are safe from being deleted by the system.

Paths Methods

basename(path, ext)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to get the base name from.

ext(optional)string

An optional file extension.


Returns the base name of a path.

Returns:
string

A string representing the base name.

dirname(path)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to get the directory name from.


Returns the directory name of a path.

Returns:
string

A string representing the directory name.

extname(path)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to get the extension from.


Returns the extension of a path.

Returns:
string

A string representing the extension.

isAbsolute(path)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to check.


Checks if a path is absolute.

Returns:
boolean

true if the path is absolute, false otherwise.

join(...paths)

Android
iOS
tvOS
ParameterTypeDescription
...paths(string | File | Directory)[]

An array of path segments.


Joins path segments into a single path.

Returns:
string

A string representing the joined path.

normalize(path)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to normalize.


Normalizes a path.

Returns:
string

A string representing the normalized path.

parse(path)

Android
iOS
tvOS
ParameterTypeDescription
pathstring | File | Directory

The path to parse.


Parses a path into its components.

Returns:
{ base: string, dir: string, ext: string, name: string, root: string }

An object containing the parsed path components.

relative(from, to)

Android
iOS
tvOS
ParameterTypeDescription
fromstring | File | Directory

The base path.

tostring | File | Directory

The relative path.


Resolves a relative path to an absolute path.

Returns:
string

A string representing the resolved path.