You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This package is supported in Expo managed workflow through the usage of [custom development clients](https://docs.expo.dev/development/getting-started/).
@@ -83,73 +86,69 @@ expo run:android
83
86
```
84
87
85
88
86
-
#### RN >= 0.63
89
+
#### RN >= 0.69
87
90
88
-
If you are using RN >= 0.63, only run `pod install` from the ios directory. Then rebuild your project. Older RN versions are not supported.
91
+
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.
⚠️ Breaking in v6: `pick` returns a `Promise<Array<DocumentPickerResponse>>` instead of `Promise<DocumentPickerResponse>`. If you were using `pick`, change those usages to `pickSingle`.
95
98
96
-
Use `pickMultiple`, `pickSingle` or `pick` to open a document picker for the user to select file(s). All methods return a Promise.
97
-
98
-
### `DocumentPicker.pickDirectory()`
99
+
Use `pickSingle` or `pick` to open a document picker for the user to select file(s).
99
100
100
-
Open a system directory picker. Returns a promise that resolves to (`{ uri: string }`) of the directory selected by user.
101
+
- with `pick`, you can use `allowMultiSelection` param to control whether user can select multiple files (`false` by default). Returns a `Promise<Array<DocumentPickerResponse>>`
101
102
102
-
### `DocumentPicker.pick(options)` and `DocumentPicker.pickMultiple(options)`
103
+
-`pickSingle` is "sugar function" on top of `pick` and only allows a single selection returns `Promise<DocumentPickerResponse>`
103
104
104
-
-`pick` is the most universal, you can use `allowMultiSelection` param to control whether or not user can select multiple files (`false` by default). Returns a `Promise<Array<DocumentPickerResponse>>`
105
105
106
-
`pickSingle` and `pickMultiple` are "sugar functions" on top of `pick`, and they _might be removed_ in a future release for increased API clarity.
106
+
#### `pickDirectory()`
107
107
108
-
-`pickSingle` only allows a single selection and the Promise will resolve to that single result (same behavior as `pick` in v5)
109
-
-`pickMultiple` allows multiple selection and the Promise will resolve to an array of results.
108
+
Open a system directory picker. Returns a promise that resolves to (`{ uri: string }`) of the directory selected by user.
110
109
111
110
## Options
112
111
113
112
All of the options are optional
114
113
115
114
#### `allowMultiSelection`:`boolean`
116
115
117
-
Whether selecting multiple files is allowed. For `pick`, this is `false` by default. `allowMultiSelection` is `false` for `pickSingle` and `true` for `pickMultiple` and cannot be overridden for those calls.
116
+
Whether selecting multiple files is allowed. For `pick`, this is `false` by default. `allowMultiSelection` is `false` for `pickSingle` and cannot be overridden.
118
117
119
118
#### `type`:`string|Array<string>`
120
119
121
-
The type or types of documents to allow selection of. May be an array of types as single type string.
120
+
The type or types of documents to allow selection of. An array of strings or single string.
122
121
123
-
- 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).
124
-
- On iOS these must be Apple "[Uniform Type Identifiers](https://developer.apple.com/documentation/uniformtypeidentifiers/system-declared_uniform_type_identifiers?language=objc)"
122
+
- 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).
123
+
- On iOS, these must be Apple "[Uniform Type Identifiers](https://developer.apple.com/documentation/uniformtypeidentifiers/system-declared_uniform_type_identifiers?language=objc)"
125
124
- If `type` is omitted it will be treated as `*/*` or `public.item`.
#### [iOS and Android only]`copyTo`:`"cachesDirectory" | "documentDirectory"`
128
127
129
-
Controls how the picker is presented, eg. on an iPad you may want to present it fullscreen. Defaults to `pageSheet`.
128
+
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.
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.
132
131
133
-
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.
132
+
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).
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 right in place.
136
+
Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to `pageSheet`.
138
137
139
-
#### [iOS and Android only]`copyTo`:`"cachesDirectory" | "documentDirectory"`
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 (eg. 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.
140
+
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.
142
141
143
-
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.
142
+
#### [iOS only]`mode`:`"import" | "open"`
144
143
145
-
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).
144
+
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.
146
145
147
146
#### [Windows only]`readContent`:`boolean`
148
147
149
148
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.
150
149
151
150
- 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)
152
-
- 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.
151
+
- 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.
153
152
154
153
```
155
154
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).
@@ -191,7 +190,7 @@ The file size of the document. _On Android some DocumentProviders may not provid
191
190
192
191
The base64 encoded content of the picked file if the option `readContent` was set to `true`.
193
192
194
-
## `DocumentPicker.types.*`
193
+
## `types.*`
195
194
196
195
`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).
197
196
@@ -209,26 +208,25 @@ The base64 encoded content of the picked file if the option `readContent` was se
209
208
-`DocumentPicker.types.xls`: xls files
210
209
-`DocumentPicker.types.xlsx`: xlsx files
211
210
212
-
###`DocumentPicker.isCancel(err)`
211
+
#### `isCancel(err)`
213
212
214
-
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.
213
+
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.
215
214
216
-
###`DocumentPicker.isInProgress(err)`
215
+
#### `isInProgress(err)`
217
216
218
-
If the user somehow manages to open multiple file pickers (eg. 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()`.
217
+
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()`.
219
218
220
219
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.
If `mode` is set to `open` iOS is giving you secure access to a file located outside from your sandbox.
223
+
If `mode` is set to `open`, iOS is giving you secure access to a file located outside from your sandbox.
225
224
In that case Apple is asking you to release the access as soon as you finish using the resource.
226
225
227
226
## Example
228
227
229
228
See the example app in `example` folder.
230
229
231
-
232
230
## How to upload picked files?
233
231
234
232
Use blob support that is built into react native - [see comment](https://github.com/rnmods/react-native-document-picker/issues/70#issuecomment-384335402).
0 commit comments