feat: Add includeHiddenAssets option (#1288)

CaiJingLong · AlexV525 · web-flow · commit ef3f748d6745 · 2025-05-15T14:40:41.000+08:00
Signed-off-by: Caijinglong &lt;cjl_spy@163.com&gt;
Co-authored-by: Alex Li &lt;github@alexv525.com&gt;
diff --git a/example/lib/model/photo_provider.dart b/example/lib/model/photo_provider.dart
@@ -57,6 +57,15 @@ class PhotoProvider extends ChangeNotifier {
     notifyListeners();
   }
 
+  bool _includeHiddenAssets = false;
+
+  bool get includeHiddenAssets => _includeHiddenAssets;
+
+  set includeHiddenAssets(bool value) {
+    _includeHiddenAssets = value;
+    notifyListeners();
+  }
+
   DateTime _startDt = DateTime(2005); // Default Before 8 years
 
   DateTime get startDt => _startDt;
@@ -168,6 +177,13 @@ class PhotoProvider extends ChangeNotifier {
     containsPathModified = value;
   }
 
+  void changeIncludeHiddenAssets(bool? value) {
+    if (value == null) {
+      return;
+    }
+    includeHiddenAssets = value;
+  }
+
   void reset() {
     list.clear();
   }
@@ -191,13 +207,13 @@ class PhotoProvider extends ChangeNotifier {
   }
 
   FilterOptionGroup makeOption() {
-    final FilterOption option = FilterOption(
+    final FilterOption filterOption = FilterOption(
       sizeConstraint: SizeConstraint(
         minWidth: int.tryParse(minWidth) ?? 0,
         maxWidth: int.tryParse(maxWidth) ?? 100000,
         minHeight: int.tryParse(minHeight) ?? 0,
         maxHeight: int.tryParse(maxHeight) ?? 100000,
-        ignoreSize: ignoreSize,
+        ignoreSize: _ignoreSize,
       ),
       durationConstraint: DurationConstraint(
         min: minDuration,
@@ -211,15 +227,19 @@ class PhotoProvider extends ChangeNotifier {
       max: endDt,
     );
 
-    return FilterOptionGroup()
-      ..setOption(AssetType.video, option)
-      ..setOption(AssetType.image, option)
-      ..setOption(AssetType.audio, option)
-      ..createTimeCond = createDtCond
-      ..containsPathModified = _containsPathModified
+    final FilterOptionGroup optionGroup = FilterOptionGroup(
+      imageOption: filterOption,
+      videoOption: filterOption,
+      audioOption: filterOption,
+      containsPathModified: containsPathModified,
       // ignore: deprecated_member_use
-      ..containsLivePhotos = _containsLivePhotos
-      ..onlyLivePhotos = onlyLivePhotos;
+      containsLivePhotos: containsLivePhotos,
+      onlyLivePhotos: onlyLivePhotos,
+      createTimeCond: createDtCond,
+      includeHiddenAssets: includeHiddenAssets, // iOS 平台特有
+    );
+
+    return optionGroup;
   }
 
   Future<void> refreshAllGalleryProperties() async {
diff --git a/example/lib/page/custom_filter/include_hidden_test_page.dart b/example/lib/page/custom_filter/include_hidden_test_page.dart
@@ -0,0 +1,54 @@
+import 'package:flutter/material.dart';
+import 'package:photo_manager/photo_manager.dart';
+
+class IncludeHiddenTestPage extends StatefulWidget {
+  const IncludeHiddenTestPage({super.key});
+
+  @override
+  State<IncludeHiddenTestPage> createState() => _IncludeHiddenTestPageState();
+}
+
+class _IncludeHiddenTestPageState extends State<IncludeHiddenTestPage> {
+  final List<String> _logs = [];
+
+  Future<void> _test() async {
+    final option = CustomFilter.sql(where: '');
+    final count = await PhotoManager.getAssetCount(filterOption: option);
+
+    setState(() {
+      _logs.add('Not include hidden count: $count');
+    });
+
+    final option2 = CustomFilter.sql(where: '');
+    option2.includeHiddenAssets = true;
+    final count2 = await PhotoManager.getAssetCount(filterOption: option2);
+
+    setState(() {
+      _logs.add('Include hidden count: $count2');
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Include Hidden Test'),
+      ),
+      body: Column(
+        children: [
+          ElevatedButton(
+            onPressed: _test,
+            child: const Text('Test the count of hidden and not hidden'),
+          ),
+          Expanded(
+            child: ListView(
+              children: [
+                ..._logs.reversed.map((e) => ListTile(title: Text(e))),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
diff --git a/example/lib/page/custom_filter_example_page.dart b/example/lib/page/custom_filter_example_page.dart
@@ -1,3 +1,5 @@
+import 'dart:io';
+
 import 'package:flutter/material.dart';
 import 'package:photo_manager/photo_manager.dart';
 import 'package:photo_manager_example/page/custom_filter/path_list.dart';
@@ -6,6 +8,7 @@ import 'custom_filter/advance_filter_page.dart';
 import 'custom_filter/custom_filter_sql_gif_image.dart';
 import 'custom_filter/custom_filter_sql_page.dart';
 import 'custom_filter/filter_assets_page.dart';
+import 'custom_filter/include_hidden_test_page.dart';
 
 class CustomFilterExamplePage extends StatelessWidget {
   const CustomFilterExamplePage({super.key});
@@ -69,6 +72,11 @@ class CustomFilterExamplePage extends StatelessWidget {
                 },
               ),
             ),
+            if (Platform.isIOS || Platform.isMacOS)
+              buildItem(
+                'Include hidden test',
+                const IncludeHiddenTestPage(),
+              ),
           ],
         ),
       ),
diff --git a/example/lib/page/filter_option_page.dart b/example/lib/page/filter_option_page.dart
@@ -34,6 +34,7 @@ class _FilterOptionPageState extends State<FilterOptionPage> {
           }),
           buildIgnoreSize(provider),
           buildNeedTitleCheck(provider),
+          buildIncludeHiddenAssetsCheck(provider),
           buildDurationWidget(
             provider,
             'minDuration',
@@ -204,6 +205,27 @@ class _FilterOptionPageState extends State<FilterOptionPage> {
       },
     );
   }
+
+  /// 构建包含隐藏资源的复选框
+  ///
+  /// 此选项仅在 iOS 平台上有效
+  Widget buildIncludeHiddenAssetsCheck(PhotoProvider provider) {
+    return AnimatedBuilder(
+      animation: provider,
+      builder: (BuildContext context, Widget? snapshot) {
+        return CheckboxListTile(
+          title: const Text('Include hidden assets (iOS only)'),
+          subtitle: const Text('包含隐藏的资源（仅 iOS 平台有效）'),
+          onChanged: (bool? value) {
+            if (value != null) {
+              provider.includeHiddenAssets = value;
+            }
+          },
+          value: provider.includeHiddenAssets,
+        );
+      },
+    );
+  }
 }
 
 class DarwinPathFilterPage extends StatefulWidget {
diff --git a/example/lib/page/home_page.dart b/example/lib/page/home_page.dart
@@ -64,6 +64,8 @@ class _NewHomePageState extends State<NewHomePage> {
             _buildContainsLivePhotos(),
             _buildOnlyLivePhotos(),
             _buildPathContainsModifiedDateCheck(),
+            if (Platform.isIOS || Platform.isMacOS)
+              _buildIncludeHiddenAssetsCheck(),
             _buildPngCheck(),
             _buildNotifyCheck(),
             _buildFilterOption(watchProvider),
@@ -210,7 +212,17 @@ class _NewHomePageState extends State<NewHomePage> {
       onChanged: (bool? value) {
         readProvider.changeContainsPathModified(value);
       },
-      title: const Text('contains path modified date'),
+      title: const Text('Contains path modified date'),
+    );
+  }
+
+  Widget _buildIncludeHiddenAssetsCheck() {
+    return CheckboxListTile(
+      value: watchProvider.includeHiddenAssets,
+      onChanged: (bool? value) {
+        readProvider.changeIncludeHiddenAssets(value);
+      },
+      title: const Text('Include hidden assets'),
     );
   }
 
diff --git a/ios/Classes/core/PMConvertUtils.m b/ios/Classes/core/PMConvertUtils.m
@@ -133,6 +133,7 @@ + (NSDictionary *)convertPMAssetToMap:(PMAssetEntity *)asset
         container.containsModified = [map[@"containsPathModified"] boolValue];
         container.containsLivePhotos = [map[@"containsLivePhotos"] boolValue];
         container.onlyLivePhotos = [map[@"onlyLivePhotos"] boolValue];
+        container.includeHiddenAssets = [map[@"includeHiddenAssets"] boolValue];
         
         NSArray *sortArray = map[@"orders"];
         [container injectSortArray:sortArray];
diff --git a/ios/Classes/core/PMFilterOption.h b/ios/Classes/core/PMFilterOption.h
@@ -58,6 +58,7 @@ typedef struct PMDurationConstraint {
 @property(nonatomic, assign) BOOL containsLivePhotos;
 @property(nonatomic, assign) BOOL onlyLivePhotos;
 @property(nonatomic, assign) BOOL containsModified;
+@property(nonatomic, assign) BOOL includeHiddenAssets;
 @property(nonatomic, strong) NSArray<NSSortDescriptor *> *sortArray;
 
 - (NSArray<NSSortDescriptor *> *)sortCond;
diff --git a/ios/Classes/core/PMFilterOption.m b/ios/Classes/core/PMFilterOption.m
@@ -52,6 +52,9 @@ - (PHFetchOptions *)getFetchOptions:(int)type {
 
     PHFetchOptions *options = [PHFetchOptions new];
     options.sortDescriptors = [optionGroup sortCond];
+    
+    // 获取 includeHiddenAssets 属性
+    options.includeHiddenAssets = optionGroup.includeHiddenAssets;
 
     NSMutableString *cond = [NSMutableString new];
     NSMutableArray *args = [NSMutableArray new];
@@ -255,6 +258,9 @@ - (NSString *)where {
 
 - (PHFetchOptions *)getFetchOptions:(int)type {
     PHFetchOptions *options = [PHFetchOptions new];
+    
+    // 从 params 中获取 includeHiddenAssets 属性
+    options.includeHiddenAssets = self.params[@"includeHiddenAssets"] ? [self.params[@"includeHiddenAssets"] boolValue] : NO;
 
     BOOL containsImage = [PMRequestTypeUtils containsImage:type];
     BOOL containsVideo = [PMRequestTypeUtils containsVideo:type];
diff --git a/lib/src/filter/base_filter.dart b/lib/src/filter/base_filter.dart
@@ -38,6 +38,7 @@ abstract class PMFilter {
   /// Construct a default filter.
   factory PMFilter.defaultValue({
     bool containsPathModified = false,
+    bool includeHiddenAssets = false,
   }) {
     return CustomFilter.sql(
       where: '',
@@ -58,6 +59,17 @@ abstract class PMFilter {
   ///  * [AssetPathEntity.lastModified].
   bool containsPathModified = false;
 
+  /// Whether to include hidden assets in the results.
+  ///
+  /// This option only takes effect on iOS.
+  /// Beginning with iOS 16, users can require authentication to view the
+  /// hidden album, and the user setting is true by default. When true,
+  /// the system doesn’t return hidden assets even if the option is true.
+  ///
+  /// See also:
+  ///  * [PHFetchOptions.includeHiddenAssets](https://developer.apple.com/documentation/photos/phfetchoptions/includehiddenassets).
+  bool includeHiddenAssets = false;
+
   /// The type of the filter.
   BaseFilterType get type;
 
@@ -83,6 +95,7 @@ abstract class PMFilter {
   Map<String, dynamic> _paramMap() {
     return <String, dynamic>{
       'containsPathModified': containsPathModified,
+      'includeHiddenAssets': includeHiddenAssets,
     };
   }
 }
diff --git a/lib/src/filter/classical/filter_option_group.dart b/lib/src/filter/classical/filter_option_group.dart
@@ -47,8 +47,10 @@ class FilterOptionGroup extends PMFilter {
     DateTimeCond? createTimeCond,
     DateTimeCond? updateTimeCond,
     List<OrderOption> orders = const <OrderOption>[],
+    bool includeHiddenAssets = false,
   }) {
     super.containsPathModified = containsPathModified;
+    super.includeHiddenAssets = includeHiddenAssets;
     _map[AssetType.image] = imageOption;
     _map[AssetType.video] = videoOption;
     _map[AssetType.audio] = audioOption;
@@ -140,6 +142,7 @@ class FilterOptionGroup extends PMFilter {
     }
     containsPathModified = other.containsPathModified;
     containsLivePhotos = other.containsLivePhotos;
+    includeHiddenAssets = other.includeHiddenAssets;
     onlyLivePhotos = other.onlyLivePhotos;
     createTimeCond = other.createTimeCond;
     updateTimeCond = other.updateTimeCond;
@@ -197,6 +200,7 @@ class FilterOptionGroup extends PMFilter {
     FilterOption? videoOption,
     FilterOption? audioOption,
     bool? containsPathModified,
+    bool? includeHiddenAssets,
     @Deprecated(
       'The option will be enabled by default. '
       'This will be removed in v4.0.0',
@@ -216,12 +220,14 @@ class FilterOptionGroup extends PMFilter {
     createTimeCond ??= this.createTimeCond;
     updateTimeCond ??= this.updateTimeCond;
     orders ??= this.orders;
+    includeHiddenAssets ??= this.includeHiddenAssets;
 
     final FilterOptionGroup result = FilterOptionGroup()
       ..setOption(AssetType.image, imageOption!)
       ..setOption(AssetType.video, videoOption!)
       ..setOption(AssetType.audio, audioOption!)
       ..containsPathModified = containsPathModified
+      ..includeHiddenAssets = includeHiddenAssets
       ..containsLivePhotos = containsLivePhotos
       ..onlyLivePhotos = onlyLivePhotos
       ..createTimeCond = createTimeCond
