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

Expo DocumentPicker

一个库，提供访问系统 UI 的能力，用于从用户设备上可用的提供方中选择文档。

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

expo-document-picker 提供了对系统 UI 的访问，用于从用户设备上可用的提供程序中选择文档。

安装

Terminal

- npx expo install expo-document-picker

If you are installing this in an existing React Native app, make sure to install expo in your project.

在 app 配置中进行配置

如果你在项目中使用配置插件（Continuous Native Generation (CNG)），你可以使用 expo-document-picker 内置的 config plugin 进行配置。该插件允许你配置一些无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。如果你的应用没有使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

如果你想启用 iCloud 存储功能，请在 app config 文件中将 expo.ios.usesIcloudStorage 键设置为 true，如 configuration properties 所述。

在本地运行 EAS Build 时，将使用 iOS capabilities signing 在构建前启用所需的能力。

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-document-picker",
        {
          "iCloudContainerEnvironment": "Production"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`iCloudContainerEnvironment`	`undefined`	Only for: iOS 设置 iOS 的 `com.apple.developer.icloud-container-environment` 权限项，用于 AdHoc iOS 构建。可选值：`Development`、`Production`。了解更多。
`kvStoreIdentifier`	`undefined`	Only for: iOS 覆盖默认的 iOS `com.apple.developer.ubiquity-kvstore-identifier` 权限项，该权限项会使用你的 Apple Team ID 和 bundle identifier。如果你的应用在启用 iCloud 存储后被转移到另一个 Apple Team，这可能是必需的。

Are you using this library in an existing React Native app?

不使用 EAS Build 且希望使用 iCloud 存储功能的应用，必须为其 bundle identifier 手动配置带有 CloudKit 支持的 iCloud 服务。

如果你通过 Apple Developer Console 启用了 iCloud 能力，那么请务必在你的 ios/[app]/[app].entitlements 文件中添加以下权限项（其中 dev.expo.my-app 为你的 bundle identifier）：

<key>com.apple.developer.icloud-container-identifiers</key>
<array>
    <string>iCloud.dev.expo.my-app</string>
</array>
<key>com.apple.developer.icloud-services</key>
<array>
    <string>CloudDocuments</string>
</array>
<key>com.apple.developer.ubiquity-container-identifiers</key>
<array>
    <string>iCloud.dev.expo.my-app</string>
</array>
<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)dev.expo.my-app</string>

Apple Developer Console 还要求创建一个 iCloud Container。在注册新的容器时，系统会要求你为该容器提供描述和标识符。描述可以填写任意名称。标识符请添加 iCloud.<your_bundle_identifier>（与 com.apple.developer.icloud-container-identifiers 和 com.apple.developer.ubiquity-container-identifiers 权限项中使用的值相同）。

与 `expo-file-system` 搭配使用

当将 expo-document-picker 与 expo-file-system 一起使用时，文件系统并不总是能够在 expo-document-picker 选中文件后立即读取该文件。

为了让 expo-file-system 能够在文件被选中后立即读取它，你需要确保 copyToCacheDirectory 选项设置为 true。

API

import * as DocumentPicker from 'expo-document-picker';

Component

`getDocumentAsync`

Android

iOS

Web

Type: React.Element<DocumentPickerOptions>

Display the system UI for choosing a document. By default, the chosen file is copied to the app's internal cache directory.

Notes for Web: The system UI can only be shown after user activation (e.g. a Button press). Therefore, calling getDocumentAsync in componentDidMount, for example, will not work as intended. The cancel event will not be returned in the browser due to platform restrictions and inconsistencies across browsers.

Types

`DocumentPickerAsset`

Android

iOS

Web

Property	Type	Description
base64(optional)	`string`	Only for: Web Base64 string of the file.
file(optional)	`File`	Only for: Web `File` object for the parity with web File API.
lastModified	`number`	Timestamp of last document modification. Web API specs The lastModified provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date.
mimeType(optional)	`string`	Document MIME type.
name	`string`	Document original name.
size(optional)	`number`	Document size in bytes.
uri	`string`	An URI to the local document file.

`DocumentPickerCanceledResult`

Android

iOS

Web

Type representing canceled pick result.

Property	Type	Description
assets	`null`	Always `null` when the request was canceled.
canceled	`true`	Always `true` when the request was canceled.
output(optional)	`null`	Only for: Web Always `null` when the request was canceled.

`DocumentPickerOptions`

Android

iOS

Web

Property	Type	Description
base64(optional)	`boolean`	Only for: Web If `true`, asset url is base64 from the file If `false`, asset url is the file url parameter Default:`true`
copyToCacheDirectory(optional)	`boolean`	Only for: Android iOS If `true`, the picked file is copied to `FileSystem.CacheDirectory`, which allows other Expo APIs to read the file immediately. This may impact performance for large files, so you should consider setting this to `false` if you expect users to pick particularly large files and your app does not need immediate read access. Default:`true`
multiple(optional)	`boolean`	Allows multiple files to be selected from the system UI. Default:`false`
type(optional)	`string \| string[]`	The MIME type(s) of the documents that are available to be picked. It also supports wildcards like `'image/'` to choose any image. To allow any type of document you can use `'/'`. Default:`'/*'`

`DocumentPickerResult`

Android

iOS

Web

Literal Type: union

Type representing successful and canceled document pick result.

Acceptable values are: DocumentPickerSuccessResult | DocumentPickerCanceledResult

`DocumentPickerSuccessResult`

Android

iOS

Web

Type representing successful pick result.

Property	Type	Description
assets	`DocumentPickerAsset[]`	An array of picked assets.
canceled	`false`	If asset data have been returned this should always be `false`.
output(optional)	`FileList`	Only for: Web `FileList` object for the parity with web File API.

Expo DocumentPicker

安装

在 app 配置中进行配置

Example app.json with config plugin

Configurable properties

与 expo-file-system 搭配使用

API

Component

getDocumentAsync

Types

DocumentPickerAsset

DocumentPickerCanceledResult

DocumentPickerOptions

DocumentPickerResult

DocumentPickerSuccessResult

与 `expo-file-system` 搭配使用

`getDocumentAsync`

`DocumentPickerAsset`

`DocumentPickerCanceledResult`

`DocumentPickerOptions`

`DocumentPickerResult`

`DocumentPickerSuccessResult`