前言

文件拷贝和移动是文件管理的常见操作，如备份文件、整理目录结构等。@pura/harmony-utils 的 FileUtil 封装了文件拷贝和移动方法，支持跨目录操作。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、FileUtil拷贝移动核心API

FileUtil 提供了以下文件拷贝和移动方法：

方法	说明	返回类型	使用场景
copyFile(src, dest)	拷贝文件	void	文件备份
copyDir(src, dest)	拷贝目录	void	目录备份
moveFile(src, dest)	移动文件	void	文件归档
moveDir(src, dest)	移动目录	void	目录整理

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 跨目录支持：支持跨目录的拷贝和移动操作

1.2 拷贝与移动区别

操作	源文件	目标文件	适用场景
拷贝	保留	新增副本	备份、复制
移动	删除	新增	归档、整理

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 文件拷贝

import { FileUtil } from '@pura/harmony-utils';

Button('拷贝文件')
  .width('100%')
  .onClick(() => {
    try {
      let src = FileUtil.getFilesDir() + '/test.txt';
      let dest = FileUtil.getFilesDir() + '/backup.txt';
      FileUtil.copyFile(src, dest);
      this.result = `拷贝成功 ✅\n源: test.txt\n目标: backup.txt`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 文件移动

Button('移动文件')
  .width('100%')
  .onClick(() => {
    try {
      let src = FileUtil.getFilesDir() + '/backup.txt';
      let dest = FileUtil.getFilesDir() + '/archive/backup.txt';
      FileUtil.moveFile(src, dest);
      this.result = `移动成功 ✅\n已移至archive目录`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { FileUtil } from '@pura/harmony-utils';

@Entry
@Component
struct FileCopyDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('创建测试文件').width('100%').onClick(() => {
        FileUtil.writeTextSync(FileUtil.getFilesDir() + '/src.txt', '测试内容');
        this.result = '测试文件已创建';
      });
      Button('拷贝文件').width('100%').onClick(() => {
        try {
          FileUtil.copyFile(FileUtil.getFilesDir() + '/src.txt', FileUtil.getFilesDir() + '/dst.txt');
          this.result = '拷贝成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 文件备份策略

import { FileUtil } from '@pura/harmony-utils';

function backupFile(filePath: string): string {
  let backupPath = filePath + '.bak';
  FileUtil.copyFile(filePath, backupPath);
  return backupPath;
}

4.2 批量移动文件

function moveFilesToArchive(filePaths: string[]): void {
  let archiveDir = FileUtil.getFilesDir() + '/archive';
  FileUtil.createDir(archiveDir);
  filePaths.forEach(path => {
    let filename = path.split('/').pop() || '';
    FileUtil.moveFile(path, archiveDir + '/' + filename);
  });
}

五、注意事项

1. 目标路径：目标路径的父目录必须存在
2. 同名文件：目标路径已存在同名文件会覆盖
3. 跨分区：移动操作跨分区时实际为拷贝+删除
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 大文件：大文件拷贝可能耗时，建议异步处理

六、常见问题

Q1: 拷贝文件时目标目录不存在？

需要先创建目标目录，使用 createDir() 创建后再拷贝。

Q2: 移动文件后源文件还在？

可能是跨分区移动失败，检查源路径和目标路径是否有效。

Q3: 如何批量拷贝整个目录？

使用 copyDir() 方法可以拷贝整个目录及其内容。

Q4: 拷贝过程中断会导致数据丢失吗？

拷贝是原子操作，中断后目标文件可能不完整，建议校验后使用。

总结

FileUtil 的文件拷贝和移动方法为文件管理提供了便捷操作。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据需求选择拷贝或移动操作。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。