MIGRATION_GUIDE.md

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.

• 2.x to 2.2
• 1.x to 2.0
• 0.6 to 1.0
• 0.5 To 0.6

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.iOS.favoriteAsset(
  entity: entity,
  favorite: true,
);

After:

/// If succeed, a new entity will be returned.
final AssetEntity? newEntity = await PhotoManager.editor.iOS.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);