feat: Add relativePathAsync getter to AssetPathEntity (#1320)

Add ability to get the relative path of an album/folder through AssetPathEntity.

Changes:
- Add relativePathAsync getter to AssetPathEntity (Dart layer)
- Implement platform channel method getPathRelativePath
- Add Android native implementation:
  - Android 10+ (API 29+): Uses MediaStore RELATIVE_PATH column
  - Android 9- (API 28-): Uses File.parent from DATA column
- iOS/macOS returns null (albums are logical, not physical folders)
- Add test UI in example app to display relative paths

Platform-specific behavior:
- Android: Returns relative path for device folders (e.g., 'DCIM/Camera')
- iOS: Returns null (PHAssetCollection logical albums have no file path)
- Special albums (All, Recent): Returns null on all platforms

---------

Co-authored-by: Alex Li <github@alexv525.com>

Author: toyaji

CHANGELOG.md

@@ -13,6 +13,7 @@ To know more about breaking changes, see the [Migration Guide][].
 - Add `cancelToken` parameter to `AssetEntity.loadFile`.
 - Add `cancelAllRequest` method to `PhotoManager`.
 - The `AssetEntity.getFile` and `AssetEntity.getOriginBytes` methods are public.
+- Add `relativePathAsync` getter to `AssetPathEntity`.
 - Add iOS 18 smart album subtypes support:
   - `smartAlbumSpatial` - For spatial/3D photos
   - `smartAlbumProRes` - For ProRes videos

android/src/main/kotlin/com/fluttercandies/photo_manager/constant/Methods.kt

@@ -71,6 +71,7 @@ class Methods {
         const val getOriginBytes = "getOriginBytes"
         const val getMediaUrl = "getMediaUrl"
         const val fetchEntityProperties = "fetchEntityProperties"
+        const val getPathRelativePath = "getPathRelativePath"
 
         const val getLatLng = "getLatLngAndroidQ"
         const val notify = "notify"

android/src/main/kotlin/com/fluttercandies/photo_manager/core/PhotoManager.kt

@@ -250,6 +250,10 @@ class PhotoManager(private val context: Context) {
         }
     }
 
+    fun getPathRelativePath(galleryId: String): String? {
+        return dbUtils.getPathRelativePath(context, galleryId)
+    }
+
     fun getMediaUri(id: Long, type: Int): String {
         return dbUtils.getMediaUri(context, id, type)
     }

android/src/main/kotlin/com/fluttercandies/photo_manager/core/PhotoManagerPlugin.kt

@@ -458,6 +458,12 @@ class PhotoManagerPlugin(
                 }
             }
 
+            Methods.getPathRelativePath -> {
+                val id = call.argument<String>("id")!!
+                val relativePath = photoManager.getPathRelativePath(id)
+                resultHandler.reply(relativePath)
+            }
+
             Methods.getLatLng -> {
                 val id = call.argument<String>("id")!!
                 // 读取id

android/src/main/kotlin/com/fluttercandies/photo_manager/core/utils/AndroidQDBUtils.kt

@@ -369,7 +369,7 @@ object AndroidQDBUtils : IDBUtils {
         }
 
         val insertUri = MediaStoreUtils.getInsertUri(mediaType)
-        val relativePath = getRelativePath(context, galleryId)
+        val relativePath = getPathRelativePath(context, galleryId)
         val cv = ContentValues().apply {
             for (key in copyKeys) {
                 put(key, cursor.getString(key))
@@ -405,7 +405,7 @@ object AndroidQDBUtils : IDBUtils {
         }
 
         val cr = context.contentResolver
-        val targetPath = getRelativePath(context, galleryId)
+        val targetPath = getPathRelativePath(context, galleryId)
         val contentValues = ContentValues().apply {
             put(RELATIVE_PATH, targetPath)
         }
@@ -483,9 +483,11 @@ object AndroidQDBUtils : IDBUtils {
         return true
     }
 
-    private fun getRelativePath(context: Context, galleryId: String): String? {
-        val cr = context.contentResolver
-        val cursor = cr.logQuery(
+    override fun getPathRelativePath(context: Context, galleryId: String): String? {
+        if (galleryId == PhotoManager.ALL_ID) {
+            return null
+        }
+        val cursor = context.contentResolver.logQuery(
             allUri,
             arrayOf(BUCKET_ID, RELATIVE_PATH),
             "$BUCKET_ID = ?",

android/src/main/kotlin/com/fluttercandies/photo_manager/core/utils/DBUtils.kt

@@ -465,5 +465,27 @@ object DBUtils : IDBUtils {
         }
     }
 
+    override fun getPathRelativePath(context: Context, galleryId: String): String? {
+        if (galleryId == PhotoManager.ALL_ID) {
+            return null
+        }
+        val cursor = context.contentResolver.logQuery(
+            allUri,
+            arrayOf(MediaStore.MediaColumns.DATA),
+            "${MediaStore.MediaColumns.BUCKET_ID} = ?",
+            arrayOf(galleryId),
+            null
+        )
+        cursor.use {
+            if (!it.moveToNext()) {
+                return null
+            }
+            val dataPath = it.getStringOrNull(MediaStore.MediaColumns.DATA)
+            return dataPath?.let { path ->
+                File(path).parent
+            }
+        }
+    }
+
     private data class GalleryInfo(val path: String, val galleryId: String, val galleryName: String)
 }

android/src/main/kotlin/com/fluttercandies/photo_manager/core/utils/IDBUtils.kt

@@ -727,6 +727,8 @@ interface IDBUtils {
         }
     }
 
+    fun getPathRelativePath(context: Context, galleryId: String): String?
+
     fun getPathModifiedDate(context: Context, pathId: String): Long? {
         val columns = arrayOf(DATE_MODIFIED)
         val sortOrder = "$DATE_MODIFIED desc"

example/lib/widget/gallery_item_widget.dart

@@ -81,7 +81,12 @@ class GalleryItemWidget extends StatelessWidget {
                   sb.writeln('assetCount = ${await item.assetCountAsync}');
                   sb.writeln('id = ${item.id}');
 
+                  // Test relativePath
+                  final relativePath = await item.relativePathAsync;
+                  sb.writeln('relativePath = $relativePath');
+
                   print(sb.toString());
+                  showToast('Properties logged to console');
                 },
               ),
             ],
@@ -101,7 +106,31 @@ class GalleryItemWidget extends StatelessWidget {
           future: item.assetCountAsync,
           builder: (_, AsyncSnapshot<int> data) {
             if (data.hasData) {
-              return Text('count : ${data.data}');
+              return Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  Text('count : ${data.data}'),
+                  FutureBuilder<String?>(
+                    future: item.relativePathAsync,
+                    builder: (_, AsyncSnapshot<String?> pathData) {
+                      if (pathData.connectionState == ConnectionState.done) {
+                        final path = pathData.data;
+                        if (path != null) {
+                          return Text(
+                            'path: $path',
+                            style: TextStyle(
+                              fontSize: 12,
+                              color: Colors.grey[600],
+                            ),
+                          );
+                        }
+                      }
+                      return const SizedBox.shrink();
+                    },
+                  ),
+                ],
+              );
             }
             return const SizedBox.shrink();
           },

lib/src/internal/constants.dart

@@ -43,6 +43,7 @@ class PMConstants {
   static const String mGetLatLngAndroidQ = 'getLatLngAndroidQ';
   static const String mGetTitleAsync = 'getTitleAsync';
   static const String mGetMimeTypeAsync = 'getMimeTypeAsync';
+  static const String mGetPathRelativePath = 'getPathRelativePath';
   static const String mGetMediaUrl = 'getMediaUrl';
   static const String mGetSubPath = 'getSubPath';
   static const String mCopyAsset = 'copyAsset';

lib/src/internal/plugin.dart

@@ -684,6 +684,23 @@ class PhotoManagerPlugin with BasePlugin, IosPlugin, AndroidPlugin, OhosPlugin {
     return null;
   }
 
+  Future<String?> getPathRelativePath(AssetPathEntity pathEntity) async {
+    if (Platform.isIOS || Platform.isMacOS) {
+      // iOS/macOS use logical albums (PHAssetCollection) without physical paths
+      return null;
+    }
+    if (Platform.isAndroid) {
+      return _channel.invokeMethod(
+        PMConstants.mGetPathRelativePath,
+        <String, dynamic>{'id': pathEntity.id},
+      );
+    }
+    if (PlatformUtils.isOhos) {
+      return null;
+    }
+    return null;
+  }
+
   Future<int> getAssetCount({
     PMFilter? filterOption,
     RequestType type = RequestType.common,