Migration Guide

The document only describes the equivalent changes to the API. If you want to see the new feature support, please refer to readme and change log.

Migration Guide

3.x to 3.4

Overall

In order to let developers write the most precise API usage, the filename of saveLivePhoto has migrated to title.

`saveLivePhoto`

Before:

final entity = await PhotoManager.editor.saveLivePhoto(
  imageFile: imageFile,
  videoFile: videoFile,
  filename: 'live_0',
);

After:

final entity = await PhotoManager.editor.saveLivePhoto(
  imageFile: imageFile,
  videoFile: videoFile,
  title: 'live_0',
);

3.x to 3.3

Overall

In order to let developers write the most precise API usage, the title of saveImage has migrated to filename.

`saveImage`

Before:

final entity = await PhotoManager.editor.saveImage(bytes, title: 'new.jpg');

After:

final entity = await PhotoManager.editor.saveImage(bytes, filename: 'new.jpg');

3.0.x to 3.1

Overall

containsLivePhotos now defaults to false instead of true.
AssetPathEntity.darwinType and AssetPathEntity.darwinSubtype are deprecated.

`containsLivePhotos`

Live Photos are used to being obtained when querying images and videos, the behavior sometimes causes drama that users don't want to see images when getting videos. The flag is now disabled by default.

`AlbumType`

The extra information of the album type has been abstract as AlbumType which contains Darwin (iOS/macOS) and OpenHarmony album information. The new class deprecates AssetPathEntity.darwinType and AssetPathEntity.darwinSubtype, AssetPathEntity.albumTypeEx should be used instead.

Before:

final path = await AssetPathEntity.fromId('');
final PMDarwinAssetCollectionType? darwinType = path.darwinType;
final PMDarwinAssetCollectionSubtype? darwinSubtype = path.darwinSubtype;

After:

final path = await AssetPathEntity.fromId('');
final PMDarwinAssetCollectionType? darwinType = path.albumTypeEx?.darwin?.type;
final PMDarwinAssetCollectionSubtype? darwinSubtype = path.albumTypeEx?.darwin?.subtype;

2.x to 3.0

Overall

Use Editor.darwin instead of Editor.iOS.
Use PermissionRequestOption instead of PermisstionRequestOption.
Use AssetPathEntity.assetCountAsync instead of AssetPathEntity.assetCount.
Removed AssetEntityImage and AssetEntityImageProvider.

`AssetEntityImage` and `AssetEntityImageProvider`

These classes are no longer provided from the package. Instead, include photo_manager_image_provider to use AssetEntityImage and AssetEntityImageProvider.

import 'package:photo_manager_image_provider/photo_manager_image_provider.dart';

2.x to 2.8

Overall

Methods invoked with assets permission no longer call for permissions implicitly. Users must follow the below methods to ensure permissions were granted:

PhotoManager.requestPermissionExtend(), verify if the result is authorized or limited.
PhotoManager.setIgnorePermissionCheck(true), ignoring permission checks, or handle permissions with other mechanisms.

PhotoManager.editor.deleteWithIds only move assets to the trash on Android 30 and above.

2.x to 2.2

Overall

AssetPathEntity.assetCount has been deprecated, and added a new asynchronized getter assetCountAsync.
FilterOptionGroup.containsEmptyAlbum has been removed.

`assetCount`

Before you can easily access total count of a path:

int get count => path.assetCount;

Now you can only use the new getter:

int count = await path.assetCountAsync;

Be aware that the change is to improve when gathering info from paths, which means usages with the previous field should be migrated to separate requests to improve the performance.

1.x to 2.0

This version mainly covers all valid issues, API deprecations, and few new features.

Overall

The org name has been updated from top.kikt to com.fluttercandies.
The plugin name on native side has been updated from ImageScanner to PhotoManager.
AssetPathEntity and AssetEntity are now immutable.
title are required when using saving methods.
RequestType.common is the default type for all type request.
Arguments with getAssetListPaged are now required with name.
PhotoManager.notifyingOfChange has no setter anymore.
PhotoManager.refreshAssetProperties and PhotoManager.fetchPathProperties have been moved to entities.
containsLivePhotos are true by default. If you previously used RequestType.video to filter assets, they'll include live photos now. To keep to old behavior, you should explicitly set containsLivePhotos to false in this case.
isLocallyAvailable now passes isOrigin, so it's been changed to isLocallyAvailable().

API migrations

There are several APIs have been removed, since they can't provide precise meanings, or can be replaced by new APIs. If you've used these APIs, consider migrating them to the latest version.

Removed API/class/field	Migrate destination
`PhotoManager.getImageAsset`	`PhotoManager.getAssetPathList(type: RequestType.image)`
`PhotoManager.getVideoAsset`	`PhotoManager.getAssetPathList(type: RequestType.video)`
`PhotoManager.fetchPathProperties`	`AssetPathEntity.fetchPathProperties`
`PhotoManager.refreshAssetProperties`	`AssetEntity.refreshProperties`
`PhotoManager.requestPermission`	`PhotoManager.requestPermissionExtend`
`AssetPathEntity.assetList`	N/A, use pagination APIs instead.
`AssetPathEntity.refreshPathProperties`	`AssetPathEntity.obtainForNewProperties`
`AssetEntity.createDtSecond`	`AssetEntity.createDateSecond`
`AssetEntity.fullData`	`AssetEntity.originBytes`
`AssetEntity.thumbData`	`AssetEntity.thumbnailData`
`AssetEntity.refreshProperties`	`AssetEntity.obtainForNewProperties`
`FilterOptionGroup.dateTimeCond`	`FilterOptionGroup.createTimeCond`
`ThumbFormat`	`ThumbnailFormat`
`ThumbOption`	`ThumbnailOption`

`getAssetListPaged`

Before:

AssetPathEntity.getAssetListPaged(0, 50);

After:

AssetPathEntity.getAssetListPaged(page: 0, size: 50);

Filtering only videos

Before:

final List<AssetPathEntity> paths = PhotoManager.getAssetPathList(type: RequestType.video);

After:

final List<AssetPathEntity> paths = PhotoManager.getAssetPathList(
  type: RequestType.video,
  filterOption: FilterOptionGroup(containsLivePhotos: false),
);

`isLocallyAvailable`

Before:

final bool isLocallyAvailable = await entity.isLocallyAvailable;

After:

// .file is locally available.
final bool isFileLocallyAvailable = await entity.isLocallyAvailable();

// .originFile is locally available.
final bool isOriginFileLocallyAvailable = await entity.isLocallyAvailable(
  isOrigin: true,
);

iOS Editor favorite asset

Before:

final bool isSucceed = await PhotoManager.editor.darwin.favoriteAsset(
  entity: entity,
  favorite: true,
);

After:

/// If succeed, a new entity will be returned.
final AssetEntity? newEntity = await PhotoManager.editor.darwin.favoriteAsset(
  entity: entity,
  favorite: true,
);

0.6 to 1.0

This version is a null-safety version.

Please read document for null-safety information in dart or flutter.

0.5 To 0.6

Before:

final dtCond = DateTimeCond(
  min: startDt,
  max: endDt,
  asc: asc,
)..dateTimeCond = dtCond;

After:

final dtCond = DateTimeCond(
  min: startDt,
  max: endDt,
);

final orderOption = OrderOption(
  type: OrderOptionType.createDate,
  asc: asc,
);

final filterOptionGroup = FilterOptionGroup()..addOrderOption(orderOption);

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!