Feat: Add path type filter (#950)

fluttercandies · Jul 25, 2023 · 5b4be35 · 5b4be35
1 parent a4256b3
commit 5b4be35
Show file tree

Hide file tree

Showing 23 changed files with 648 additions and 74 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,11 @@ that can be found in the LICENSE file. -->
 
 # CHANGELOG
 
-## 2.6.1
+## 2.7.0
+
+### Feature
+
+- Support `darwinType` and `darwinSubType` in `AssetPathEntity` on iOS and macOS. (#950)
 
 ### Improvements
 

diff --git a/README-ZH.md b/README-ZH.md
@@ -49,16 +49,18 @@ that can be found in the LICENSE file. -->
     * [原生平台的配置](#原生平台的配置)
       * [Android 配置准备](#android-配置准备)
         * [Kotlin, Gradle, AGP](#kotlin-gradle-agp)
-        * [Android 10 (Q, 29)](#android-10-q-29)
+        * [Android 10 (Q, 29)](#android-10--q-29-)
         * [Glide](#glide)
       * [iOS 配置准备](#ios-配置准备)
   * [使用方法](#使用方法)
     * [请求权限](#请求权限)
       * [iOS 受限的资源权限](#ios-受限的资源权限)
-    * [获取相簿或图集 (`AssetPathEntity`)](#获取相簿或图集-assetpathentity)
-    * [获取资源 (`AssetEntity`)](#获取资源-assetentity)
+    * [获取相簿或图集 (`AssetPathEntity`)](#获取相簿或图集--assetpathentity-)
+      * [`getAssetPathList` 方法的参数](#getassetpathlist-方法的参数)
+      * [PMPathFilterOption](#pmpathfilteroption)
+    * [获取资源 (`AssetEntity`)](#获取资源--assetentity-)
       * [通过 `AssetPathEntity` 获取](#通过-assetpathentity-获取)
-      * [通过 `PhotoManager` 方法 (2.6.0+) 获取](#通过-photomanager-方法-260-获取)
+      * [通过 `PhotoManager` 方法 (2.6.0+) 获取](#通过-photomanager-方法--260--获取)
       * [通过 ID 获取](#通过-id-获取)
       * [通过原始数据获取](#通过原始数据获取)
       * [通过 iCloud 获取](#通过-icloud-获取)
@@ -71,8 +73,8 @@ that can be found in the LICENSE file. -->
         * [原始数据的使用](#原始数据的使用)
         * [iOS 上文件检索时间过长](#ios-上文件检索时间过长)
     * [资源变动的通知回调](#资源变动的通知回调)
-      * [过滤资源](#过滤资源)
-        * [FilterOptionGroup](#filteroptiongroup)
+  * [过滤资源](#过滤资源)
+    * [FilterOptionGroup](#filteroptiongroup)
     * [CustomFilter](#customfilter)
       * [更高级的 CustomFilter](#更高级的-customfilter)
       * [相关类定义解释](#相关类定义解释)
@@ -83,7 +85,7 @@ that can be found in the LICENSE file. -->
   * [原生额外配置](#原生额外配置)
     * [Android 额外配置](#android-额外配置)
       * [Glide 相关问题](#glide-相关问题)
-      * [Android 13 (API level 33) 额外配置](#android-13-api-level-33-额外配置)
+      * [Android 13 (API level 33) 额外配置](#android-13--api-level-33--额外配置)
     * [iOS 额外配置](#ios-额外配置)
       * [配置系统相册名称的国际化](#配置系统相册名称的国际化)
     * [实验性功能](#实验性功能)
@@ -248,6 +250,34 @@ final List<AssetPathEntity> paths = await PhotoManager.getAssetPathList();
 
 详情请参阅 [`getAssetPathList`][]。
 
+#### `getAssetPathList` 方法的参数
+
+| 参数名           | 说明                                                         | 默认值              |
+| :--------------- | ------------------------------------------------------------ | ------------------- |
+| hasAll           | 如果你需要一个包含所有资源（AssetEntity) 的 PathEntity ，传入 true | true                |
+| onlyAll          | 如果你只需要一个包含所有资源的，传入true                     | false               |
+| type             | 资源文件的类型（视频、图片、音频）                           | RequestType.common  |
+| filterOption     | 用于筛选 AssetEntity，详情请参阅 [过滤资源](#过滤资源)       | FilterOptionGroup() |
+| pathFilterOption | 只对 iOS 和 macOS生效，对应原生中的相册类型，详情请参阅 [PMPathFilterOption](#pmpathfilteroption)。 | 默认为包含所有      |
+
+#### PMPathFilterOption
+
+自 2.7.0 版本开始提供，当前仅支持 iOS 和 macOS。
+
+```dart
+final List<PMDarwinAssetCollectionType> pathTypeList = []; // 配置为你需要的类型
+final List<PMDarwinAssetCollectionSubtype> pathSubTypeList = []; // 配置为你需要的子类型
+final darwinPathFilterOption = PMDarwinPathFilter(
+      type: pathTypeList,
+      subType: pathSubTypeList,
+    );
+PMPathFilter pathFilter = PMPathFilter();
+```
+
+ `PMDarwinAssetCollectionType`的枚举值一一对应 [PHAssetCollectionType | 苹果官网文档](https://developer.apple.com/documentation/photokit/phassetcollectiontype?language=objc).
+
+ `PMDarwinAssetCollectionSubtype` 的枚举值一一对应 [PHAssetCollectionSubType | 苹果官网文档](https://developer.apple.com/documentation/photokit/phassetcollectionsubtype?language=objc).
+
 ### 获取资源 (`AssetEntity`)
 
 资源（图片/视频/音频）以 [`AssetEntity`][] 的方式呈现，
@@ -464,7 +494,7 @@ PhotoManager.removeChangeCallback(changeNotify);
 PhotoManager.stopChangeNotify();
 ```
 
-#### 过滤资源
+## 过滤资源
 
 插件包含对资源过滤筛选的支持。
 以下的方法包含 `filterOption` 参数，用于指定资源过滤的条件。
@@ -482,7 +512,7 @@ PhotoManager.stopChangeNotify();
 - [FilterOptionGroup](#FilterOptionGroup)
 - [CustomFilter](#CustomFilter)
 
-##### FilterOptionGroup
+### FilterOptionGroup
 
 `FilterOptionGroup` 是 2.6.0 版本前唯一支持的筛选器实现。
 

diff --git a/README.md b/README.md
@@ -50,23 +50,25 @@ see the [migration guide](MIGRATION_GUIDE.md) for detailed info.
     * [Configure native platforms](#configure-native-platforms)
       * [Android config preparation](#android-config-preparation)
         * [Kotlin, Gradle, AGP](#kotlin-gradle-agp)
-        * [Android 10 (Q, 29)](#android-10-q-29)
+        * [Android 10 (Q, 29)](#android-10--q-29-)
         * [Glide](#glide)
       * [iOS config preparation](#ios-config-preparation)
   * [Usage](#usage)
     * [Request for permission](#request-for-permission)
       * [Limited entities access on iOS](#limited-entities-access-on-ios)
-    * [Get albums/folders (`AssetPathEntity`)](#get-albumsfolders-assetpathentity)
-    * [Get assets (`AssetEntity`)](#get-assets-assetentity)
+    * [Get albums/folders (`AssetPathEntity`)](#get-albumsfolders--assetpathentity-)
+      * [Params of `getAssetPathList`](#params-of-getassetpathlist)
+      * [PMPathFilterOption](#pmpathfilteroption)
+    * [Get assets (`AssetEntity`)](#get-assets--assetentity-)
       * [From `AssetPathEntity`](#from-assetpathentity)
-      * [From `PhotoManager` (Since 2.6)](#from-photomanager-since-26)
+      * [From `PhotoManager` (Since 2.6)](#from-photomanager--since-26-)
       * [From ID](#from-id)
       * [From raw data](#from-raw-data)
       * [From iCloud](#from-icloud)
       * [Display assets](#display-assets)
-      * [Obtain "Live Photos"](#obtain-live-photos)
-        * [Filtering only "Live Photos"](#filtering-only-live-photos)
-        * [Obtain the video from "Live Photos"](#obtain-the-video-from-live-photos)
+      * [Obtain "Live Photos"](#obtain--live-photos-)
+        * [Filtering only "Live Photos"](#filtering-only--live-photos-)
+        * [Obtain the video from "Live Photos"](#obtain-the-video-from--live-photos-)
       * [Limitations](#limitations)
         * [Android 10 media location permission](#android-10-media-location-permission)
         * [Usage of the original data](#usage-of-the-original-data)
@@ -84,7 +86,7 @@ see the [migration guide](MIGRATION_GUIDE.md) for detailed info.
   * [Native extra configs](#native-extra-configs)
     * [Android extra configs](#android-extra-configs)
       * [Glide issues](#glide-issues)
-      * [Android 13 (Api 33) extra configs](#android-13-api-33-extra-configs)
+      * [Android 13 (Api 33) extra configs](#android-13--api-33--extra-configs)
     * [iOS extra configs](#ios-extra-configs)
       * [Localized system albums name](#localized-system-albums-name)
     * [Experimental features](#experimental-features)
@@ -265,6 +267,34 @@ final List<AssetPathEntity> paths = await PhotoManager.getAssetPathList();
 
 See [`getAssetPathList`][] for more detail.
 
+#### Params of `getAssetPathList`
+
+| Name             | Description                                                  | Default value           |
+| :--------------- | ------------------------------------------------------------ | ----------------------- |
+| hasAll           | Set to true when you need an album containing all assets.    | true                    |
+| onlyAll          | Use this property if you only need one album containing all assets. | false                   |
+| type             | Type of media resource (video, image, audio)                 | RequestType.common      |
+| filterOption     | Used to filter resource files, see [Filtering](#filtering) for details | FilterOptionGroup()     |
+| pathFilterOption | Only valid for iOS and macOS, for the corresponding album type. See [PMPathFilterOption](#pmpathfilteroption) for more detail. | Include all by default. |
+
+#### PMPathFilterOption
+
+Provide since 2.7.0, currently only valid for iOS and macOS.
+
+```dart
+final List<PMDarwinAssetCollectionType> pathTypeList = []; // use your need type
+final List<PMDarwinAssetCollectionSubtype> pathSubTypeList = []; // use your need type
+final darwinPathFilterOption = PMDarwinPathFilter(
+      type: pathTypeList,
+      subType: pathSubTypeList,
+    );
+PMPathFilter pathFilter = PMPathFilter();
+```
+
+The `PMDarwinAssetCollectionType` has a one-to-one correspondence with [PHAssetCollectionType | Apple Developer Documentation](https://developer.apple.com/documentation/photokit/phassetcollectiontype?language=objc).
+
+The `PMDarwinAssetCollectionSubtype` has a one-to-one correspondence with [PHAssetCollectionSubType | Apple Developer Documentation](https://developer.apple.com/documentation/photokit/phassetcollectionsubtype?language=objc).
+
 ### Get assets (`AssetEntity`)
 
 Assets (images/videos/audios) are abstracted as the [`AssetEntity`][] class.
@@ -274,28 +304,33 @@ and the `PHAsset` object on iOS/macOS.
 #### From `AssetPathEntity`
 
 You can use [the pagination method][`getAssetListPaged`]:
+
 ```dart
 final List<AssetEntity> entities = await path.getAssetListPaged(page: 0, size: 80);
 ```
 
 Or use [the range method][`getAssetListRange`]:
+
 ```dart
 final List<AssetEntity> entities = await path.getAssetListRange(start: 0, end: 80);
 ```
 
 #### From `PhotoManager` (Since 2.6)
 
 First, You need get count of assets:
+
 ```dart
 final int count = await PhotoManager.getAssetCount();
 ```
 
 Then, you can use [the pagination method][`PhotoManager.getAssetListPaged`]:
+
 ```dart
 final List<AssetEntity> entities = await PhotoManager.getAssetListPaged(page: 0, pageCount: 80);
 ```
 
 Or use [the range method][`PhotoManager.getAssetListRange`]:
+
 ```dart
 final List<AssetEntity> entities = await PhotoManager.getAssetListRange(start: 0, end: 80);
 ```
@@ -313,6 +348,7 @@ You can store the ID if you want to implement features
 that's related to persistent selections.
 Use [`AssetEntity.fromId`][] to retrieve the entity
 once you persist an ID.
+
 ```dart
 final AssetEntity? asset = await AssetEntity.fromId(id);
 ```
@@ -327,6 +363,7 @@ You can create an entity from raw data,
 such as downloaded images, recorded videos, etc.
 The created entity will show as a corresponding resource
 on your device's gallery app.
+
 ```dart
 final Uint8List rawData = yourRawData;
 
@@ -380,6 +417,7 @@ when the file is downloading.
 
 The plugin provided the `AssetEntityImage` widget and
 the `AssetEntityImageProvider` to display assets:
+
 ```dart
 final Widget image = AssetEntityImage(
   yourAssetEntity,
@@ -405,6 +443,7 @@ This plugin supports obtain live photos and filtering them:
 ##### Filtering only "Live Photos"
 
 This is supported when filtering only image.
+
 ```dart
 final List<AssetPathEntity> paths = await PhotoManager.getAssetPathList(
   type: RequestType.image,
@@ -509,6 +548,7 @@ PhotoManager.stopChangeNotify();
 
 Filtering assets are also supported by the plugin.
 Below methods have the `filterOption` argument to define the conditions when obtaining assets.
+
 - PhotoManager
   - getAssetPathList (Accessible with `AssetPathEntity.filterOption`)
   - getAssetCount
@@ -520,8 +560,9 @@ Below methods have the `filterOption` argument to define the conditions when obt
   - obtainPathFromProperties (not recommended to use directly)
 
 There are two implementations of filters:
-- [FilterOptionGroup](#FilterOptionGroup)
-- [CustomFilter](#CustomFilter)
+
+- [FilterOptionGroup](#filteroptiongroup)
+- [CustomFilter](#customfilter)
 
 ### FilterOptionGroup
 
@@ -573,6 +614,7 @@ you'll need to use `CustomColumns.base`, `CustomColumns.android` and `CustomColu
 to get the columns name correctly.
 
 An example for how to construct a `CustomFilter`:
+
 ```dart
 CustomFilter createFilter() {
   return CustomFilter.sql(

diff --git a/example/ios/.gitignore b/example/ios/.gitignore
@@ -30,3 +30,4 @@ Runner/GeneratedPluginRegistrant.*
 !default.mode2v3
 !default.pbxuser
 !default.perspectivev3
+.build/
diff --git a/example/lib/model/photo_provider.dart b/example/lib/model/photo_provider.dart
@@ -180,6 +180,7 @@ class PhotoProvider extends ChangeNotifier {
         hasAll: hasAll,
         onlyAll: onlyAll,
         filterOption: option,
+        pathFilterOption: pathFilterOption,
       ),
       prefix: 'Obtain path list duration',
     );
@@ -244,6 +245,38 @@ class PhotoProvider extends ChangeNotifier {
       thumbFormat = ThumbnailFormat.jpeg;
     }
   }
+
+  /// For path filter option
+  var _pathFilterOption = const PMPathFilter();
+  PMPathFilter get pathFilterOption => _pathFilterOption;
+  List<PMDarwinAssetCollectionType> _pathTypeList = PMDarwinAssetCollectionType.values;
+
+  List<PMDarwinAssetCollectionType> get pathTypeList => _pathTypeList;
+
+  set pathTypeList(List<PMDarwinAssetCollectionType> value) {
+    _pathTypeList = value;
+    _onChangePathFilter();
+  }
+
+  late List<PMDarwinAssetCollectionSubtype> _pathSubTypeList = _pathFilterOption.darwin.subType;
+
+  List<PMDarwinAssetCollectionSubtype> get pathSubTypeList => _pathSubTypeList;
+
+  set pathSubTypeList(List<PMDarwinAssetCollectionSubtype> value) {
+    _pathSubTypeList = value;
+    _onChangePathFilter();
+  }
+
+  void _onChangePathFilter() {
+    final darwinPathFilterOption = PMDarwinPathFilter(
+      type: pathTypeList,
+      subType: pathSubTypeList,
+    );
+    _pathFilterOption = PMPathFilter(
+      darwin: darwinPathFilterOption,
+    );
+    notifyListeners();
+  }
 }
 
 class AssetPathProvider extends ChangeNotifier {