HarmonyOS文件基础服务(Core File Kit)实战演练02-环境搭建与基础配置

Core File Kit 实战演练 02：环境搭建与基础配置

使用 Core File Kit 处理文件时，第一个问题通常是：环境怎么配？权限要不要声明？本篇文章直接演示如何在 DevEco Studio 中完成环境配置和权限声明，并实现一个文本文件的创建、写入与读取。操作仅限应用内部沙箱，核心接口来自 @kit.CoreFileKit。

1. 核心概念

Core File Kit 归属于"应用框架"Kit 类别，提供文件系统相关的基础操作能力。其接口包含在 SDK 的 Kit 模块中，需要通过导入 Kit 的方式获取接口能力。

HarmonyOS SDK 从 HarmonyOS NEXT Developer Preview1（API 11）版本开始，以 Kit 维度提供开放能力。Core File Kit 是文件存储领域的基础服务。

2. 环境准备

DevEco Studio 版本：6.1.0 Release 或更高版本
HarmonyOS SDK：6.1.0(23) 或更高版本（对应 API Version 23）

不推荐直接使用 API 11 以下的旧版本 SDK，许多文件接口在不同版本有所演进。若必须使用旧版本，请在 API 参考中勾选对应 SDK 版本查看可用接口。

3. 核心实现

3.1 声明权限

如果需要访问用户媒体文件（图片、音频、视频），必须在 module.json5 中添加权限声明。若操作仅限应用内部沙箱文件，可不申请此权限。

打开模块下的 module.json5，在 requestPermissions 数组中添加：

json 复制代码

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "$string:read_media_reason"
      },
      {
        "name": "ohos.permission.WRITE_MEDIA",
        "reason": "$string:write_media_reason"
      }
    ]
  }
}

在 string.json 中定义对应的原因描述：

json 复制代码

{
  "string": [
    {
      "name": "read_media_reason",
      "value": "用于读取用户媒体文件"
    },
    {
      "name": "write_media_reason",
      "value": "用于写入用户媒体文件"
    }
  ]
}

特别注意：如果不涉及跨应用文件共享，应用沙箱内的文件操作不需要声明任何用户权限。如果只操作沙箱文件却声明了读写媒体权限，反而可能引起用户对隐私用途的质疑，建议按需添加。

3.2 创建并写入文件

在 .ets 文件中先导入所需模块：

typescript 复制代码

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

使用 fileIo.open 创建或打开文件，参数中的 mode 使用 OpenMode.CREATE 确保文件不存在时自动创建。

typescript 复制代码

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

@Entry
@Component
struct FileDemo {
  build() {
    Column() {
      Button('创建并写入文件')
        .onClick(() => {
          this.createAndWriteFile();
        })
    }
    .width('100%')
    .height('100%')
  }

  async createAndWriteFile() {
    const context: common.Context = getContext(this);
    // 获取应用沙箱内文件路径，文件名为 demo.txt
    const filePath: string = context.filesDir + '/demo.txt';
    // 使用 CREATE 模式打开，若文件已存在则直接打开
    const file: fileIo.File = await fileIo.open(filePath, fileIo.OpenMode.CREATE);
    // 写入内容
    await fileIo.write(file.fd, 'Hello, Core File Kit!');
    // 关闭文件
    fileIo.close(file);
    console.info('文件创建并写入成功');
  }
}

注意：fileIo.open 返回的 file 对象中的 fd 是文件描述符，写入完成后务必调用 fileIo.close 释放资源，否则可能导致文件句柄泄漏。不过，如果使用 fileIo.open 时传入的 mode 不包含 WRITE_ONLY 或 READ_WRITE，则写入时会报错，这里使用 CREATE 实际上隐含了可写权限。更严谨的做法是使用 fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY。

3.3 读取文件内容

接上一步，读取刚刚写入的文件：

typescript 复制代码

async readFile() {
  const context: common.Context = getContext(this);
  const filePath: string = context.filesDir + '/demo.txt';
  const file: fileIo.File = await fileIo.open(filePath, fileIo.OpenMode.READ_ONLY);
  // 获取文件大小
  const stat = await fileIo.stat(filePath);
  const buf = new ArrayBuffer(stat.size);
  await fileIo.read(file.fd, buf);
  const content = new TextDecoder().decode(buf);
  console.info('读取内容:', content);
  fileIo.close(file);
}

读取时建议先通过 fileIo.stat 获取文件大小，避免分配过大或过小的缓冲区。如果文件内容未知，也可以循环读取直到返回长度为零。TextDecoder 用于将 ArrayBuffer 解码为字符串，编码默认为 UTF-8。

以上就是使用 Core File Kit 进行基础文件操作的全过程。APIs 具体参数（如 OpenMode 枚举值）可参考官方 API 文档。如果你在沙箱外操作文件（如用户选择目录），则需额外关注权限与安全上下文。欢迎在评论区交流实际调试中遇到的权限问题。

3.2 创建文件并写入内容

通过 fileIo.open 指定 OpenMode.CREATE 模式完成文件创建，然后调用 fileIo.write 写入数据：

typescript 复制代码

.height('100%')
  }

  async createAndWriteFile() {
    const context: common.Context = getContext(this);
    // 获取应用沙箱内文件路径，文件名为 demo.txt
    const filePath: string = context.filesDir + '/demo.txt';

    // 打开文件，CREATE 表示文件不存在则创建
    const file: fileIo.File = await fileIo.open(filePath, fileIo.OpenMode.CREATE);
    console.info('文件创建成功，fd: ' + file.fd);

    // 写入字符串内容
    await fileIo.write(file.fd, 'Hello Core File Kit!');
    console.info('写入成功');

    // 关闭文件描述符
    fileIo.close(file);
    console.info('文件已关闭');
  }
}

关键参数说明：

OpenMode.CREATE：如果文件不存在则创建新文件，若存在则打开原有文件
写入操作使用 fileIo.write，写入内容为 string 或 ArrayBuffer

💡 注意：fileIo.write 写入时，若文件已存在且未指定 OpenMode.TRUNC，原有内容不会被清空，新内容会追加到文件末尾。若需要覆盖写入，应先使用 OpenMode.TRUNC 模式打开。

3.3 读取文件内容

读取文件同样需要先打开文件，然后调用 fileIo.read：

typescript 复制代码

async readFile() {
  const context: common.Context = getContext(this);
  const filePath: string = context.filesDir + '/demo.txt';

  // 以只读模式打开文件
  const file: fileIo.File = await fileIo.open(filePath, fileIo.OpenMode.READ_ONLY);

  // 读取全部内容，指定读取长度（这里设为 1024）
  const readBuf: ArrayBuffer = new ArrayBuffer(1024);
  const readLen: number = await fileIo.read(file.fd, readBuf);
  console.info('读取长度: ' + readLen);

  // 将 ArrayBuffer 转为字符串
  const content: string = new TextDecoder().decode(readBuf.slice(0, readLen));
  console.info('文件内容: ' + content);

  fileIo.close(file);
}

💡 注意：new ArrayBuffer(1024) 表示预分配 1024 字节的缓冲区。实际读取长度由 readLen 返回，若文件小于 1024 字节，则只读入文件实际大小。避免使用固定大缓冲区读取未知大小文件时，建议先通过 fileIo.stat 获取文件大小。

4. 注意事项

应用沙箱内的文件操作不需要任何权限声明，只有访问外部存储的媒体文件才需 ohos.permission.READ_MEDIA 等权限
OpenMode.CREATE 只负责创建文件，不会覆盖已有内容。若需要清空后写入，请使用 OpenMode.TRUNC
文件读写完毕后必须调用 fileIo.close 释放文件描述符，否则可能导致资源泄漏
fileIo.write 和 fileIo.read 返回的 number 是实际写入或读取的字节数，可通过它判断操作是否完全完成

上一篇介绍了 Core File Kit 整体能力概览和适用场景。下一篇将进入 批量文件操作，演示如何高效处理多个文件的复制、移动和删除。

如果你在实际开发中遇到沙箱路径或权限相关的问题，欢迎在评论区交流讨论。