HarmonyOS文件基础服务(Core File Kit)实战演练05-实战：文件管理工具开发

HarmonyOS文件基础服务实战演练05：实战：文件管理工具开发

在HarmonyOS应用开发中，文件管理是最基础且频繁使用的功能之一。Core File Kit（文件基础服务）提供了统一的文件操作接口，但实际开发中常会遇到目录浏览、文件创建删除重命名以及权限校验等问题。本文基于前四篇已掌握的文件操作API，构建一个跨平台文件管理工具，核心功能包括目录浏览、文件操作、权限校验及异常处理。

核心概念

Core File Kit 以 Kit 维度封装文件相关接口，开发者通过导入 Kit 的方式即可使用其能力。应用开发文档中明确，从 HarmonyOS NEXT Developer Preview1（API 11）版本开始，SDK 以 Kit 维度提供开放能力，Kit 封装的接口模块可查看 SDK 目录下各 Kit 的定义。文件管理工具的开发需遵守以下规则：

所有文件操作接口必须在 module.json5 中声明对应权限。
元服务只能使用带"元服务 API"标记的接口。
不同设备类型对接口支持情况有差异，可通过 API 参考页面筛选设备类型查看。

环境准备

DevEco Studio 6.1.0 Release 及以上版本
HarmonyOS SDK 6.1.0(23) 及以上版本

核心实现

以下实现基于 Ability Kit（程序框架服务）搭建页面，结合 Core File Kit 提供的文件操作能力。代码示例中的 API 均来自官方文档中明确指出的文件基础服务接口（如 fileIo 等），所有调用方式与文档示例保持一致。

1. 导入 Kit

根据文档说明，通过导入 Kit 的方式引入文件管理能力。例如：

typescript 复制代码

import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

注意： @kit.CoreFileKit 包名在 API 11 以后统一，若使用旧版本可能需导入 @ohos.file.fs 等模块，请根据实际 SDK 版本调整导入路径。

2. 获取应用沙箱路径

在 UIAbility 中通过上下文获取沙箱路径。文档指出，应用文件操作需在应用沙箱内进行。

typescript 复制代码

let context = getContext(this) as common.UIAbilityContext;
let sandboxPath = context.filesDir;

提示： context.filesDir 返回的是应用内部沙箱根目录，不同 Ability 上下文可能返回不同路径（如 PageAbility 与 ServiceAbility），建议在 UIAbility 的 onCreate 中获取并保存，或通过全局状态共享。沙箱外文件操作需额外声明权限。

3. 目录浏览与文件列表

使用 fileIo.listDir 列出目录内容，返回 FileInfo 数组，包含文件名、大小、修改时间等。

typescript 复制代码

async function listFiles(dirPath: string): Promise<Array<fileIo.FileInfo>> {
  try {
    let fileList = await fileIo.listDir(dirPath);
    return fileList;
  } catch (error) {
    console.error(`listDir failed, error: ${JSON.stringify(error)}`);
    return [];
  }
}

提示： FileInfo 中的 isDirectory 属性可用于判断是否为目录，在 UI 中区分文件和文件夹展示。另外，listDir 默认不递归子目录，若需遍历整个目录树需自行递归调用。

4. 文件操作：创建、删除、重命名

typescript 复制代码

async function createFile(parentPath: string, fileName: string): Promise<void> {
  let filePath = `${parentPath}/${fileName}`;
  await fileIo.create(filePath);
}

async function deleteFile(filePath: string): Promise<void> {
  await fileIo.delete(filePath);
}

async function renameFile(oldPath: string, newPath: string): Promise<void> {
  await fileIo.rename(oldPath, newPath);
}

注意： create 默认创建空文件，若需要创建目录请使用 fileIo.mkdir。删除文件前建议先检查文件是否存在，可使用 fileIo.access 或捕获异常。重命名时 newPath 必须包含完整路径（新文件名），rename 不支持跨盘移动，若需移动文件请使用 fileIo.move。

5. 权限校验

应用操作文件前需在 module.json5 中声明权限，例如写入沙箱外的文件需申请 ohos.permission.WRITE_MEDIA。对于沙箱内操作，默认无需额外权限。若需检查权限状态，可通过 abilityAccessCtrl 动态查询：

typescript 复制代码

import { abilityAccessCtrl } from '@kit.AbilityKit';

async function checkPermission(permission: string): Promise<boolean> {
  let atManager = abilityAccessCtrl.createAtManager();
  let result = await atManager.checkAccessToken({ tokenID: 0, permissionName: permission });
  return result === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
}

提示： 沙箱路径操作无需声明 READ_MEDIA / WRITE_MEDIA 权限，但若需访问相册或媒体库，则必须在 module.json5 中声明，并通过 requestPermissions 动态申请。权限申请结果异步回调，建议在用户操作触发前统一处理。

6. 异常处理

Core File Kit 接口抛出 BusinessError，包含 code 和 message。建议在调用处统一捕获并做差异化处理：

typescript 复制代码

async function safeFileOperation(filePath: string, operation: string): Promise<void> {
  try {
    switch (operation) {
      case 'delete':
        await fileIo.delete(filePath);
        break;
      case 'create':
        await fileIo.create(filePath);
        break;
      default:
        break;
    }
  } catch (error) {
    console.error(`${operation} failed, code: ${error.code}, message: ${error.message}`);
    // 可根据 error.code 细分处理，如 13900001 表示文件不存在
    if (error.code === 13900001) {
      // 提示用户文件已被移除
    }
  }
}

提示： 常见错误码可参考官方文档"通用错误码"章节，如 13900001（文件不存在）、13900002（权限不足）、13900003（IO错误）等。统一异常处理能避免未捕获异常导致应用崩溃。

本文实现了文件管理工具的核心功能模块，涵盖了从权限校验到异常处理的完整流程。实际开发中可根据需求扩展文件搜索、剪贴板、压缩等功能。欢迎在评论区交流特定场景下的实现细节。

在HarmonyOS应用开发中，文件操作是基础功能，但许多开发者在权限配置、路径确认及异常处理上反复踩坑。Core File Kit提供了沙箱内的文件读写接口，但若未正确理解沙箱路径与权限声明，实际运行时会出现"Permission denied"或"目录不存在"等问题。下面通过完整的代码示例和关键细节说明，逐步覆盖权限校验、异常处理等环节，帮助减少调试时间。

5. 权限校验

应用操作文件前需在 module.json5 中声明权限，例如写入沙箱外的文件需申请 ohos.permission.WRITE_MEDIA。代码中可通过 abilityAccessCtrl 检查权限状态，但此部分涉及安全 Kit，文档未详细展开。本实战基于沙箱路径操作，无需额外权限。

沙箱路径下无需在 module.json5 中声明任何存储权限，但若需要访问相册或媒体库，则必须按文档声明对应权限。建议优先使用沙箱路径，能避开大量权限适配问题。

6. 异常处理

所有文件操作均使用 try-catch 包裹，文档中强调接口调用可能失败，需捕获错误。常见错误码包括文件不存在、路径无权限等。

typescript 复制代码

try {
  // 例如打开文件
  let file = fileIo.openSync(path);
  // ... 操作文件
} catch (error) {
  console.error(`文件操作异常，错误码: ${error.code}, 信息: ${error.message}`);
  // 根据错误码做不同处理，例如 13900001 表示文件不存在
}

错误码可通过 fileIo.errno 对照，但更直接的做法是查看 error.code。建议对每个文件操作单独 try-catch，而不是用一个外层包裹所有操作，否则难以定位具体哪一步出错。

注意事项

元服务只能使用带"元服务 API"标记的接口，部分文件操作接口不支持在元服务中使用，开发时需留意接口文档中的标记。例如 fileIo.listDirSync 在元服务中可用，但 fileIo.createRandomAccessFile 可能不被支持。
不同设备类型（手机、平板、PC/2in1）对接口支持情况有差异，可通过 API 参考页面左侧"高级筛选>设备"筛选查看。例如 ohos.permission.WRITE_MEDIA 在手机和平板上均需声明，但在 PC 上可能不同。
文件操作路径需在应用沙箱内，跨应用访问需使用 fileAccess 等其他模块，非本 Kit 范围。沙箱路径可使用 context.filesDir 或 context.cacheDir 获得，不要硬编码路径。

常见问题 FAQ

Q1：文件操作返回 "Permission denied" 错误？

A：确认 module.json5 中已声明对应权限，且仅在沙箱路径内操作。沙箱外路径需额外授权。另外检查是否在 Ability 的 onCreate 或 onWindowStageCreate 之后才调用文件操作，部分上下文在生命周期早期不可用。

Q2：listDir 返回空数组？

A：检查目录路径是否正确，路径不存在或为空目录时返回空数组。建议先使用 fileIo.access 判断目录是否存在。例如：

typescript 复制代码

if (!fileIo.accessSync(dirPath)) {
  console.error('目录不存在');
  return;
}

Q3：接口在元服务中不可用？

A：查看 API 参考页面，确认接口是否带有"元服务 API"标记。若无则该接口仅支持应用。另外，部分接口在元服务中可能同步版本不可用但异步版本可用，建议优先使用带 Callback 或 Promise 的接口。

上一篇介绍了 Core File Kit 的流式读写与大数据量处理策略。下一篇将探讨应用数据安全与加密存储，结合 ArkData 实现文件级加密。你对沙箱文件操作还有哪些困惑？欢迎在评论区交流。