Expo DocumentPicker

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

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.0

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

安装

Terminal

- npx expo install expo-document-picker

- yarn expo install expo-document-picker

- pnpm expo install expo-document-picker

- bun expo install expo-document-picker

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

在应用配置中进行配置

如果项目中使用配置插件（Continuous Native Generation（CNG）），则可以使用内置的配置插件配置 expo-document-picker。该插件允许你配置各种无法在运行时设置、且必须构建新的应用二进制文件才能生效的属性。如果应用不使用 CNG，则需要手动配置此库。

Example app.json with config plugin

如果想启用 iCloud 存储功能，请按照配置属性中的说明，在应用配置文件中将 expo.ios.usesIcloudStorage 键设置为 true

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

app.json

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

Configurable properties

Name	Default	Description
`iCloudContainerEnvironment`	`undefined`	Only for: iOS 设置用于 AdHoc iOS 构建的 iOS `com.apple.developer.icloud-container-environment` entitlement。可能的值：`Development`、`Production`。请参阅关于内部分发构建的 eas-cli issue #693。
`kvStoreIdentifier`	`undefined`	Only for: iOS 覆盖默认的 iOS `com.apple.developer.ubiquity-kvstore-identifier` entitlement，该 entitlement 使用你的 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 service

如果通过 Apple Developer Console 启用了 iCloud capability，请务必在 ios/[app]/[app].entitlements 文件中添加以下 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 entitlements 中使用的值相同）

与 `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`	A 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

安装

在应用配置中进行配置

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`