一、原理解析

鸿蒙 6 沙箱目录的文件操作依赖@ohos.file.fs模块，核心特点：

1. 沙箱目录（filesDir/cacheDir）为应用私有，无需额外权限，操作更安全；
2. 大文件操作需在TaskPool（非 UI 线程）执行，避免阻塞 UI；
3. 进度监听需通过fs.createStream创建读写流，分段处理文件并计算进度。

二、完整实现代码

1. 工具类封装（文件操作 + 进度监听）

import fs from '@ohos.file.fs';
import taskpool from '@ohos.taskpool';
import common from '@ohos.app.ability.common';
import { BusinessError } from '@ohos.base';

// 文件操作进度回调类型
type ProgressCallback = (progress: number) => void; // progress：0~100

export class SandboxFileUtil {
  private context: common.UIAbilityContext;

  constructor(context: common.UIAbilityContext) {
    this.context = context;
  }

  // 1. 复制文件（带进度监听）
  async copyFileWithProgress(
    srcPath: string, // 源文件路径（沙箱内）
    destPath: string, // 目标路径（沙箱内）
    progressCallback?: ProgressCallback
  ): Promise<boolean> {
    try {
      // 检查源文件是否存在
      if (!await fs.access(srcPath)) throw new Error('源文件不存在');

      // 获取文件大小（用于计算进度）
      const fileStats = await fs.stat(srcPath);
      const fileSize = fileStats.size;
      if (fileSize === 0) {
        await fs.copyFile(srcPath, destPath);
        progressCallback?.(100);
        return true;
      }

      // 提交到TaskPool执行（非UI线程）
      const result = await taskpool.execute(
        this.doCopyFile,
        srcPath,
        destPath,
        fileSize,
        progressCallback
      );
      return result;
    } catch (err) {
      console.error(`复制文件失败：${(err as BusinessError).message}`);
      return false;
    }
  }

  // 2. 移动文件（本质：复制+删除源文件）
  async moveFileWithProgress(
    srcPath: string,
    destPath: string,
    progressCallback?: ProgressCallback
  ): Promise<boolean> {
    const copySuccess = await this.copyFileWithProgress(srcPath, destPath, progressCallback);
    if (copySuccess) {
      await this.deleteFile(srcPath);
      return true;
    }
    return false;
  }

  // 3. 删除文件（支持文件/目录）
  async deleteFile(path: string): Promise<boolean> {
    try {
      const stats = await fs.stat(path);
      if (stats.isDirectory()) {
        // 删除目录（递归删除子文件）
        await fs.rmdir(path, { recursive: true });
      } else {
        // 删除文件
        await fs.unlink(path);
      }
      return true;
    } catch (err) {
      console.error(`删除文件失败：${(err as BusinessError).message}`);
      return false;
    }
  }

  // TaskPool执行的复制逻辑（需@Concurrent装饰器）
  @Concurrent
  private async doCopyFile(
    srcPath: string,
    destPath: string,
    fileSize: number,
    progressCallback?: ProgressCallback
  ): Promise<boolean> {
    const readStream = fs.createStream(srcPath, 'r');
    const writeStream = fs.createStream(destPath, 'w');
    let processedSize = 0;

    try {
      // 分段读取文件
      for await (const chunk of readStream) {
        await writeStream.write(chunk);
        processedSize += chunk.byteLength;
        // 计算进度（0~100）
        const progress = Math.round((processedSize / fileSize) * 100);
        progressCallback?.(progress);
      }
      await writeStream.close();
      await readStream.close();
      return true;
    } catch (err) {
      // 失败时删除目标文件
      if (await fs.access(destPath)) {
        await fs.unlink(destPath);
      }
      console.error(`TaskPool复制失败：${(err as BusinessError).message}`);
      return false;
    }
  }
}

2. 组件中使用示例

import { SandboxFileUtil } from '../utils/SandboxFileUtil';
import router from '@ohos.router';

@Entry
@Component
struct FileOperationDemo {
  private context = getContext(this) as common.UIAbilityContext;
  private fileUtil = new SandboxFileUtil(this.context);
  @State copyProgress: number = 0; // 复制进度
  @State isCopying: boolean = false;

  build() {
    Column({ space: 20 }) {
      Text('沙箱文件操作示例')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      Progress({
        value: this.copyProgress,
        total: 100,
        type: ProgressType.Linear
      })
        .width('80%')
        .text(`${this.copyProgress}%`)

      Button('复制大文件')
        .onClick(async () => {
          if (this.isCopying) return;
          this.isCopying = true;
          this.copyProgress = 0;

          // 源文件路径（沙箱filesDir下的test.zip）
          const srcPath = `${this.context.filesDir}/test.zip`;
          // 目标文件路径
          const destPath = `${this.context.filesDir}/test_copy.zip`;

          // 执行复制（带进度监听）
          const success = await this.fileUtil.copyFileWithProgress(
            srcPath,
            destPath,
            (progress) => {
              // 更新进度（UI线程）
              this.copyProgress = progress;
            }
          );

          this.isCopying = false;
          if (success) {
            promptAction.showToast({ message: '复制成功' });
          } else {
            promptAction.showToast({ message: '复制失败' });
          }
        })
        .width('80%')
        .enabled(!this.isCopying)
    }
    .width('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

三、避坑点

1. 沙箱路径规范：必须通过context.filesDir/context.cacheDir获取路径，不可硬编码；
2. 大文件处理：超过 100MB 的文件必须用流（createStream）分段处理，避免内存溢出；
3. TaskPool 限制：@Concurrent装饰的方法不可直接访问组件状态，需通过回调更新 UI；
4. 权限问题：沙箱内文件操作无需额外权限，若操作公共目录需申请ohos.permission.READ_EXTERNAL_STORAGE；
5. 异常处理：复制失败时需删除目标文件，避免残留无效文件。