引言文件操作是移动应用最基础的能力之一——缓存图片需要写入临时目录用户数据需要持久化到文件日志需要追加写入文本。HarmonyOS NEXT 通过ohos.file.fs模块将 POSIX 风格的文件系统操作封装为 JavaScript/ArkTS 友好的同步/异步 API让开发者在应用沙箱内自由地进行目录浏览、文件读写、复制删除和属性查询。ohos.file.fs属于kit.CoreFileKit是应用沙箱文件系统的统一入口。它导出fileIo命名空间提供 50 余个文件操作函数——从基础的open/read/write/close到高级的listFile/stat/copyFile/moveFile/unlink覆盖文件生命周期的全流程。每个函数都有同步Sync后缀和异步Promise Callback两种版本。与 Android 的java.io.FileFileInputStreamJava 风格需要异常处理模板代码和 iOS 的FileManagerFoundation 框架Objective-C 风格不同鸿蒙将文件 I/O 设计为模块级命名空间函数通过fileIo.openSync()返回File句柄操作单个文件通过fileIo.listFileSync()目录遍历通过fileIo.statSync()查询元数据——简洁直接无复杂的类继承体系。本文将深入讲解ohos.file.fs的目录浏览、文件读写、元数据查询和批量操作四大核心能力并构建一个文件系统实验室Demo——在应用沙箱内完成文件创建、查看、复制和删除的全流程操作。一、API 架构命名空间 File 句柄模式1.1 核心设计理念ohos.file.fs的设计核心是命名空间函数 File 句柄的双层模型。导入时使用fileIo命名空间importfileIofromohos.file.fs;命名空间提供两类函数路径级操作直接操作文件路径无需 File 句柄listFileSync(path: string): string[]— 列出目录内容statSync(path: string): Stat— 获取文件元数据readTextSync(path: string): string— 读取文本文件全部内容copyFileSync(src: string, dest: string): void— 复制文件moveFileSync(src: string, dest: string): void— 移动文件unlinkSync(path: string): void— 删除文件accessSync(path: string): boolean— 检查文件是否可访问mkdirSync(path: string): void/rmdirSync(path: string): void— 创建/删除目录句柄级操作需要先openSync获取 File 对象openSync(path: string, mode?: number): File— 打开文件返回句柄writeSync(fd: number, data: string | ArrayBuffer): void— 向文件描述符写入数据readSync(fd: number, buffer: ArrayBuffer, options?: object): number— 从文件描述符读取数据closeSync(file: File): void— 关闭文件释放句柄这种双层设计让简单操作可以直接走路径级 API如整个读取小文件用readTextSync复杂操作走 File 句柄获得精确控制如日志追加写入用openSync(path, APPEND)writeSync(fd, line)closeSync。1.2 sandbox 沙箱限制所有文件操作都限制在应用沙箱目录内getContext(this).filesDir— 应用私有文件目录/data/storage/el2/base/haps/entry/files/getContext(this).cacheDir— 缓存目录系统可能在空间不足时清空getContext(this).tempDir— 临时目录应用退出后可能清空尝试访问沙箱外的路径会抛出权限异常。这是鸿蒙的安全模型——与 iOS 的沙箱机制类似比 Android 的存储权限更严格。// 合法访问沙箱内文件constfilesDirgetContext(this).filesDir;constcontentfileIo.readTextSync(filesDir/note.txt);// 非法尝试访问沙箱外路径会抛异常// fileIo.readTextSync(/system/etc/hosts); // ERROR1.3 OpenMode 打开模式常量fileIo.OpenMode命名空间提供文件打开模式常量遵循 POSIX 文件权限惯例八进制值常量含义值READ_ONLY只读0o0WRITE_ONLY只写0o1READ_WRITE读写0o2CREATE文件不存在时创建0o100TRUNC打开时清空文件0o1000APPEND追加模式0o2000多个模式通过按位或|组合使用// 创建新文件仅写入 创建 清空原有内容constfilefileIo.openSync(path,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.TRUNC);// 追加写入日志constlogFilefileIo.openSync(path,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.APPEND);二、目录浏览与文件发现2.1 listFileSync —— 列出目录内容fileIo.listFileSync(path: string): string[]返回目录下所有文件和子目录的名称数组。这是最简单的文件列表 API——不返回元数据只返回名称字符串。constfilesDirgetContext(this).filesDir;constnamesfileIo.listFileSync(filesDir);console.log(文件数量: names.length.toString());// names [note.txt, config.json, cache, download.tmp]返回的名称只是文件名不包含完整路径。区分文件和目录需要额外调用statSync()检查mode字段——但 Demo 中做了简化处理因为可以通过listFileSync遍历到的都可能是文件或目录。2.2 statSync —— 获取文件元数据fileIo.statSync(path: string): Stat返回一个Stat接口对象包含文件的完整元数据interfaceStat{readonlyino:bigint;// inode 号readonlysize:bigint;// 文件大小字节readonlymode:number;// 文件权限八进制形式如 0o644readonlyuid:number;// 所有者 UIDreadonlygid:number;// 组 IDreadonlyatime:bigint;// 最后访问时间毫秒时间戳readonlymtime:bigint;// 最后修改时间毫秒时间戳}其中mode可以用八进制格式显示给用户——Number(st.mode).toString(8)将其转换为33188这样的八进制字符串实际上底层是0o100644即普通文件 权限 644。conststfileIo.statSync(fullPath);constsizeMB(Number(st.size)/(1024*1024)).toFixed(2) MB;constmtimenewDate(Number(st.mtime));constperm0oNumber(st.mode).toString(8);console.log(文件大小: sizeMB, 修改时间: mtime, 权限: perm);size和mtime是bigint类型——需要用Number()转换后才能参与字符串拼接或数学运算。三、文件读写操作3.1 readTextSync —— 最简单的文本读取fileIo.readTextSync(path: string): string一次性读取整个文件并以 UTF-8 文本返回。适用于配置文件、JSON 数据和日志文件等小文件场景。try{constcontentfileIo.readTextSync(fullPath);this.fileContentcontent;console.log(读取到 content.length.toString() 个字符);}catch(e){console.error(读取失败);}文件不存在或不可读时会抛出异常需要 try/catch 保护。3.2 openSync writeSync closeSync —— 三步写文件创建或写入文件需要三个步骤// 1. 打开文件创建 只写 清空constfilefileIo.openSync(fullPath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.TRUNC);// 2. 写入内容fileIo.writeSync(file.fd,Hello HarmonyOS!\n第二行内容);// 3. 关闭释放fileIo.closeSync(file);writeSync接受string | ArrayBuffer类型——写入文本直接用字符串写入二进制数据用ArrayBuffer。Demo 中封装了创建文件的操作privatecreateFile():void{constfullPaththis.currentDir/this.newFileName.trim();constfilefileIo.openSync(fullPath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.TRUNC);fileIo.writeSync(file.fd,this.newFileContent);fileIo.closeSync(file);this.refreshFileList();}用户输入文件名和内容后点击创建文件出现在目录列表中。四、文件复制、删除与重命名4.1 copyFileSync —— 按路径复制fileIo.copyFileSync(src: string, dest: string): void直接将源文件复制到目标路径。不需要先读取内容再写入——系统内部直接使用高效的内核复制。// 复制文件note.txt → note_copy.txtconstsrcPaththis.currentDir/name;constdestPaththis.currentDir/name.replace(/(\.[^.])$/,_copy$1);fileIo.copyFileSync(srcPath,destPath);Demo 中在每个文件旁边放了复制按钮点击后自动生成原文件名_copy.扩展名格式的副本。4.2 unlinkSync —— 删除文件fileIo.unlinkSync(path: string): void删除指定路径的文件。注意这不是delete或remove——POSIX 系统中删除文件的系统调用是unlink移除目录项到 inode 的链接。constfullPaththis.currentDir/name;fileIo.unlinkSync(fullPath);Demo 中每个文件旁边有红色删除按钮点击后立即删除并刷新目录列表。4.3 moveFileSync / renameSync —— 重命名fileIo.moveFileSync(src: string, dest: string): void移动或重命名文件。在同一文件系统内移动和重命名是同一个操作只修改目录项不复制数据。// 重命名fileIo.moveFileSync(filesDir/old_name.txt,filesDir/new_name.txt);// 跨目录移动fileIo.moveFileSync(filesDir/data.txt,cacheDir/data_backup.txt);五、实战 Demo文件系统实验室5.1 页面设计文件系统实验室页面分为五个功能区域快捷操作栏刷新列表按钮重新读取目录 创建文件按钮展开/收起创建面板文件创建面板可折叠TextInput 输入文件名默认 “note.txt” TextArea 输入文件内容默认 “Hello HarmonyOS!” 绿色创建按钮目录内容列表展示当前目录下所有文件名每个文件右侧有三个操作按钮——“查看”蓝色“复制”天蓝“删除”红色。目录项不显示操作按钮文件内容查看面板点击查看后展开显示文件属性卡片大小/修改时间/权限三列 文件内容等宽字体、灰色背景操作日志记录所有操作——列目录、创建、查看、复制、删除及其结果5.2 核心实现状态模型设计StatefileList:FileItem[][];StatecurrentDir:string;StateselectedFile:string;StatefileContent:string;StatefileSize:string--;StatefileMtime:string--;StatefileMode:string--;StatenewFileName:stringnote.txt;StatenewFileContent:stringHello HarmonyOS!;StateshowCreate:booleanfalse;StateshowContent:booleanfalse;Statelogs:LogEntry[][];设计要点fileList存储文件列表名称 是否为目录每次操作后通过refreshFileList()重新读取selectedFile记录当前查看的文件名showContent控制查看面板的显示/隐藏showCreate控制创建面板的展开/折叠文件属性size/mtime/mode只在查看文件时通过statSync()获取目录列表刷新privaterefreshFileList():void{try{constfilesfileIo.listFileSync(this.currentDir);this.fileList[];for(leti0;ifiles.length;i){try{constfullPaththis.currentDir/files[i];conststfileIo.statSync(fullPath);this.fileList.push({name:files[i],isDir:(Number(st.mode)0o40000)!0}asFileItem);}catch(e){this.fileList.push({name:files[i],isDir:false}asFileItem);}}}catch(e){this.addLog(列出目录失败,error);}}通过检查mode的0o40000位来判断是否为目录——这是 POSIX 文件类型的掩码。5.3 交互方式Demo 提供四个核心交互点浏览目录进入页面自动列出filesDir下的所有文件点击刷新列表可重新读取创建文件点击创建文件展开面板 → 输入文件名和内容 → 点击创建按钮 → 文件出现在列表中 → 面板自动折叠查看文件点击列表中任意文件的查看按钮 → 展开内容面板 → 显示文件属性大小/修改时间/权限八进制值 完整文件内容等宽字体最多 20 行管理文件每个文件提供复制创建_copy后缀副本和删除立即移除按钮六、总结ohos.file.fs是 HarmonyOS NEXT 中应用沙箱文件操作的标准模块。通过本文的学习你应该已经掌握目录浏览listFileSync(path)列出目录内容返回名称数组statSync(path)获取文件元数据size/mtime/mode 等 Stat 接口文件读写readTextSync(path)一次性读取文本文件openSync(path, mode)writeSync(fd, data)closeSync(file)三步创建和写入文件批量操作copyFileSync(src, dest)复制文件moveFileSync(src, dest)移动/重命名unlinkSync(path)删除文件打开模式OpenMode.CREATE | WRITE_ONLY | TRUNC创建并覆盖写入、OpenMode.CREATE | WRITE_ONLY | APPEND创建并追加写入沙箱限制所有操作限制在filesDir/cacheDir/tempDir内访问沙箱外路径会抛异常ohos.file.fs的最佳使用模式可以总结为listFileSync 发现文件 → statSync 查看属性 → readTextSync 读取小文件内容 → openSync writeSync closeSync 三步创建/写入 → copyFileSync/unlinkSync 复制/删除。所有操作都在沙箱内使用同步版 API 简化代码异常通过 try/catch 保护。在 HarmonyOS 的文件管理体系中ohos.file.fs定位于基础文件 I/O与ohos.file.statvfs文件系统统计、ohos.file.picker文件选择器和ohos.file.photoPicker照片选择器形成完整的文件能力栈。它是应用本地数据持久化最底层的基石——无论是日志写入、JSON 配置存储还是内容缓存最终都依赖于ohos.file.fs提供的沙箱文件操作。ohos.file.fs属于kit.CoreFileKit所有 API 都提供 Sync/Async 配对版本操作范围限制在应用沙箱内无需额外权限。