文件管理概述

• 结构化数据：能够用统一的数据模型加以描述的数据。常见的是各类数据库数据。在应用开发中，对结构化数据的开发活动隶属于数据管理模块。

• 非结构化数据：指数据结构不规则或不完整，没有预定义的数据结构/模型，不方便用数据库二维逻辑表来表现的数据。常见的是各类文件，如文档、图片、音频、视频等。在应用开发中，对非结构化数据的开发活动隶属于文件管理模块，将在下文展开介绍。

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

• 用户文件：文件所有者为登录到该终端设备的用户，包括用户私有的图片、视频、音频、文档等。

• 系统文件：与应用和用户无关的其他文件，包括公共库、设备文件、系统资源文件等。这类文件不需要开发者进行文件管理，本文不展开介绍。

• 本地文件系统：提供本地设备或外置存储设备（如U盘、移动硬盘）的文件访问能力。本地文件系统是最基本的文件系统，本文不展开介绍。

• 分布式文件系统：提供跨设备的文件访问能力。所谓跨设备，指文件不一定存储在本地设备或外置存储设备，而是通过计算机网络与其他分布式设备相连。

应用文件

应用文件概述

• 设备上应用所使用及存储的数据，以文件、键值对、数据库等形式保存在一个应用专属的目录内。该专属目录我们称为“应用文件目录”，该目录下所有数据以不同的文件格式存放，这些文件即应用文件。

• “应用文件目录”与一部分系统文件（应用运行必须使用的系统文件）所在的目录组成了一个集合，该集合称为“应用沙箱目录”，代表应用可见的所有目录范围。因此“应用文件目录”是在“应用沙箱目录”内的。

• 系统文件及其目录对于应用是只读的；应用仅能保存文件到“应用文件目录”下，根据目录的使用规范和注意事项来选择将数据保存到不同的子目录中。

应用沙箱目录

• 对于每个应用，系统会在内部存储空间映射出一个专属的“应用沙箱目录”，它是“应用文件目录”与一部分系统文件（应用运行必需的少量系统文件）所在的目录组成的集合。

• 应用沙箱限制了应用可见的数据的最小范围。在“应用沙箱目录”中，应用仅能看到自己的应用文件以及少量的系统文件（应用运行必需的少量系统文件）。因此，本应用的文件也不为其他应用可见，从而保护了应用文件的安全。

• 应用可以在“应用文件目录”下保存和处理自己的应用文件；系统文件及其目录对于应用是只读的；而应用若需访问用户文件，则需要通过特定API同时经过用户的相应授权才能进行。

图1 应用沙箱文件访问关系图

应用沙箱目录与应用沙箱路径

• 如下图所示，在普通应用（也称三方应用）视角下，不仅可见的目录与文件数量限制到了最小范围，并且可见的目录与文件路径也与系统进程等其他进程看到的不同。我们将普通应用视角下看到的“应用沙箱目录”下某个文件或某个具体目录的路径，称为“应用沙箱路径”。

• 一般情况下，开发者的hdc shell环境等效于系统进程视角，因此“应用沙箱路径”与开发者使用hdc工具调试时看到的真实物理路径不同，其对应关系详见应用沙箱路径和调试进程视角下的真实物理路径。

• 从实际物理路径推导物理路径与沙箱路径并不是1：1的映射关系，沙箱路径总是少于系统进程视角可见的物理路径。有些调试进程视角下的物理路径在对应的应用沙箱目录是无法找到的，而沙箱路径总是能够找到其对应的物理路径。（这一个有什么影响？？？）

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

1. 一级目录data/：代表应用文件目录。

2. 二级目录storage/：代表本应用持久化文件目录。

3. 三级目录el1/、el2/：代表不同文件加密类型。
• el1，设备级加密区：设备开机后即可访问的数据区。
• el2，用户级加密区：设备开机后，需要至少一次解锁对应用户的锁屏界面（密码、指纹、人脸等方式或无密码状态）后，才能够访问的加密数据区。
应用如无特殊需要，应将数据存放在el2加密目录下，以尽可能保证数据安全。但是对于某些场景，一些应用文件需要在用户解锁前就可被访问，例如时钟、闹铃、壁纸等，此时应用需要将这些文件存放到设备级加密区（el1）。切换应用文件加密类型目录的方法请参见获取和修改加密分区。

4. 四级、五级目录：
通过ApplicationContext可以获取base下的files、cache、preferences、temp、distributedfiles等目录的应用文件路径，应用全局信息可以存放在这些目录下。
通过UIAbilityContext、AbilityStageContext、ExtensionContext可以获取hap级别应用文件路径。HAP信息可以存放在这些目录下，存放在此目录的文件会跟随HAP的卸载而删除，不会影响app级别目录下的文件。在开发态，一个应用包含一个或者多个HAP，详见Stage模型应用程序包结构。
Context上下文获取及上述应用文件路径的获取，详见应用上下文Context。
说明
• 禁止直接使用上图中四级目录之前的目录名组成的路径字符串，否则可能导致后续应用版本因应用文件路径变化导致不兼容问题。
• 应通过Context属性获取应用文件路径，包括但不限于上图中绿色背景的路径。
应用文件路径具体说明及生命周期如下表所示。

目录名	Context属性名称	类型	说明
bundle	bundleCodeDir	安装文件路径	应用安装后的app的hap资源包所在目录；随应用卸载而清理。
base	NA	本设备文件路径	应用在本设备上存放持久化数据的目录，子目录包含files/、cache/、temp/和haps/；随应用卸载而清理。
database	databaseDir	数据库路径	应用在el1加密条件下存放通过分布式数据库服务操作的文件目录；随应用卸载而清理。
distributedfiles	distributedFilesDir	分布式文件路径	应用在el2加密条件下存放分布式文件的目录，应用将文件放入该目录可分布式跨设备直接访问；随应用卸载而清理。
files	filesDir	应用通用文件路径	应用在本设备内部存储上通用的存放默认长期保存的文件路径；随应用卸载而清理。
cache	cacheDir	应用缓存文件路径	应用在本设备内部存储上用于缓存下载的文件或可重新生成的缓存文件的路径，应用cache目录大小超过配额或者系统空间达到一定条件，自动触发清理该目录下文件；用户通过系统空间管理类应用也可能触发清理该目录。应用需判断文件是否仍存在，决策是否需重新缓存该文件。
preferences	preferencesDir	应用首选项文件路径	应用在本设备内部存储上通过数据库API存储配置类或首选项的目录；随应用卸载而清理。详见通过用户首选项实现数据持久化。
temp	tempDir	应用临时文件路径	应用在本设备内部存储上仅在应用运行期间产生和需要的文件，应用退出后即清理。

对于上述各类应用文件路径，常见使用场景如下：
• 安装文件路径
可以用于存储应用的代码资源数据，主要包括应用安装的HAP资源包、可重复使用的库文件以及插件资源等。此路径下存储的代码资源数据可以被用于动态加载。
• 数据库路径
仅用于保存应用的私有数据库数据，主要包括数据库文件等。此路径下仅适用于存储分布式数据库相关文件数据。
• 分布式文件路径
可以用于保存应用分布式场景下的数据，主要包括应用多设备共享文件、应用多设备备份文件、应用多设备群组协助文件。此路径下存储这些数据，使得应用更加适合多设备使用场景。
• 应用通用文件路径
可以用于保存应用的任何私有数据，主要包括用户持久性文件、图片、媒体文件以及日志文件等。此路径下存储这些数据，使得数据保持私有、安全且持久有效。
• 应用缓存文件路径
可以用于保存应用的缓存数据，主要包括离线数据、图片缓存、数据库备份以及临时文件等。此路径下存储的数据可能会被系统自动清理，因此不要存储重要数据。
• 应用首选项文件路径
可以用于保存应用的首选项数据，主要包括应用首选项文件以及配置文件等。此路径下仅适用于存储小量数据。
• 应用临时文件路径
可以用于保存应用的临时生成的数据，主要包括数据库缓存、图片缓存、临时日志文件、以及下载的应用安装包文件等。此路径下存储使用后即可删除的数据。

应用文件访问与管理

应用文件访问

说明

使用读写接口时，需注意可选项参数offset的设置。对于已存在且读写过的文件，文件偏移指针默认在上次读写操作的终止位置。

说明

使用流接口时，需注意流的及时关闭。同时流的异步接口应严格遵循异步接口使用规范，避免同步、异步接口混用。流接口不支持并发读写。

应用文件上传下载

说明

当前上传应用文件功能，仅支持上传应用缓存文件路径（cacheDir）下的文件。

使用上传下载模块接口，需申请相关权限：ohos.permission.INTERNET。

说明

当前网络资源文件仅支持下载至应用文件目录。

使用上传下载模块接口，需申请相关权限：ohos.permission.INTERNET。

应用及文件系统空间统计

• 获取文件系统数据分区剩余空间大小。

• 获取当前应用的存储空间大小。

向应用沙箱推送文件

1. 可以通过DevEco Studio向应用安装路径中放入目标文件，详见应用安装资源访问。

2. 在具备设备环境时，可以使用另一种更为灵活的方式，通过hdc工具来向设备中应用沙箱路径推送文件。即本文介绍的内容。

应用文件分享

• 基于URI分享方式，应用可分享单个文件，通过ohos.app.ability.wantConstant的wantConstant.Flags接口以只读或读写权限授权给其他应用。应用可通过ohos.file.fs的open()接口打开URI，并进行读写操作。当前OpenHarmony API 9仅支持临时授权，分享给其他应用的文件在被分享应用退出时权限被收回。

• 基于FD分享方式，应用可分享单个文件，通过ohos.file.fs的open接口以指定权限授权给其他应用。应用从Want中解析拿到FD后可通过ohos.file.fs的读写接口对文件进行读写。

• file：文件URI的标志。

• bundleName：该文件资源的属主。

• path：文件资源在应用沙箱中的路径。

说明

写权限分享时，同时授予读权限。

用户文件

用户文件概述

1. 用户文件存放在用户目录下，归属于该设备上登录的用户。

2. 用户文件存储位置主要分为内置存储、外置存储。

3. 应用对用户文件的创建、访问、删除等行为，需要提前获取用户授权，或由用户操作完成。

用户文件存储位置

• 用户特有的文件：这部分文件归属于登录该设备的用户，不同用户登录后，仅可看到该用户自己的文件。按照这些文件的特征/属性，以及用户/应用的使用习惯，可分为：
• 图片/视频类媒体文件
所具有的特征包括拍摄时间、地点、旋转角度、文件宽高等信息，以媒体文件的形式存储在系统中，通常是以所有文件、相册的形式对外呈现，不会展示其在系统中存储的具体位置。
• 音频类媒体文件
所具有的特征包括所属专辑、音频创作者、持续时间等信息，以媒体文件的形式存储在系统中，通常会以所有文件、专辑、作家等形式对外部呈现，不会展示其在系统中存储的具体位置。
• 其他文件（统称为文档类文件）
以普通文件的形式存储在系统中，该类文件既包括普通的文本文件、压缩文件等，又包括以普通文件形式存储的图片/视频、音频文件，该类文件通常是以目录树的形式对外展示。

• 多用户共享的文件：用户可以通过将文件放在共享文件区，实现多个用户之间文件的共享访问。
共享文件区的文件，也是以普通文件的形式存储在系统中，以目录树的形式对外展示。

用户文件访问框架

• 应用（即图中的文件访问客户端）若需访问用户文件，如选择一张照片或保存多个文档等，可以通过拉起“文件选择器应用”来实现。

• HarmonyOS系统预置了文件选择器应用FilePicker和文件管理器应用FileManager。
• FilePicker：系统预置应用，提供文件访问客户端选择和保存文件的能力，且不需要配置任何权限。FilePicker的使用指导请参见选择用户文件。
• FileManager：系统预置应用，终端用户可通过系统文件管理器实现查看文件、修改文件、删除文件（目录）、重命名文件（目录）、移动文件（目录）、创建文件（目录）等操作。

• File Access Framework（用户文件访问框架）的主要功能模块如下：
• File Access Helper：提供给文件管理器和文件选择器访问用户文件的API接口，应用不可直接调用。
• File Access ExtensionAbility：提供文件访问框架能力，由内卡文件管理服务UserFileManager和外卡文件管理服务ExternalFileManager组成，实现对应的文件访问功能。

选择与保存用户文件（FilePicker）

具体实现示例见官网。

选择用户文件

• PhotoViewPicker：适用于图片或视频类文件的选择与保存。

• DocumentViewPicker：适用于文档类文件的选择与保存。

• AudioViewPicker：适用于音频类文件的选择与保存。

保存用户文件

分布式文件系统

分布式文件系统概述

• 两台设备组网，用户可以利用一台设备上的编辑软件编辑另外一台设备上的文档。

• 平板保存的音乐，车载系统直接可见并可播放。

• 户外拍摄的照片，回家打开平板直接访问原设备拍摄的照片。

分布式文件系统架构

• distributedfile_daemon：主要负责设备上线监听、通过软总线建立链路，并根据分布式的设备安全等级执行不同的数据流转策略。

• hmdfs：实现在内核的网络文件系统，包括缓存管理、文件访问、元数据管理和冲突管理等。
• 缓存管理
• 设备分布式组网后，hmdfs提供文件的互访能力，但不会主动进行文件数据传输和拷贝。如果应用需要将数据保存到本地，需主动拷贝。
• hmdfs保证Close-to-Open的一致性，即一端写关闭后，另外一端可以读取到最新数据，不保证文件内容的实时一致性。
• 数据在远端写入，但是由于网络原因未及时回刷，文件系统会在下次网络接入时回刷本地，但是如果远端已修改则无法回刷。
• 文件访问
• 文件访问接口与本地一致（ohos.file.fs）。
• 如果文件在本地，则堆叠访问本地文件系统。
• 如果文件在其他设备，则同步网络访问远端设备文件。
说明
symlink：不支持。
• 元数据管理
• 分布式组网下，文件一端创建、删除、修改，另一端可以“立即”查看到最新文件，看到速度取决于网络情况。
• 远端设备离线后，该设备数据将不再在本端设备呈现。但由于设备离线的感知具有延迟，可能会造成部分消息4s超时，因此开发者需要考虑接口的网络超时或一些文件虽然可以看到，但实际设备可能已离线的场景。
• 冲突处理（难理解，可以找一些例子加强一下）
• 本地与远端冲突 ，远端文件被重命名，看到的同名文件是本地同名文件，远端文件被重命名。
• 远端多个设备冲突，以接入本设备ID为顺序，显示设备ID小的同名文件，其他文件被依次重命名。
• 如果组网场景，目录树下已经有远端文件，创建同名文件，提示文件已存在。
• 冲突文件显示_conflict_dev后依次加id，id从1自动递增。
• 同名目录之间仅融合不存在冲突，文件和远端目录同名冲突，远端目录后缀加_remote_directory。

设置分布式文件数据等级

接口说明

注意

1. 对于不满足安全等级的文件，跨设备仍然可以看到该文件，但是无权限打开访问该文件。

2. 分布式文件系统的数据等级默认为S3，应用可以主动设置文件的安全等级。

开发示例

跨设备文件访问

开发步骤