feat: Android 11+ batch move assets (#1319)

This pull request introduces a new batch move feature for Android 11+ (API 30+) in the photo manager plugin, allowing multiple assets to be moved to a different album with a single user permission dialog. The implementation includes both platform-side (Kotlin) and Dart-side changes, as well as an example usage for developers. The main areas of change are the addition of the batch move API, integration of the new manager, and updates to the example app.

**Batch Move Feature Implementation**

* Added new method `moveAssetsToPath` to support batch moving of assets to a target album/folder, which triggers only one system permission dialog for all selected assets.
[[1]](diffhunk://#diff-8c2e6037bac8f1d70b0e894c4dce0779ac080ba908d9e6fc6310aab8feea23c6R86)
[[2]](diffhunk://#diff-879a3e732a2f4305e1600272748b44c9fb104d335d2fe538a7a3c9536921e6c0R558-R583)
* Introduced `PhotoManagerWriteManager` class in `PhotoManagerWriteManager.kt` to handle write requests and batch move operations, including permission handling and actual asset relocation logic.

**Plugin Integration**

* Registered `writeManager` as an `ActivityResultListener` in the plugin lifecycle, ensuring proper permission and result handling for batch move operations.
[[1]](diffhunk://#diff-cea18dace7ce6804f7272079a1bd5f66c4920f364df7c6c614dae4684d758c60R87)
[[2]](diffhunk://#diff-cea18dace7ce6804f7272079a1bd5f66c4920f364df7c6c614dae4684d758c60R97)
[[3]](diffhunk://#diff-879a3e732a2f4305e1600272748b44c9fb104d335d2fe538a7a3c9536921e6c0R61-R67)
* Updated activity binding logic to include `writeManager` for context and activity reference management.

**Example and Documentation**

* Added `move_assets_example.dart` with clear documentation and sample code demonstrating how to use the new batch move API, including important notes on Android version requirements, path formats, and error handling.
* Updated example app navigation to include the new "Move Assets example" page for easier developer access and testing.
[[1]](diffhunk://#diff-0502524377b0a7e252905c71e9e595b4b5d3ff4732ae81494b4bdcc787c17a76R8)
[[2]](diffhunk://#diff-0502524377b0a7e252905c71e9e595b4b5d3ff4732ae81494b4bdcc787c17a76R32)

---------

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

Author: toyaji

CHANGELOG.md

@@ -25,6 +25,7 @@ To know more about breaking changes, see the [Migration Guide][].
 - Add optional `latitude`, `longitude`, and `creationDate` parameters to `saveImage`, `saveImageWithPath`, and `saveVideo` methods.
   - On iOS: Sets location and creation date metadata for saved assets.
   - On Android Q+: Sets DATE_TAKEN field and location metadata for saved assets.
+- Add batch asset move functionality using `createWriteRequest` API for Android 11+.
 
 ### Improvements
 

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

@@ -84,6 +84,7 @@ class PhotoManagerPlugin : FlutterPlugin, ActivityAware {
         binding.addRequestPermissionsResultListener(listener)
         plugin?.let {
             binding.addActivityResultListener(it.deleteManager)
+            binding.addActivityResultListener(it.writeManager)
             binding.addActivityResultListener(it.favoriteManager)
         }
     }
@@ -94,6 +95,7 @@ class PhotoManagerPlugin : FlutterPlugin, ActivityAware {
         }
         plugin?.let { p ->
             oldBinding.removeActivityResultListener(p.deleteManager)
+            oldBinding.removeActivityResultListener(p.writeManager)
             oldBinding.removeActivityResultListener(p.favoriteManager)
         }
     }

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

@@ -85,6 +85,7 @@ class Methods {
         const val favoriteAsset = "favoriteAsset"
         const val copyAsset = "copyAsset"
         const val moveAssetToPath = "moveAssetToPath"
+        const val moveAssetsToPath = "moveAssetsToPath"
         const val removeNoExistsAssets = "removeNoExistsAssets"
         const val getColumnNames = "getColumnNames"
 

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

@@ -58,12 +58,14 @@ class PhotoManagerPlugin(
     }
 
     val deleteManager = PhotoManagerDeleteManager(applicationContext, activity)
+    val writeManager = PhotoManagerWriteManager(applicationContext, activity)
     val favoriteManager = PhotoManagerFavoriteManager(applicationContext)
 
     fun bindActivity(activity: Activity?) {
         this.activity = activity
         permissionsUtils.withActivity(activity)
         deleteManager.bindActivity(activity)
+        writeManager.bindActivity(activity)
         favoriteManager.bindActivity(activity)
     }
 
@@ -590,6 +592,32 @@ class PhotoManagerPlugin(
                 photoManager.moveToGallery(assetId, albumId, resultHandler)
             }
 
+            Methods.moveAssetsToPath -> {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                    try {
+                        val assetIds = call.argument<List<String>>("assetIds")!!
+                        val targetPath = call.argument<String>("targetPath")!!
+                        
+                        val uris = assetIds.mapNotNull { photoManager.getUri(it) }
+                        if (uris.isEmpty()) {
+                            resultHandler.replyError("No valid URIs found for the given asset IDs")
+                            return
+                        }
+                        
+                        writeManager.moveToPathWithPermission(uris, targetPath, resultHandler)
+                    } catch (e: Exception) {
+                        LogUtils.error("moveAssetsToPath failed", e)
+                        resultHandler.replyError("moveAssetsToPath failed", message = e.message)
+                    }
+                } else {
+                    LogUtils.error("moveAssetsToPath requires Android 11+ (API 30+)")
+                    resultHandler.replyError(
+                        "moveAssetsToPath requires Android 11+ (API 30+)",
+                        message = "Current API level: ${Build.VERSION.SDK_INT}"
+                    )
+                }
+            }
+
             Methods.deleteWithIds -> {
                 try {
                     val ids = call.argument<List<String>>("ids")!!

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

@@ -0,0 +1,191 @@
+package com.fluttercandies.photo_manager.core
+
+import android.app.Activity
+import android.content.ContentResolver
+import android.content.ContentValues
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.provider.MediaStore
+import androidx.annotation.RequiresApi
+import com.fluttercandies.photo_manager.util.LogUtils
+import com.fluttercandies.photo_manager.util.ResultHandler
+import io.flutter.plugin.common.PluginRegistry
+
+/**
+ * Manager for handling write requests (modifications) on Android 11+ (API 30+)
+ * Uses MediaStore.createWriteRequest() to request user permission for batch modifications
+ */
+class PhotoManagerWriteManager(val context: Context, private var activity: Activity?) :
+    PluginRegistry.ActivityResultListener {
+
+    fun bindActivity(activity: Activity?) {
+        this.activity = activity
+    }
+
+    private var androidRWriteRequestCode = 40071
+    private var writeHandler: ResultHandler? = null
+    private var pendingOperation: WriteOperation? = null
+
+    private val cr: ContentResolver
+        get() = context.contentResolver
+
+    /**
+     * Represents a pending write operation that will be executed after user grants permission
+     */
+    private data class WriteOperation(
+        val uris: List<Uri>,
+        val targetPath: String,
+        val operationType: OperationType
+    )
+
+    enum class OperationType {
+        MOVE,       // Move files to another folder
+        UPDATE      // Generic update operation
+    }
+
+    override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?): Boolean {
+        if (requestCode == androidRWriteRequestCode) {
+            handleWriteResult(resultCode)
+            return true
+        }
+        return false
+    }
+
+    private fun handleWriteResult(resultCode: Int) {
+        if (resultCode == Activity.RESULT_OK) {
+            // User granted permission, execute the pending operation
+            val operation = pendingOperation
+            if (operation != null) {
+                val success = when (operation.operationType) {
+                    OperationType.MOVE -> performMove(operation.uris, operation.targetPath)
+                    OperationType.UPDATE -> performUpdate(operation.uris, operation.targetPath)
+                }
+                writeHandler?.reply(success)
+            } else {
+                LogUtils.error("No pending operation found after write permission granted")
+                writeHandler?.reply(false)
+            }
+        } else {
+            // User denied permission
+            LogUtils.info("User denied write permission")
+            writeHandler?.reply(false)
+        }
+        
+        // Clean up
+        pendingOperation = null
+        writeHandler = null
+    }
+
+    /**
+     * Request permission to move assets to a different album/folder on Android 11+ (API 30+)
+     * 
+     * @param uris List of content URIs to move
+     * @param targetPath Target RELATIVE_PATH (e.g., "Pictures/MyAlbum")
+     * @param resultHandler Callback with result (true if successful, false otherwise)
+     */
+    @RequiresApi(Build.VERSION_CODES.R)
+    fun moveToPathWithPermission(uris: List<Uri>, targetPath: String, resultHandler: ResultHandler) {
+        if (activity == null) {
+            LogUtils.error("Activity is null, cannot request write permission")
+            resultHandler.reply(false)
+            return
+        }
+
+        this.writeHandler = resultHandler
+        this.pendingOperation = WriteOperation(uris, targetPath, OperationType.MOVE)
+
+        try {
+            val pendingIntent = MediaStore.createWriteRequest(cr, uris)
+            activity?.startIntentSenderForResult(
+                pendingIntent.intentSender,
+                androidRWriteRequestCode,
+                null,
+                0,
+                0,
+                0
+            )
+        } catch (e: Exception) {
+            LogUtils.error("Failed to create write request", e)
+            resultHandler.reply(false)
+            pendingOperation = null
+            writeHandler = null
+        }
+    }
+
+    /**
+     * Perform the actual move operation after permission is granted
+     * Updates the RELATIVE_PATH of each URI to move files to a different folder
+     */
+    private fun performMove(uris: List<Uri>, targetPath: String): Boolean {
+        return try {
+            val values = ContentValues().apply {
+                put(MediaStore.MediaColumns.RELATIVE_PATH, targetPath)
+            }
+
+            var successCount = 0
+            for (uri in uris) {
+                try {
+                    val updated = cr.update(uri, values, null, null)
+                    if (updated > 0) {
+                        successCount++
+                    }
+                } catch (e: Exception) {
+                    LogUtils.error("Failed to move URI: $uri", e)
+                }
+            }
+
+            LogUtils.info("Moved $successCount/${uris.size} files to $targetPath")
+            successCount > 0  // Return true if at least one file was moved
+        } catch (e: Exception) {
+            LogUtils.error("Failed to perform move operation", e)
+            false
+        }
+    }
+
+    /**
+     * Perform a generic update operation after permission is granted
+     * This can be extended for other types of modifications
+     */
+    private fun performUpdate(uris: List<Uri>, updateData: String): Boolean {
+        // Placeholder for generic update operations
+        // Can be extended based on specific needs
+        LogUtils.info("Generic update operation not yet implemented")
+        return false
+    }
+
+    /**
+     * Request permission to update/modify assets on Android 11+ (API 30+)
+     * This is a generic method that can be used for various update operations
+     * 
+     * @param uris List of content URIs to update
+     * @param resultHandler Callback with result (true if permission granted, false otherwise)
+     */
+    @RequiresApi(Build.VERSION_CODES.R)
+    fun requestWritePermission(uris: List<Uri>, resultHandler: ResultHandler) {
+        if (activity == null) {
+            LogUtils.error("Activity is null, cannot request write permission")
+            resultHandler.reply(false)
+            return
+        }
+
+        this.writeHandler = resultHandler
+
+        try {
+            val pendingIntent = MediaStore.createWriteRequest(cr, uris)
+            activity?.startIntentSenderForResult(
+                pendingIntent.intentSender,
+                androidRWriteRequestCode,
+                null,
+                0,
+                0,
+                0
+            )
+        } catch (e: Exception) {
+            LogUtils.error("Failed to create write request", e)
+            resultHandler.reply(false)
+            writeHandler = null
+        }
+    }
+}

example/lib/page/index_page.dart

@@ -5,6 +5,7 @@ import 'package:photo_manager_example/widget/nav_button.dart';
 import 'change_notify_page.dart';
 import 'developer/develop_index_page.dart';
 import 'home_page.dart';
+import 'move_assets_page.dart';
 import 'save_image_example.dart';
 
 class IndexPage extends StatefulWidget {
@@ -28,6 +29,7 @@ class _IndexPageState extends State<IndexPage> {
           routePage('Custom filter example', const CustomFilterExamplePage()),
           routePage('Save media example', const SaveMediaExample()),
           routePage('Change notify example', const ChangeNotifyExample()),
+          routePage('Move Assets example', const MoveAssetsBatchTestPage()),
           routePage('For Developer page', const DeveloperIndexPage()),
         ],
       ),