批量操作在媒体文件管理中的价值

HarmonyOS 开发里，Media Library Kit 的批量操作 API 经常被误解。很多人第一次接触时，会按照单条增删改的思路去处理大量文件，结果发现界面卡顿、操作超时、甚至应用被系统杀死。

这个问题的根源在于：对文件系统进行单条操作时，每次调用都会触发一次完整的事务提交。当文件数量达到几十上百时，这种开销会线性增长，直接拖垮 UI 线程。

Media Library Kit 提供的 executeBatch 方法，正是为了解决这个问题而设计的。它允许将多个操作打包成一个事务统一提交，大幅减少 I/O 次数和事务开销。官方文档提到了这个 API，但没有详细解释实际使用中的性能影响和注意事项。

前置环境

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机

核心实现：从单条到批量

传统方案的问题

先看一个常见的错误写法：

// 不推荐：循环单条删除
async function deleteFilesOneByOne(uris: string[]) {
    for (const uri of uris) {
        try {
            await mediaLibrary.deleteAsset(uri);
            // 每次循环都提交一次事务
        } catch (err) {
            console.error(`删除 ${uri} 失败`, err);
        }
    }
}

这段代码在文件数量少于10个时问题不大。一旦超过50个，你就会发现：

• UI 明显卡顿
• 删除进度时断时续
• 后续操作可能触发 ANR

原因在于：每次 deleteAsset 都会触发一次本地数据库写入，同时还会更新系统的媒体索引。当这些操作密集执行时，I/O 竞争和锁冲突成为主要瓶颈。

使用 executeBatch 优化

executeBatch 的核心思想是：把所有操作打包成一个事务，统一提交。创建、更新、删除三种操作都可以用统一的 BatchRequest 结构描述。

下面实现一个完整的批量删除功能：

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';

async function batchDeleteAssets(context: common.Context, uris: string[]): Promise<boolean> {
    const helper = photoAccessHelper.getPhotoAccessHelper(context);
    
    // 构建批量操作请求
    const fetchFileResult = await helper.getAssets(uris);
    const batchDeleteRequest: Array<photoAccessHelper.BatchRequest> = [];
    
    for (let i = 0; i < fetchFileResult.getCount(); i++) {
        const asset = await fetchFileResult.getObjectByIndex(i);
        batchDeleteRequest.push({
            operation: photoAccessHelper.OperationType.DELETE,
            uri: asset.uri
        });
    }
    
    // 执行批量操作
    try {
        const results = await helper.executeBatch(batchDeleteRequest);
        // 检查每个操作的结果
        for (let i = 0; i < results.length; i++) {
            if (results[i].result !== photoAccessHelper.ResultType.SUCCESS) {
                console.warn(`删除失败: ${results[i].uri}, 错误码: ${results[i].errorCode}`);
            }
        }
        return true;
    } catch (err) {
        console.error('批量删除失败', err);
        return false;
    }
}

关键点：

• executeBatch 返回的结果数组与请求数组一一对应，便于逐项确认
• 整个操作在系统层面被优化为单次事务提交
• 不会阻塞 UI 线程，因为 executeBatch 本身就是异步 API

带进度显示的批量操作

实际项目中，用户通常需要看到操作进度。这里用 @State 管理进度状态：

@Entry
@Component
struct BatchOperationDemo {
    @State fileList: Array<photoAccessHelper.PhotoAsset> = [];
    @State progress: number = 0;
    @State isOperating: boolean = false;
    
    async startBatchDelete() {
        if (this.fileList.length === 0) return;
        
        this.isOperating = true;
        this.progress = 0;
        
        const uris = this.fileList.map(item => item.uri);
        const batchSize = 20; // 分批处理，适合用户反馈
        
        // 同样可以用 executeBatch 分批提交
        // 这里拆分为多个批次，便于中间显示进度
        for (let i = 0; i < uris.length; i += batchSize) {
            const batch = uris.slice(i, i + batchSize);
            await batchDeleteAssets(getContext(this), batch);
            
            // 更新进度
            this.progress = Math.min(100, Math.round((i + batch.length) / uris.length * 100));
            // 注意：这里是在异步函数中更新状态，ArkUI 会正确处理
        }
        
        this.fileList = [];
        this.isOperating = false;
        this.progress = 100;
    }
    
    build() {
        Column() {
            List() {
                ForEach(this.fileList, (item: photoAccessHelper.PhotoAsset) => {
                    ListItem() {
                        Text(item.uri)
                    }
                })
            }
            .height('70%')
            
            if (this.isOperating) {
                // 进度条
                Row() {
                    Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
                        .width('80%')
                    Text(`${this.progress}%`)
                        .width('20%')
                }
                .padding(10)
            }
            
            Button('批量删除')
                .onClick(() => this.startBatchDelete())
                .enabled(!this.isOperating && this.fileList.length > 0)
        }
        .padding(10)
    }
}

这里需要注意：虽然 executeBatch 支持超大批次提交，但考虑到用户体验，建议将操作拆分为每批20-50个文件，并在每批完成后更新 UI 状态。这样既发挥了批量操作的性能优势，又避免了用户长时间无反馈。

常见问题与解决方案

问题1：大数量提交时出现“死锁”或超时

现象：当一次提交的文件数超过500个时，executeBatch 抛出超时异常，甚至导致应用无响应。

原因：系统底层对每个事务有资源限制，一次提交过多操作会触发文件系统层面的锁机制。不同设备能力差异很大，低端机可能100个操作就会出现问题。

解决方案：拆分为合适大小的批次。推荐值：

设备类型	推荐单次批量大小
高端旗舰	100-200
中端机型	50-100
低端或旧设备	20-50

实际项目中，可以根据设备等级动态调整：

class BatchSizeManager {
    static getBatchSize(): number {
        // 可以通过获取设备 RAM 等方式动态调整
        // 这里简单返回一个固定值
        return 50;
    }
}

问题2：进度回调中更新 UI 导致状态混乱

现象：在 executeBatch 的回调或循环中直接修改 @State 变量，有时页面组件不刷新，或刷新频率异常。

原因：ArkUI 的状态管理对频繁的状态更新有限制，如果在短时间内（如10ms内）多次修改一个 @State 属性，ArkUI 可能会合并更新，导致进度显示跳跃异常。

解决方案：使用 async 函数配合合理的更新粒度，而不是在回调中频繁更新。上面的代码中，只会在每批操作完成后更新进度，而不是每个文件完成后，这就是合理的做法。

最佳实践总结

1. 使用 executeBatch 而非循环单条操作：性能提升幅度随数量增加而增大，文件数越多，效果越明显。

2. 控制单次批量大小在50-100个操作之间：这个范围在大多数设备上能同时保证性能和安全。过小失去批量优势，过大增加超时风险。

3. 不要在 executeBatch 回调中直接修改 @State：异步回调里修改状态虽然被允许，但过于密集的修改会导致 UI 更新异常。正确的做法是在分批处更新状态。

4. 始终处理部分失败场景：executeBatch 返回的结果数组可以逐项检查。不要假设要么全成功要么全失败，实际开发中经常出现部分文件被其他应用占用导致删除失败的情况。

5. 批量操作前检查权限：特别是批量删除和修改，如果中途遇到权限拒绝，会导致整体事务回滚。建议操作前统一申请 ohos.permission.READ_MEDIA 和 ohos.permission.WRITE_MEDIA。

FAQ

Q：为什么批量更新比批量删除性能差距明显？

A：更新操作需要修改文件元数据，涉及更多的 I/O 操作。删除操作如果是标记删除（软删除），则只需要修改一个状态位。实际项目中，批量更新建议将单次提交数量减半。

Q：真机测试时 executeBatch 正常，但某些设备上报“权限不足”，为什么？

A：不同设备的 SELinux 策略略有差异。特别是在 HarmonyOS NEXT 上，部分系统级目录的写入权限受限于文件的实际归属。建议操作前确认所有文件对当前应用来说是可写的。

Q：批量操作完成后，UI 列表没有实时更新，如何处理？

A：Media Library Kit 的变更不会主动通知 UI 层。建议在批量操作完成后，重新调用 getAssets 获取最新列表并刷新 @State。也可以注册 photoAccessHelper.AlbumChangeEvent 监听变化，但需要手动触发刷新。