This document gathered all breaking changes and migrations requirement between major versions.
Due to the support of the limited permission status on Android,
the permission overlay will also displays on Android.
Thus, iOSPermissionOverlay is now migrating to permissionOverlay.
AssetPickerBuilderDelegate.viewAsset has 2 changes:
- It now uses the generic type of the delegate rather than always
AssetEntity. - The
indexof arguments is now nullable, to indicate the behavior of previewing selected assets only.
PermissionRequestOption has been added to
AssetPickerDelegate.permissionCheck and
AssetPickerDelegate.pickAssetsWithDelegate as an argument.
Classes that extend AssetPickerDelegate and override these methods must migrate,
Delegates that use AssetPicker.permissionCheck
should choose whether to pass the request option.
Before:
-
AssetPicker.permissionCheck();
-
Future<PermissionState> permissionCheck();
-
Future<List<Asset>?> pickAssetsWithDelegate<Asset, Path, PickerProvider extends AssetPickerProvider<Asset, Path>>( BuildContext context, { required AssetPickerBuilderDelegate<Asset, Path> delegate, Key? key, bool useRootNavigator = true, AssetPickerPageRouteBuilder<List<Asset>>? pageRouteBuilder, })
After:
-
AssetPicker.permissionCheck(requestOption: ...);
-
Future<PermissionState> permissionCheck({ PermissionRequestOption requestOption = const PermissionRequestOption, });
-
Future<List<Asset>?> pickAssetsWithDelegate<Asset, Path, PickerProvider extends AssetPickerProvider<Asset, Path>>( BuildContext context, { required AssetPickerBuilderDelegate<Asset, Path> delegate, PermissionRequestOption requestOption = const PermissionRequestOption, Key? key, bool useRootNavigator = true, AssetPickerPageRouteBuilder<List<Asset>>? pageRouteBuilder, })
isAppleOS in AssetPickerBuilderDelegate and AssetPickerViewerBuilderDelegate
has been refactored to relies on the TargetPlatform from a given BuildContext.
Delegates that extends those should update the signature at least.
Before:
bool get isAppleOS;After:
bool isAppleOS(BuildContext context);Delegates extending AssetPickerBuilderDelegate that implements selectAsset
should add the index argument to its signature.
Before:
void selectAsset(
BuildContext context,
Asset asset,
bool selected,
);After:
void selectAsset(
BuildContext context,
Asset asset,
int index,
bool selected,
);Delegates that extend AssetPickerBuilderDelegate should now implement viewAsset.
Delegates that extend DefaultAssetPickerBuilderDelegate are not required to do so.
viewAsset is abstracted in the AssetPickerBuilderDelegate:
Future<void> viewAsset(
BuildContext context,
int index,
AssetEntity currentAsset,
);The new method is implemented in the DefaultAssetPickerBuilderDelegate.
It's a private method previously which not allow to modify.
AssetPathEntity.assetCountAsyncwas introduced in fluttercandies/flutter_photo_manager#784 to improve the loading performance during paths obtain. By migrating the asynchronous getter, we need to introduce a new conceptPathWrapperto hold metadata together, but initialize fields separately.containsPathModifiedis nowfalseby default (previouslytrue), and can be changed accordingly.
currentPathhas been changed fromPath?toPathWrapper<Path>?.pathsListhas been removed, and addedAssetPickerProvider.paths.totalAssetsCountis now nullable to indicates initialization.getThumbnailFromPathandswitchPathhave different signature fromPathtoPathWrapper<Path>.
pathEntityWidgethas different signature fromPathtoPathWrapper<Path>, and theisAudioargument has been removed.
sort has a different signature, which needs PathWrappers to sort. More specifically:
Before:
void sort(List<Path> list) {}After:
void soft(List<PathWrapper<Path>> list) {}- Nearly all delegates are updated due to semantic support and de-nested improvements.
- Most arguments in
pickAssetshave been gathered as theAssetPickerConfig. - Most text delegates has been renamed with
*AssetPickerTextDelegate. AssetsPickerTextDelegatehas been renamed toAssetPickerTextDelegate(Asset without s).
gridThumbSizehas been renamed togridThumbnailSizeand has different type.pathThumbSizehas been renamed topathThumbnailSizeand has different type.previewThumbSizehas been renamed topreviewThumbnailSizeand has different type.
Before:
AssetPicker.pickAssets(
context,
maxAssets: maxAssetsCount,
selectedAssets: assets,
requestType: RequestType.image,
)After:
AssetPicker.pickAssets(
context,
pickerConfig: AssetPickerConfig(
maxAssets: maxAssetsCount,
selectedAssets: assets,
requestType: RequestType.image,
),
)This method no longer requires the provider argument, delegate should hold provider itself if necessary.
- The abstract delegate doesn't require a
provideranymore, custom delegates should maintain their own providers. - The
ChangeNotifierProvideris no longer held inside thepickAssetsmethod, custom delegates should provide the notifier on their own. keepScrollOffsethas been moved to the default delegate instead of the abstract one.- Custom delegates must implement
isSingleAssetMode,selectAsset,assetGridItemSemanticsBuilderandbuild. selectIndicatormethod now has a different signature.disposemust call super when extending.
isSwitchingPathnow holds by the default delegate.currentPathEntityhas been renamed tocurrentPath.getAssetsFromEntityhas been renamed togetAssetsFromPath.getFirstThumbFromPathEntityhas been renamed togetThumbnailFromPath.getAssetPathListhas been renamed togetPaths.pathEntityListhas been renamed topathsList.validPathThumbCounthas been renamed tovalidPathThumbnailsCount.
previewThumbSizehas been renamed topreviewThumbnailSizeand has different type.
If you didn't extend AssetPickerBuilderDelegate or AssetTextDelegate to build delegates on your own,
you can stop reading.
- User who extended
AssetPickerBuilderDelegateneeds to update the subclass with the latest changes. AssetsPickerTextDelegateis not abstract anymore.
New arguments:
PermissionState initialPermission: The intention of this change is to be capable with various ofPermissionState. If your delegate didn't require a permission check, you can passPermissionState.authorizeddirectly.keepScrollOffset: To hold the provider and delegate without disposing, and keep the scroll offset with the last picking.
Other changes:
assetsGridBuilderis not implemented by default.- The
findChildIndexBuilderandassetsGridItemCountmethods have new signature. They require calculating placeholders count on iOS/macOS by default.
- Added the
isDisplayingDetailnotifier. - Added double tap animation series of fields.
- This delegate is now a normal class with Chinese language implemented by default,
which makes
DefaultAssetsPickerTextDelegateremoved. If you used to useDefaultAssetsPickerTextDelegate(), useAssetsPickerTextDelegate()instead.
- The
switchPathmethod has a different signature:
Before:
void switchPath(Path pathEntity);After:
Future<void> switchPath([P? pathEntity]);SortPathDelegate accepts a generic type Path now, and the type will be delivered to the sort method.
If you only use the AssetPicker.pickAssets and AssetEntityImageProvider, didn't use AssetPickerViewer,
AssetPickerProvider, or other components separately, you can stop reading.
The AssetPicker and the AssetPickerViewer are only a builder since 5.x, all widgets construct were moved
to AssetPickerBuilderDelegate and AssetPickerViewerBuilderDelegate, and these delegates are both abstract.
By splitting delegates, now you can build your own picker with custom types, style, and widgets.
For how to implement a custom picker, see the example's custom page for more implementation details.
-
If you have ever use
AssetPickerViewer.pushToViewer, the propertiesassetshas changed topreviewAssets. -
If you have extended an
AssetPickerProviderorAssetPickerViewerProvider, it now requires you to pass generic typeAssetandPath, and handle the entities on your own.