Skip to content

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 new

There 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 ​

MethodDescription
PHPhotoLibrary.authorizationStatusForAccessLevel()Reads the current authorization status without a prompt
PHPhotoLibrary.requestAuthorizationForAccessLevel()Requests permission; returns a Promise

Instance methods ​

MethodDescription
performChanges()Modifies the library: saves a new photo

Authorization status ​

ValueMeaning
'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.

nameWhen
NotAllowedErrorThe user didn't allow it, or it is restricted by the system
InvalidStateErrorThe project doesn't have NSPhotoLibraryAddUsageDescription. Doesn't happen with projects generated by the CLI, which stops at generation
PhotosErrorOther 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 ​

js
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 ​

ObjCJS
PHPhotoLibrary.sharedPhotoLibraryPHPhotoLibrary.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 ​