|
1 | 1 | # react-native-document-picker |
2 | 2 |
|
3 | | -📣📣 A full rewrite of the library is in progress. 📣📣 |
| 3 | +📣📣 A full rewrite of the library is DONE. 📣📣 |
4 | 4 |
|
5 | | -Please subscribe to [this issue](https://github.com/rnmods/react-native-document-picker/issues/603) to receive updates. |
| 5 | +See the new [docs here](https://react-native-documents.github.io/) |
6 | 6 |
|
7 | 7 | 🚧🚧 GH discussions available 🚧🚧 |
8 | 8 |
|
9 | 9 | If you want to ask questions, we opened [GH discussions](https://github.com/rnmods/react-native-document-picker/discussions) for that purpose! 🤗 Issue tracker is now reserved for bugs and feature requests only and issues not following the issue template can be closed. Thank you! |
10 | | - |
11 | | -A React Native wrapper for: |
12 | | - |
13 | | -- Apple's `UIDocumentPickerViewController` |
14 | | -- Android's `Intent.ACTION_GET_CONTENT` |
15 | | -- Windows `Windows.Storage.Pickers` |
16 | | - |
17 | | -<table> |
18 | | - <tr><td><strong>iOS</strong></td><td><strong>Android</strong></td></tr> |
19 | | - <tr> |
20 | | - <td><p align="center"><img src="/docs/ios_screenshot.jpeg" height="500"></p></td> |
21 | | - <td><p align="center"><img src="/docs/android_screenshot.jpg" height="500"></p></td> |
22 | | - </tr> |
23 | | -</table> |
24 | | - |
25 | | -Requires RN >= 0.69, Android 5.0+ and iOS 11+ |
26 | | - |
27 | | -# Table of Contents |
28 | | - |
29 | | -- [react-native-document-picker](#react-native-document-picker) |
30 | | - - [Installation](#installation) |
31 | | - - [RN >= 0.69](#rn--069) |
32 | | - - [API](#api) |
33 | | - - [pickSingle(options) / pick(options)](#picksingleoptions--pickoptions) |
34 | | - - [pickDirectory()](#pickdirectory) |
35 | | - - [Options](#options) |
36 | | - - [allowMultiSelection:boolean](#allowmultiselectionboolean) |
37 | | - - [type:string|Array<string>](#typestringarraystring) |
38 | | - - [[iOS and Android only] copyTo:"cachesDirectory" | "documentDirectory"](#ios-and-android-only-copytocachesdirectory--documentdirectory) |
39 | | - - [[iOS only] presentationStyle:'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'](#ios-only-presentationstylefullscreen--pagesheet--formsheet--overfullscreen) |
40 | | - - [[iOS only] transitionStyle:'coverVertical' | 'flipHorizontal' | 'crossDissolve' | 'partialCurl'](#ios-only-transitionstylecoververtical--fliphorizontal--crossdissolve--partialcurl) |
41 | | - - [[iOS only] mode:"import" | "open"](#ios-only-modeimport--open) |
42 | | - - [[Windows only] readContent:boolean](#windows-only-readcontentboolean) |
43 | | - - [Result](#result) |
44 | | - - [uri](#uri) |
45 | | - - [fileCopyUri](#filecopyuri) |
46 | | - - [type](#type) |
47 | | - - [name](#name) |
48 | | - - [size](#size) |
49 | | - - [[Windows only] content](#windows-only-content) |
50 | | - - [types.\*](#types) |
51 | | - - [isCancel(err)](#iscancelerr) |
52 | | - - [isInProgress(err)](#isinprogresserr) |
53 | | - - [[iOS only] releaseSecureAccess(uris: Array<string>)](#ios-only-releasesecureaccessuris-arraystring) |
54 | | - - [Example](#example) |
55 | | - - [How to upload picked files?](#how-to-upload-picked-files) |
56 | | - - [Help wanted: Improvements](#help-wanted-improvements) |
57 | | - |
58 | | -### Installation |
59 | | - |
60 | | -#### React Native |
61 | | - |
62 | | -```bash |
63 | | -npm i --save react-native-document-picker |
64 | | - |
65 | | -OR |
66 | | - |
67 | | -yarn add react-native-document-picker |
68 | | -``` |
69 | | - |
70 | | -```ts |
71 | | -import DocumentPicker from 'react-native-document-picker' |
72 | | -``` |
73 | | - |
74 | | -#### Expo |
75 | | - |
76 | | -This package is supported in Expo managed workflow through the usage of [custom development clients](https://docs.expo.dev/development/getting-started/). |
77 | | - |
78 | | -```bash |
79 | | -expo install react-native-document-picker |
80 | | - |
81 | | -# Create a development build (provided you have expo-dev-client installed and set up) |
82 | | -eas build |
83 | | - |
84 | | -# Or run it locally |
85 | | -expo prebuild |
86 | | -expo run:ios |
87 | | -expo run:android |
88 | | -``` |
89 | | - |
90 | | -#### RN >= 0.69 |
91 | | - |
92 | | -If you are using RN >= 0.69, only run `pod install` from the ios directory. Then rebuild your project. Older RN versions are not supported. |
93 | | - |
94 | | -New architecture is supported with RN >= 71. |
95 | | - |
96 | | -## API |
97 | | - |
98 | | -#### `pickSingle(options)` / `pick(options)` |
99 | | - |
100 | | -⚠️ Breaking in v6: `pick` returns a `Promise<Array<DocumentPickerResponse>>` instead of `Promise<DocumentPickerResponse>`. If you were using `pick`, change those usages to `pickSingle`. |
101 | | - |
102 | | -Use `pickSingle` or `pick` to open a document picker for the user to select file(s). |
103 | | - |
104 | | -- with `pick`, you can use `allowMultiSelection` param to control whether user can select multiple files (`false` by default). Returns a `Promise<Array<DocumentPickerResponse>>` |
105 | | - |
106 | | -- `pickSingle` is "sugar function" on top of `pick` and only allows a single selection returns `Promise<DocumentPickerResponse>` |
107 | | - |
108 | | -#### `pickDirectory()` |
109 | | - |
110 | | -Open a system directory picker. Returns a promise that resolves to (`{ uri: string }`) of the directory selected by user. |
111 | | - |
112 | | -## Options |
113 | | - |
114 | | -All of the options are optional |
115 | | - |
116 | | -#### `allowMultiSelection`:`boolean` |
117 | | - |
118 | | -Whether selecting multiple files is allowed. For `pick`, this is `false` by default. `allowMultiSelection` is `false` for `pickSingle` and cannot be overridden. |
119 | | - |
120 | | -#### `type`:`string|Array<string>` |
121 | | - |
122 | | -The type or types of documents to allow selection of. An array of strings or single string. |
123 | | - |
124 | | -- On Android, these are MIME types such as `text/plain` or partial MIME types such as `image/*`. See [common MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). |
125 | | -- On iOS, these must be Apple [Uniform Type Identifiers](https://developer.apple.com/documentation/uniformtypeidentifiers/system-declared_uniform_type_identifiers?language=objc) |
126 | | -- If `type` is omitted it will be treated as `*/*` or `public.item`. |
127 | | - |
128 | | -#### [iOS and Android only] `copyTo`:`"cachesDirectory" | "documentDirectory"` |
129 | | - |
130 | | -If specified, the picked file is copied to `NSCachesDirectory` / `NSDocumentDirectory` (iOS) or `getCacheDir` / `getFilesDir` (Android). The uri of the copy will be available in result's `fileCopyUri`. If copying the file fails (e.g. due to lack of free space), `fileCopyUri` will be `null`, and more details about the error will be available in `copyError` field in the result. |
131 | | - |
132 | | -This should help if you need to work with the file(s) later on, because by default, [the picked documents are temporary files. They remain available only until your application terminates](https://developer.apple.com/documentation/uikit/uidocumentpickerdelegate/2902364-documentpicker). This may impact performance for large files, so keep this in mind if you expect users to pick particularly large files and your app does not need immediate read access. |
133 | | - |
134 | | -On Android, this can be used to obtain local, on-device copy of the file (e.g. if user picks a document from Google Drive, this will download it locally to the phone). |
135 | | - |
136 | | -#### [iOS only] `presentationStyle`:`'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'` |
137 | | - |
138 | | -Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to `pageSheet`. |
139 | | - |
140 | | -#### [iOS only] `transitionStyle`:`'coverVertical' | 'flipHorizontal' | 'crossDissolve' | 'partialCurl'` |
141 | | - |
142 | | -Configure the transition style of the picker. Defaults to `coverVertical`, when the picker is presented, its view slides up from the bottom of the screen. |
143 | | - |
144 | | -#### [iOS only] `mode`:`"import" | "open"` |
145 | | - |
146 | | -Defaults to `import`. If `mode` is set to `import` the document picker imports the file from outside to inside the sandbox, otherwise if `mode` is set to `open` the document picker opens the file in-place. |
147 | | - |
148 | | -#### [Windows only] `readContent`:`boolean` |
149 | | - |
150 | | -Defaults to `false`. If `readContent` is set to true the content of the picked file/files will be read and supplied in the result object. |
151 | | - |
152 | | -- Be aware that this can introduce a huge performance hit in case of big files. (The files are read completely and into the memory and encoded to base64 afterwards to add them to the result object) |
153 | | -- However, reading the file directly from within the Thread which managed the picker can be necessary on Windows: Windows Apps can only read the Downloads folder and their own app folder by default and If a file is outside of these locations it cannot be acessed directly. However if the user picks the file through a file picker permissions to that file are granted implicitly. |
154 | | - |
155 | | - ``` |
156 | | - In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest (see App capability declarations), or by calling a file picker to let the user pick files and folders for the app to access (see Open files and folders with a picker). |
157 | | - ``` |
158 | | - |
159 | | - https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions |
160 | | - |
161 | | - Unfortunately that permission is not granted to the whole app, but only the Thread which handled the filepicker. Therefore, it can be useful to read the file directly. |
162 | | - |
163 | | -- You can use `react-native-fs` on Android and IOS to read the picked file. |
164 | | - |
165 | | -## Result |
166 | | - |
167 | | -The `pick` Promise resolves to an array of objects with the following keys. |
168 | | - |
169 | | -#### `uri` |
170 | | - |
171 | | -The URI representing the document picked by the user. _On iOS this will be a `file://` URI for a temporary file in your app's container if `mode` is not specified or set at `import` otherwise it will be the original `file://` URI. On Android this will be a `content://` URI for a document provided by a DocumentProvider that must be accessed with a ContentResolver._ |
172 | | - |
173 | | -Please note that you might need to use `decodeURIComponent` in order to get the URI in the format you need for further processing, e.g. when using `react-native-fs`. |
174 | | - |
175 | | -#### `fileCopyUri` |
176 | | - |
177 | | -If `copyTo` option is specified, this will point to a local copy of picked file. Otherwise, this is `null`. |
178 | | - |
179 | | -#### `type` |
180 | | - |
181 | | -The MIME type of the file. _On Android some DocumentProviders may not provide MIME types for their documents. On iOS this MIME type is based on the best MIME type for the file extension according to Apple's internal "Uniform Type Identifiers" database._ |
182 | | - |
183 | | -#### `name` |
184 | | - |
185 | | -The display name of the file. _This is normally the filename of the file, but Android does not guarantee that this will be a filename from all DocumentProviders._ |
186 | | - |
187 | | -#### `size` |
188 | | - |
189 | | -The file size of the document. _On Android some DocumentProviders may not provide this information for a document._ |
190 | | - |
191 | | -#### [Windows only] `content` |
192 | | - |
193 | | -The base64 encoded content of the picked file if the option `readContent` was set to `true`. |
194 | | - |
195 | | -## `types.*` |
196 | | - |
197 | | -`DocumentPicker.types.*` provides a few common types for use as `type` values, these types will use the correct format for each platform (MIME types on Android, UTIs on iOS). |
198 | | - |
199 | | -If you need to provide your own file type filtering: |
200 | | - |
201 | | -For Android, see [common MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). |
202 | | - |
203 | | -For iOS [Uniform Type Identifiers](https://developer.apple.com/documentation/uniformtypeidentifiers/system-declared_uniform_type_identifiers?language=objc). |
204 | | - |
205 | | -Also, searching Google usually helps. |
206 | | - |
207 | | -- `DocumentPicker.types.allFiles`: All document types, on Android this is `*/*`, on iOS is `public.item` |
208 | | -- `DocumentPicker.types.images`: All image types |
209 | | -- `DocumentPicker.types.plainText`: Plain text files |
210 | | -- `DocumentPicker.types.audio`: All audio types |
211 | | -- `DocumentPicker.types.pdf`: PDF documents |
212 | | -- `DocumentPicker.types.zip`: Zip files |
213 | | -- `DocumentPicker.types.csv`: Csv files |
214 | | -- `DocumentPicker.types.doc`: doc files |
215 | | -- `DocumentPicker.types.docx`: docx files |
216 | | -- `DocumentPicker.types.ppt`: ppt files |
217 | | -- `DocumentPicker.types.pptx`: pptx files |
218 | | -- `DocumentPicker.types.xls`: xls files |
219 | | -- `DocumentPicker.types.xlsx`: xlsx files |
220 | | - |
221 | | -#### `isCancel(err)` |
222 | | - |
223 | | -If the user cancels the document picker without choosing a file (by pressing the system back button on Android or the Cancel button on iOS), the Promise will be rejected with a cancellation error. You can check for this error using `DocumentPicker.isCancel(err)` allowing you to ignore it and cleanup any parts of your interface that may not be needed anymore. |
224 | | - |
225 | | -#### `isInProgress(err)` |
226 | | - |
227 | | -If the user somehow manages to open multiple file pickers (e.g. due the app being unresponsive), then only the picked result from the last opened picker will be considered and the promises from previous opened pickers will be rejected with an error that you can check using `DocumentPicker.isInProgress()`. |
228 | | - |
229 | | -This behavior might change in future to allow opening only a single picker at a time. The internal logic is currently implemented only on iOS. |
230 | | - |
231 | | -#### [iOS only] `releaseSecureAccess(uris: Array<string>)` |
232 | | - |
233 | | -If `mode` is set to `open`, iOS is giving you secure access to a file located outside from your sandbox. |
234 | | -In that case Apple is asking you to release the access as soon as you finish using the resource. |
235 | | - |
236 | | -## Example |
237 | | - |
238 | | -See the example app in `example` folder. |
239 | | - |
240 | | -## How to upload picked files? |
241 | | - |
242 | | -Use blob support that is built into react native - [see comment](https://github.com/rnmods/react-native-document-picker/issues/70#issuecomment-384335402). |
243 | | -If you need to track upload progress, use `XMLHttpRequest` [see here](https://gist.github.com/Tamal/9231005f0c62e1a3f23f60dc2f46ae35) |
244 | | - |
245 | | -Alternatively, use [https://github.com/johanneslumpe/react-native-fs](https://github.com/johanneslumpe/react-native-fs) |
246 | | - |
247 | | -## Help wanted: Improvements |
248 | | - |
249 | | -- Fix Xcode warning about constraints |
250 | | -- support options for the [UIDocumentPickerViewController](https://developer.apple.com/library/ios/documentation/FileManagement/Conceptual/DocumentPickerProgrammingGuide/AccessingDocuments/AccessingDocuments.html#//apple_ref/doc/uid/TP40014451-CH2-SW5) |
0 commit comments