HarmonyOS：应用文件概述（通俗易懂解释版）

应用文件概述

原文：

应用文件：文件所有者为应用，包括应用安装文件、应用资源文件、应用缓存文件等。

设备上应用所使用及存储的数据，以文件、键值对、数据库等形式保存在一个应用专属的目录内。该专属目录我们称为"应用文件目录"，该目录下所有数据以不同的文件格式存放，这些文件即应用文件。
"应用文件目录"与一部分系统文件（应用运行必须使用的系统文件）所在的目录组成了一个集合，该集合称为"应用沙箱目录"，代表应用可见的所有目录范围。因此"应用文件目录"是在"应用沙箱目录"内的。
系统文件及其目录对于应用是只读的；应用仅能保存文件到"应用文件目录"下，根据目录的使用规范和注意事项来选择将数据保存到不同的子目录中。

解释：

核心概念：沙箱与专属房间

应用沙箱目录： 想象一下，每个鸿蒙应用都有一个独立的"房间"（沙箱）。这个房间里放着应用运行所需的所有东西，包括它自己的文件和一些系统提供的必需品。其他应用未经允许不能进入这个房间，从而保证了每个应用的数据安全和隐私。
应用文件目录： 这个"房间"里有一个专门的"储物柜"，用来存放应用自己的各种数据，比如用户设置、下载的文件、缓存的图片等等。这个"储物柜"就是"应用文件目录"。

房间里的物品：文件类型

"储物柜"里存放的东西（文件）主要有：

应用安装文件： 就像应用的"身份证"，告诉系统这是什么应用。
应用资源文件： 应用的"装饰品"，比如图片、声音、布局文件等，让应用界面更美观、功能更丰富。
应用缓存文件： 应用为了运行更快而临时存放的一些东西，比如之前看过的网页、图片等。

房间规则：访问权限

系统文件只读： "房间"里有些东西是系统提供的，应用只能看（只读），不能改，就像房间里的墙壁、地板，你不能随意拆除或改造。
应用文件可读写： "储物柜"里的东西，应用可以自由存取、修改，就像你可以在自己的储物柜里放东西、拿东西、整理东西。
子目录规范： "储物柜"里有不同的格子（子目录），应用需要按照一定的规则来存放东西，比如把临时文件放在"垃圾桶"格子里，把重要的文件放在"保险箱"格子里。

总结：

鸿蒙系统为每个应用提供了一个安全的"房间"（沙箱），应用只能在自己的"房间"里活动，并且有一个专门的"储物柜"（应用文件目录）来存放自己的数据。应用可以自由管理"储物柜"里的东西，但"房间"里的一些系统提供的物品是不能随意修改的。这样既保证了应用数据的安全，又给了应用足够的自由度来管理自己的文件。

应用文件目录与应用文件路径

应用文件目录：你的专属储物柜

如果把整个沙箱比作一个应用独占的"房间"，那么"应用文件目录"就是房间里一个 വലിയ "储物柜"。这个"储物柜"是专门用来存放应用自己的各种数据的，而且只有这个应用自己能打开和使用。

储物柜的分层与分区 (目录结构)

这个"储物柜"可不是一个大箱子，它里面有很多层、很多格子，就像我们家里的衣柜、书柜一样，分门别类地存放不同的东西。

第一层 (data/): 这是"储物柜"的最顶层，代表整个应用文件目录。
第二层 (storage/): 这是"储物柜"的第二层，告诉你这个"储物柜"是用来存放需要长期保存的东西的。
第三层 (el1/ 到 el5/): 这是"储物柜"的第三层，也是最特别的一层。它代表了不同的"安全等级"。
- el1: 就像一个普通的抽屉，谁都能打开，安全性最低。
- el2: 像一个带锁的抽屉，只有你第一次输入密码后才能打开，之后只要你不关"房间"（关机），就可以随意使用。这是最常用的安全等级。
- el3, el4, el5: 就像更高级的保险箱，有更严格的开启条件，安全性更高，但一般应用用不到。
- 默认用 el2: 一般情况下，应用的数据都放在 el2 这个"抽屉"里。
第四、五层 (base/, bundle/, database/, distributedfiles/, files/, cache/, preferences/, temp/, haps/): 这些是"储物柜"里更细分的"格子"，用来存放不同类型的文件。
- bundle: 这是应用的"家当"，比如代码和一些应用资源等等，这些是应用运行的基础。
- base: 这是应用存放持久化数据的地方, 相当于总的根目录。
- database: 这是专门用来存放"数据库"文件的"格子"。
- distributedfiles: 这是用来存放可以在不同设备间共享的文件的"格子"。
- files: 这是用来存放应用需要长期保存的文件的"格子"，比如用户自己创建的文件、重要的下载文件等。
- cache: 这是用来存放"缓存"文件的"格子"，比如临时下载的图片、网页等，这些文件可以随时被清理。
- preferences: 这是用来存放应用的一些"设置"信息的"格子"，比如用户是否打开了夜间模式。
- temp: 这是用来存放"临时"文件的"格子"，应用关闭后这些文件就会被清理。
- haps: 存放HAP级别应用文件路径，文件会跟随HAP的卸载而删除。

重要提示

不要直接使用路径字符串： 尽量不要自己去拼接这些目录的路径，而是使用系统提供的 API 来获取正确的路径，避免以后系统升级导致应用出错。
Context 获取路径： 通过 Context（上下文）对象，你可以方便地获取到这些"格子"的路径。

总结

"应用文件目录"就像应用专属"房间"里的一个"储物柜"，里面有很多"层"和"格子"，用来存放不同类型的文件。应用需要按照规则把文件放到合适的"格子"里，并且通过系统提供的 API 来访问这些文件。这样既能保证数据的安全，又能让应用高效地管理自己的文件。

应用文件路径：储物柜格子的地址

如果把"应用文件目录"比作一个"储物柜"，那么"应用文件路径"就是"储物柜"里每个"格子"的具体地址。通过这个地址，应用才能找到并使用存放在里面的文件。

格子地址与用途

bundle (context: bundleCodeDir):
- 地址： bundleCodeDir
- 类型： 安装文件路径
- 用途： 这是应用的"家当"所在的"格子"，里面放着应用的"安装包"（HAP 资源包）、"工具箱"（可重复使用的库文件）和"扩展包"（插件资源）。应用卸载后，这个"格子"里的东西会被清理。
- 重要提示： 不要自己去拼接这个"格子"的地址，要使用系统提供的"资源管理接口"来访问里面的东西。
base:
- 地址： 无 (NA)
- 类型： 本设备文件路径
- 用途： 这是应用存放需要长期保存的数据的"总目录"，它下面还有很多"子格子"，比如 files/、cache/、temp/ 和 haps/。应用卸载后，这个"总目录"和里面的"子格子"都会被清理。
database (context: databaseDir):
- 地址： databaseDir
- 类型： 数据库路径
- 用途： 这是专门用来存放"数据库"文件的"格子"，而且是在 el2 加密条件下（就是我们之前说的"带锁的抽屉"）。应用卸载后，这个"格子"里的东西会被清理。
- 注意： 这个"格子"只适合存放"分布式数据库"相关的文件。
distributedfiles (context: distributedFilesDir):
- 地址： distributedFilesDir
- 类型： 分布式文件路径
- 用途： 这是用来存放可以在不同设备间共享的文件的"格子"，也是在 el2 加密条件下。应用卸载后，这个"格子"里的东西会被清理。
- 例如： 你可以在这个"格子"里存放一些需要在手机、平板、电脑之间共享的文件。
files (context: filesDir):
- 地址： filesDir
- 类型： 应用通用文件路径
- 用途： 这是用来存放应用需要长期保存的文件的"格子"，比如用户自己创建的文件、重要的下载文件、应用的日志文件等。应用卸载后，这个"格子"里的东西会被清理。
cache (context: cacheDir):
- 地址： cacheDir
- 类型： 应用缓存文件路径
- 用途： 这是用来存放"缓存"文件的"格子"，比如临时下载的图片、网页等。这个"格子"里的东西可能会被系统自动清理，或者被用户手动清理。
- 重要提示： 不要在这个"格子"里存放重要的文件，因为它们随时可能消失。
preferences (context: preferencesDir):
- 地址： preferencesDir
- 类型： 应用首选项文件路径
- 用途： 这是用来存放应用的一些"设置"信息的"格子"，比如用户是否打开了夜间模式、字体大小等。这个"格子"适合存放少量数据。应用卸载后，这个"格子"里的东西会被清理。
temp (context: tempDir):
- 地址： tempDir
- 类型： 应用临时文件路径
- 用途： 这是用来存放"临时"文件的"格子"，应用关闭后这些文件就会被清理。
  例如： 在这里可以存放一些数据库缓存，或者临时存放一些图片等等

总结

"应用文件路径"就是应用"储物柜"里每个"格子"的具体地址。通过这些地址，应用可以找到并使用存放在里面的文件。每个"格子"都有自己的用途，应用需要按照规则把文件放到合适的"格子"里。

应用文件访问(ArkTS)

HarmonyOS 应用访问沙箱文件，主要遵循以下步骤：

获取 Context 对象： Context 是应用的上下文，可以理解为应用的"管家"，它提供了访问应用资源和执行操作的方法。
通过 Context 获取沙箱目录路径： 使用 Context 提供的 API（如 getFilesDir(), getCacheDir() 等）获取特定沙箱目录的路径。
使用文件 I/O API 进行文件操作： 拿到目录路径后，就可以使用标准的文件 I/O API（如 POSIX 文件操作接口）进行文件的创建、读取、写入、删除等操作。

首先需要获得UIAbility的上下文信息(Context)

1. 在EntryAbility（UIAbility）中获取上下文信息（Context）的方法

TypeScript 复制代码

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 获取UIAbility实例的上下文
    let context = this.context;
    // ...
  }
}

2. 在页面中获取UIAbility实例的上下文信息，包括导入依赖资源context模块和在组件中定义一个context变量两个部分。

TypeScript 复制代码

/**
* 导入依赖资源context模块
*/
import { common, Want } from '@kit.AbilityKit';

@Entry
@Component
struct Page_EventHub {
    /**
    * 在组件中定义一个context变量
    */
  private context = getContext(this) as common.UIAbilityContext;
   
  startAbilityTest(): void {
    let want: Want = {
      // Want参数信息
    };
    this.context.startAbility(want);
  }

  // 页面展示
  build() {
    // ...
  }
}

新建并读写一个文件

以下示例代码演示了如何新建一个文件并对其读写。

这段代码的目标很简单：

在应用的专属"房间"（沙箱）的 files 目录中创建一个名为 test.txt 的文件。
向这个文件中写入一段文字："Try to write str."。
再把这段文字从文件中读取出来，并显示在控制台中。

TypeScript 复制代码

// pages/xxx.ets
import { fileIo as fs, ReadOptions } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { buffer } from '@kit.ArkTS';

// 获取应用文件路径
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;

function createFile(): void {
  // 文件不存在时创建并打开文件，文件存在时打开文件
  // 拼接文件路径： filesDir + '/test.txt' 将 files 目录的路径和文件名 test.txt 拼接起来，得到完整的文件路径。
  // 打开/创建文件： fs.openSync() 是 fileIo 模块提供的同步打开文件的函数。
  let file = fs.openSync(filesDir + '/test.txt', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  // 写入一段内容至文件
  // 返回值: writeLen 变量存储了实际写入的字节数。
  let writeLen = fs.writeSync(file.fd, "Try to write str.");
  console.info("The length of str is: " + writeLen);
  // 创建一个大小为1024字节的ArrayBuffer对象，用于存储从文件中读取的数据
  let arrayBuffer = new ArrayBuffer(1024);
  // 设置读取的偏移量和长度
  // offset: 0： 表示从文件的开头开始读取。
  // length: arrayBuffer.byteLength： 表示最多读取 arrayBuffer 的大小（1024 字节）。
  let readOptions: ReadOptions = {
    offset: 0,
    length: arrayBuffer.byteLength
  };
  // 读取文件内容到ArrayBuffer对象中，并返回实际读取的字节数
  let readLen = fs.readSync(file.fd, arrayBuffer, readOptions);
  // 将ArrayBuffer对象转换为Buffer对象，并转换为字符串输出
  let buf = buffer.from(arrayBuffer, 0, readLen);
  console.info("the content of file: " + buf.toString());
  // 关闭文件
  fs.closeSync(file);
}

ArkTS中基础文件操作接口功能

接口名	功能	接口类型	支持同步	支持异步
access	检查文件是否存在	方法	√	√
close	关闭文件	方法	√	√
copyFile	复制文件	方法	√	√
createStream	基于文件路径打开文件流	方法	√	√
listFile	列出文件夹下所有文件名	方法	√	√
mkdir	创建目录	方法	√	√
moveFile	移动文件	方法	√	√
open	打开文件	方法	√	√
read	从文件读取数据	方法	√	√
rename	重命名文件或文件夹	方法	√	√
rmdir	删除整个目录	方法	√	√
stat	获取文件详细属性信息	方法	√	√
unlink	删除单个文件	方法	√	√
write	将数据写入文件	方法	√	√
Stream.close	关闭文件流	方法	√	√
Stream.flush	刷新文件流	方法	√	√
Stream.write	将数据写入流文件	方法	√	√
Stream.read	从流文件读取数据	方法	√	√
File.fd	获取文件描述符	属性	-	-
OpenMode	设置文件打开标签	属性	-	-
Filter	设置文件过滤配置项	类型	-	-

原文档链接：文档中心https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/app-sandbox-directory-V13