PHPhotoLibrary
PHPhotoLibrary represents the system photo library. The app uses it to save an image as a new photo in the library.
Saving to the library requires the user to grant "Add Photos" permission. When the user hasn't been asked yet, the saving method shows the prompt itself first.
You need to install @nacrejs/photos first and write NSPhotoLibraryAddUsageDescription in nacre.config.json; for how, see PHPickerViewController, or see Core and capability packages.
Inheritance: NSObject → PHPhotoLibrary
Constructor
It can't be created with new. new PHPhotoLibrary() throws TypeError:
Illegal constructor: PHPhotoLibrary is created by the runtime, not by newThere is only one in the whole app; read it from PHPhotoLibrary.sharedPhotoLibrary.
Static properties
PHPhotoLibrary.sharedPhotoLibrary read-only
The system photo library. Reading it twice gives the same object.
Static methods
| Method | Description |
|---|---|
PHPhotoLibrary.authorizationStatusForAccessLevel() | Reads the current authorization status without a prompt |
PHPhotoLibrary.requestAuthorizationForAccessLevel() | Requests permission; returns a Promise |
Instance methods
| Method | Description |
|---|---|
performChanges() | Modifies the library: saves a new photo |
Authorization status
| Value | Meaning |
|---|---|
'notDetermined' | The user hasn't been asked yet |
'authorized' | The user allowed it |
'denied' | The user denied it |
'restricted' | Restricted by the system (parental controls and the like); the user can't change it either |
'limited' | The user granted access to only some photos. Doesn't occur for the 'addOnly' level |
The system asks the user only once. After the user has denied it, the app can't show the prompt again and can only ask the user to turn it on in the system Settings. There is no event when the status changes: the user can only change it in the prompt or by leaving the app for Settings, so read it once when you need it.
Errors
When the Promise from performChanges() or requestAuthorizationForAccessLevel() is rejected, you get an Error, called PHPhotoLibraryError in the type definitions. It has two extra fields: code (number) and domain (string), the error code and error domain from the system.
name | When |
|---|---|
NotAllowedError | The user didn't allow it, or it is restricted by the system |
InvalidStateError | The project doesn't have NSPhotoLibraryAddUsageDescription. Doesn't happen with projects generated by the CLI, which stops at generation |
PhotosError | Other failures, such as insufficient storage. See message and code for the specific reason |
The code and domain in each case are not verified in the simulator.
Examples
const photo = UIImage.imageNamed('JS/assets/photo');
if (photo !== null) {
try {
await PHPhotoLibrary.sharedPhotoLibrary.performChanges({
creationRequestForAssetFromImage: photo,
});
console.log('Saved');
} catch (err) {
console.log('Not saved: ' + /** @type {Error} */ (err).name);
}
}Effect (not verified in the simulator): On the first call, the system shows a permission prompt with the sentence written in nacre.config.json. Tap "Allow", and the console prints Saved and the system Photos app has a new image. Tap "Don't Allow", and it prints Not saved: NotAllowedError.
Corresponding iOS API
| ObjC | JS |
|---|---|
PHPhotoLibrary.sharedPhotoLibrary | PHPhotoLibrary.sharedPhotoLibrary |
[PHPhotoLibrary authorizationStatusForAccessLevel:PHAccessLevelAddOnly] | PHPhotoLibrary.authorizationStatusForAccessLevel('addOnly') |
[PHPhotoLibrary requestAuthorizationForAccessLevel:PHAccessLevelAddOnly handler:^(PHAuthorizationStatus status) { … }] | await PHPhotoLibrary.requestAuthorizationForAccessLevel('addOnly') |
[library performChanges:^{ [PHAssetChangeRequest creationRequestForAssetFromImage:image]; } completionHandler:^(BOOL success, NSError *error) { … }] | await library.performChanges({ creationRequestForAssetFromImage: image }) |
The last row has a different shape. In ObjC the first argument is a block of code, with the changes written inside it; in JS it is an object whose keys name the kind of change to make.
See also
- Picking photos from and saving photos to the library: saving, checking permission first, telling the user after a denial
PHPickerViewController: letting the user choose photos, no permission needed- Configuring the app: where usage descriptions go and how to write them per language
UIImage: the type of the image to save