@onekeyfe/react-native-photo-library 3.0.179-alpha.303 → 3.0.179-alpha.306
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,6 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
Minimal add-only image saving. [Contract and acceptance](docs/SPEC.md).
|
|
4
4
|
|
|
5
|
+
## Installation and application configuration
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
yarn add @onekeyfe/react-native-photo-library react-native-nitro-modules@0.37.0
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Install iOS pods and rebuild the native application. This package has no Web
|
|
12
|
+
implementation. It registers its native object lazily on the first API call;
|
|
13
|
+
importing the JavaScript wrapper performs no permission request or file I/O.
|
|
14
|
+
|
|
15
|
+
On iOS, supply an application-specific `NSPhotoLibraryAddUsageDescription` in
|
|
16
|
+
Info.plist. This module uses `.addOnly` authorization, so its save operation does
|
|
17
|
+
not require `NSPhotoLibraryUsageDescription` or whole-library read authorization.
|
|
18
|
+
For Android 8–9 only, the application declares:
|
|
19
|
+
|
|
20
|
+
```xml
|
|
21
|
+
<uses-permission
|
|
22
|
+
android:name="android.permission.WRITE_EXTERNAL_STORAGE"
|
|
23
|
+
android:maxSdkVersion="28" />
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Android 10+ saves with MediaStore and does not require this legacy permission.
|
|
27
|
+
The application owns these declarations and the user-facing explanation.
|
|
28
|
+
|
|
29
|
+
## Save after an explicit user action
|
|
30
|
+
|
|
5
31
|
```ts
|
|
6
32
|
import PhotoLibrary from '@onekeyfe/react-native-photo-library';
|
|
7
33
|
|
|
@@ -26,3 +52,48 @@ access, and the system prompt describes access to photos, media and files.
|
|
|
26
52
|
Permanent denial is returned as `{status: 'denied', canAskAgain: false}`.
|
|
27
53
|
`PhotoLibraryError.code` identifies permission, missing input,
|
|
28
54
|
activity/concurrency and save failures.
|
|
55
|
+
|
|
56
|
+
## API and failure handling
|
|
57
|
+
|
|
58
|
+
The default export and named exports expose the same three methods:
|
|
59
|
+
|
|
60
|
+
| Method | Result and ownership |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `getSavePermission()` | `Promise<PhotoSavePermission>`; checks without a prompt. |
|
|
63
|
+
| `requestSavePermission()` | `Promise<PhotoSavePermission>`; request from a foreground user action. |
|
|
64
|
+
| `saveToLibrary(path)` | `Promise<void>`; resolves after the OS save completes. |
|
|
65
|
+
|
|
66
|
+
`PhotoSavePermission` contains `status` (`granted`, `denied`, or `undetermined`)
|
|
67
|
+
and `canAskAgain`. Handle denial in the application's existing settings flow;
|
|
68
|
+
do not retry a permanently denied request in a loop. Overlapping Android
|
|
69
|
+
permission requests reject rather than sharing an activity result.
|
|
70
|
+
|
|
71
|
+
| `PhotoLibraryError.code` | Meaning |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| `E_NO_LIBRARY_PERMISSION` | Saving lacks the required authorization. |
|
|
74
|
+
| `E_NO_IMAGE_DATA_FOUND` | Missing, invalid, non-image, or oversized input. |
|
|
75
|
+
| `E_CANNOT_SAVE_IMAGE` | The native save or legacy media scan failed. |
|
|
76
|
+
| `E_PERMISSION_IN_PROGRESS` | Another Android permission request is pending. |
|
|
77
|
+
| `E_ACTIVITY_DOES_NOT_EXIST` | No usable activity, or its lifecycle ended. |
|
|
78
|
+
| `E_UNKNOWN` | A failure without a recognized native error code. |
|
|
79
|
+
|
|
80
|
+
Catch operation failures using the exported `PhotoLibraryError` class and its
|
|
81
|
+
`code`. The wrapper removes unrecognized native error details; do not infer a
|
|
82
|
+
successful save from a permission result alone.
|
|
83
|
+
|
|
84
|
+
## Source-file and runtime boundaries
|
|
85
|
+
|
|
86
|
+
Pass an absolute local path or `file://` URI, not a remote URL or an Android
|
|
87
|
+
content URI. Keep the image unchanged until the promise settles. Saving runs
|
|
88
|
+
serially on a native background queue and leaves the source in caller ownership.
|
|
89
|
+
The module does not queue retries, create an application image cache, or provide
|
|
90
|
+
asset selection/deletion APIs. UI/background JS objects initialize independently;
|
|
91
|
+
the application's foreground runtime owns permission actions.
|
|
92
|
+
|
|
93
|
+
The [specification](docs/SPEC.md) records source and automated evidence separately
|
|
94
|
+
from App/device acceptance. Confirm the actual permission prompt, saved asset,
|
|
95
|
+
and failure cleanup on the target OS versions before shipping a new integration.
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
MIT; see [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@onekeyfe/react-native-photo-library",
|
|
3
|
-
"version": "3.0.179-alpha.
|
|
3
|
+
"version": "3.0.179-alpha.306",
|
|
4
4
|
"description": "Add-only photo saving with version-scoped Android write permission",
|
|
5
5
|
"main": "./lib/module/index.js",
|
|
6
6
|
"types": "./lib/typescript/src/index.d.ts",
|