​
OpenHarmony文件存储的用法详解
 
​

本文将介绍对文件的一些基本操作，如：新建目录、打开文件、写文件、删除文件等，同时介绍如何获取、添加媒体资源文件。

主要涉及到如下两个接口：

  • @ohos.fileio

    该模块提供文件存储管理能力，包括文件基本管理、文件目录管理、文件信息统计、文件流式读写等常用功能。

  • @ohos.fileManager

    该模块提供公共文件访问和管理的服务接口，向下对接底层文件管理服务，如媒体库、外卡管理；向上对应用程序提供公共文件查询、创建的能力。

@ohos.fileio用法详解

导入模块

import fileio from '@ohos.fileio';

使用说明

使用该功能模块对文件/目录进行操作前，需要先获取当前应用的沙箱路径，获取方式及其接口用法如下：

应用在设备上与文件沙箱相对应的路径为：/data/app/el2/100/base/bundleName/haps/entry，其中bundleName表示当前应用的包名

  • FA模型获取当前应用的沙箱路径：

    import featureAbility from '@ohos.ability.featureAbility'; let context = featureAbility.getContext(); ​ context.getFilesDir().then((FilesDir) => {      console.log(FilesDir) // /data/storage/el2/base/haps/entry/files }) ​ context.getCacheDir().then((CacheDir) => {      console.log(CacheDir) // /data/storage/el2/base/haps/entry/cache })

  • Stage模型获取当前应用的沙箱路径

    //步骤一：在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ //步骤二：获取应用沙箱下的不同文件夹 @Entry @Component struct Index {     //...     Button("Stage获取context中的Dir").fontSize(30).margin({bottom:10})        .onClick(()=>{   // /data/storage/el2/base/haps/entry/cache         console.log("context.cacheDir : " + globalThis.context.cacheDir);   // /data/storage/el2/base/haps/entry/temp         console.log("context.tempDir : " + globalThis.context.tempDir);   // /data/storage/el2/base/haps/entry/files         console.log("context.filesDir : " + globalThis.context.filesDir);   // /data/storage/el2/database/entry         console.log("context.databaseDir : " + globalThis.context.databaseDir);   // /data/storage/el2/base/haps/entry/storage         console.log("context.preferencesDir : " + globalThis.context.preferencesDir);   // /data/storage/el1/bundle         console.log("context.bundleCodeDir : " + globalThis.context.bundleCodeDir);   // /data/storage/el2/distributedfiles/entry         console.log("context.distributedFilesDir : " + globalThis.context.distributedFilesDir);    })     //... }

本文以下代码示例均基于Stage模型中Promise类型的接口展示

新建目录

mkdir(path:string, mode?: number): Promise<void>

创建目录，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
path string 是 待创建目录的应用沙箱路径。
mode number 否 创建目录的权限，可给定如下权限，以按位或的方式追加权限，默认给定0o775。 - 0o775：所有者具有读、写及可执行权限，其余用户具有读及可执行权限。 - 0o700：所有者具有读、写及可执行权限。 - 0o400：所有者具有读权限。 - 0o200：所有者具有写权限。 - 0o100：所有者具有可执行权限。 - 0o070：所有用户组具有读、写及可执行权限。 - 0o040：所有用户组具有读权限。 - 0o020：所有用户组具有写权限。 - 0o010：所有用户组具有可执行权限。 - 0o007：其余用户具有读、写及可执行权限。 - 0o004：其余用户具有读权限。 - 0o002：其余用户具有写权限。 - 0o001：其余用户具有可执行权限。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ //在应用沙箱路径下新建testDir目录 let fileDir = globalThis.context.filesDir fileio.mkdir(fileDir+"/testDir",0o775).then(() =>{  console.log("make dir testDir success !") }).catch(error =>{     console.error("make dir testDir failed with error : " + error) })

新建/打开文件(open)

open(path: string, flags?: number, mode?: number): Promise<number>

打开文件，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
path string 是 待打开文件的应用沙箱路径。
flags number 否 打开文件的选项，必须指定如下选项中的一个，默认以只读方式打开： - 0o0：只读打开。 - 0o1：只写打开。 - 0o2：读写打开。 同时，也可给定如下选项，以按位或的方式追加，默认不给定任何额外选项： - 0o100：若文件不存在，则创建文件。使用该选项时必须指定第三个参数 mode。 - 0o200：如果追加了0o100选项，且文件已经存在，则出错。 - 0o1000：如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。 - 0o2000：以追加方式打开，后续写将追加到文件末尾。 - 0o4000：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。 - 0o200000：如果path不指向目录，则出错。 - 0o400000：如果path指向符号链接，则出错。 - 0o4010000：以同步IO的方式打开文件。
mode number 否 若创建文件，则指定文件的权限，可给定如下权限，以按位或的方式追加权限，默认给定0o666。 - 0o666：所有者具有读、写权限，所有用户组具有读、写权限，其余用户具有读、写权限。 - 0o700：所有者具有读、写及可执行权限。 - 0o400：所有者具有读权限。 - 0o200：所有者具有写权限。 - 0o100：所有者具有可执行权限。 - 0o070：所有用户组具有读、写及可执行权限。 - 0o040：所有用户组具有读权限。 - 0o020：所有用户组具有写权限。 - 0o010：所有用户组具有可执行权限。 - 0o007：其余用户具有读、写及可执行权限。 - 0o004：其余用户具有读权限。 - 0o002：其余用户具有写权限。 - 0o001：其余用户具有可执行权限。

返回值：

类型 说明
Promise<number> Promise对象。返回打开文件的文件描述符。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ //flags参数设置为0o100，如果open的文件不存在，就会创建该文件 let fileDir = globalThis.context.filesDir fileio.open(fileDir+"/newFile1.txt",0o100,0o666).then(num => {     console.log("open file "+ num) }).catch(error =>{      console.error("open file filed with error : " + error) })

 

获取文件信息(stat)

stat(path: string): Promise<Stat>

获取文件信息，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
path string 是 待获取文件的应用沙箱路径。

返回值：

类型 说明
Promise<Stat> Promise对象。返回文件的具体信息。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ let path = globalThis.context.filesDir+"/newFile1.txt" fileio.stat(path).then(function(stat){     console.log("getFileInfo succeed");     console.log("stat.dev:"+ stat.dev);     console.log("stat.ino:"+ stat.ino);     console.log("stat.mode:"+ stat.mode);     console.log("stat.nlink:"+ stat.nlink);     console.log("stat.uid:"+ stat.uid);     console.log("stat.gid:"+ stat.gid);     console.log("stat.rdev:"+ stat.rdev);     console.log("stat.size:"+ stat.size);     console.log("stat.blocks:"+ stat.blocks);     console.log("stat.atime:"+ stat.atime);     console.log("stat.mtime:"+ stat.mtime);     console.log("stat.ctime:"+ stat.ctime); }).catch(error =>{     console.error("getFileInfo failed with error:"+ error); });

 

将数据写入文件(write)

write(fd: number, buffer: ArrayBuffer | string, options?: { offset?: number; length?: number; position?: number; encoding?: string; }): Promise<number>

将数据写入文件，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
fd number 是 待写入文件的文件描述符。
buffer ArrayBuffer | string 是 待写入文件的数据，可来自缓冲区或字符串。
options Object 否 支持如下选项： - offset，number类型，表示期望写入数据的位置相对于数据首地址的偏移。可选，默认为0。 - length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。 - encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。 约束：offset+length<=buffer.size。

返回值：

类型 说明
Promise<number> Promise对象。返回实际写入的长度。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ let fileDir = globalThis.context.filesDir fileio.open(fileDir+"/newFile1.txt",0o2,0o666).then(fd => {        console.log("fd : " + fd)        fileio.write(fd,"abcd").then(num => {           console.log(" write file succeed , num : " + num)        }).catch(error =>{           console.error("write file failed with error : " + error )        }) ​         //关闭文件描述符         fileio.close(fd).then(()=>{           console.log("close succeed , fd : " + fd)        }).catch(error =>{           console.error("close failed with error : " + error)        }) })

 

从文件读取数据(read)

read(fd: number, buffer: ArrayBuffer, options?: { offset?: number; length?: number; position?: number; }): Promise<ReadOut>

从文件读取数据，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
fd number 是 待读取文件的文件描述符。
buffer ArrayBuffer 是 用于保存读取到的文件数据的缓冲区。
options Object 否 支持如下选项： - offset，number类型，表示将数据读取到缓冲区的位置，即相对于缓冲区首地址的偏移。可选，默认为0。 - length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。 约束：offset+length<=buffer.size。

返回值：

类型 说明
Promise<ReadOut> Promise对象。返回读取的结果。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) {  //...  globalThis.context = this.context;  //... } ​ let fileDir = globalThis.context.filesDir let fd = fileio.openSync(fileDir+"/newFile1.txt", 0o2); let buf = new ArrayBuffer(4096); fileio.read(fd, buf).then(function(readOut){     console.log("read file data succeed");     console.log(String.fromCharCode.apply(null, new Uint8Array(readOut.buffer))); }).catch(error =>{     console.error("read file data failed with error:"+ error); });

 

删除文件(unlink)

unlink(path:string): Promise<void>

删除文件，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
path string 是 待删除文件的应用沙箱路径。

返回值：

类型 说明
Promise<void> Promise对象。无返回值。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) { //... globalThis.context = this.context; //... } let fileDir = globalThis.context.filesDir fileio.unlink(fileDir+"/newFile1.txt").then(function(){ console.log("unlink file succeed"); }).catch(error =>{ console.error("unlink file failed with error:"+ error); });

 

删除目录(rmdir)

rmdir(path: string): Promise<void>

删除目录，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
path string 是 待删除目录的应用沙箱路径。

返回值：

类型 说明
Promise<void> Promise对象。无返回值。

代码示例:

//在应用的MainAbility.ts的onCreate生命周期函数中设置globalThis.context onCreate(want, launchParam) { //... globalThis.context = this.context; //... } let fileDir = globalThis.context.filesDir fileio.rmdir(fileDir+"/testDir").then(function() { console.info("rmdir succeed"); }).catch(error =>{ console.error("rmdir failed with error:"+ error); });

 

文件具体信息(Stat)

在调用Stat的方法前，需要先通过stat()方法（同步或异步）来构建一个Stat实例。

系统能力：以下各项对应的系统能力均为SystemCapability.FileManagement.File.FileIO。

属性

名称 参数类型 可读 可写 说明
dev number 是 否 标识包含该文件的主设备号。
ino number 是 否 标识该文件。通常同设备上的不同文件的INO不同。
mode number 是 否 表示文件类型及权限，其首 4 位表示文件类型，后 12 位表示权限。各特征位的含义如下： - 0o170000：可用于获取文件类型的掩码。 - 0o140000：文件是套接字。 - 0o120000：文件是符号链接。 - 0o100000：文件是一般文件。 - 0o060000：文件属于块设备。 - 0o040000：文件是目录。 - 0o020000：文件是字符设备。 - 0o010000：文件是具名管道，即FIFO。 - 0o0700：可用于获取用户权限的掩码。 - 0o0400：用户读，对于普通文件，所有者可读取文件；对于目录，所有者可读取目录项。 - 0o0200：用户写，对于普通文件，所有者可写入文件；对于目录，所有者可创建/删除目录项。 - 0o0100：用户执行，对于普通文件，所有者可执行文件；对于目录，所有者可在目录中搜索给定路径名。 - 0o0070：可用于获取用户组权限的掩码。 - 0o0040：用户组读，对于普通文件，所有用户组可读取文件；对于目录，所有用户组可读取目录项。 - 0o0020：用户组写，对于普通文件，所有用户组可写入文件；对于目录，所有用户组可创建/删除目录项。 - 0o0010：用户组执行，对于普通文件，所有用户组可执行文件；对于目录，所有用户组是否可在目录中搜索给定路径名。 - 0o0007：可用于获取其他用户权限的掩码。 - 0o0004：其他读，对于普通文件，其余用户可读取文件；对于目录，其他用户组可读取目录项。 - 0o0002：其他写，对于普通文件，其余用户可写入文件；对于目录，其他用户组可创建/删除目录项。 - 0o0001：其他执行，对于普通文件，其余用户可执行文件；对于目录，其他用户组可在目录中搜索给定路径名。
nlink number 是 否 文件的硬链接数。
uid number 是 否 文件所有者的ID。
gid number 是 否 文件所有组的ID。
rdev number 是 否 标识包含该文件的从设备号。
size number 是 否 文件的大小，以字节为单位。仅对普通文件有效。
blocks number 是 否 文件占用的块数，计算时块大小按512B计算。
atime number 是 否 上次访问该文件的时间，表示距1970年1月1日0时0分0秒的秒数。
mtime number 是 否 上次修改该文件的时间，表示距1970年1月1日0时0分0秒的秒数。
ctime number 是 否 最近改变文件状态的时间，表示距1970年1月1日0时0分0秒的秒数。

 

文件变化监听(Watcher7+)

Watcher是文件变化监听的实例，调用Watcher.stop()方法（同步或异步）来停止文件监听。

stop7+

stop(): Promise<void>

关闭watcher监听，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

let filename = path +"/test.txt"; let watcher = fileio.createWatcher(filename, 1, function(number){ console.info("Monitoring times: "+number); }); watcher.stop().then(()=> { console.info("close watcher succeed"); }).catch(error =>{ console.error("close watcher failed with error : " + error) });

stop7+

stop(callback: AsyncCallback<void>): void

关闭watcher监听，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 以异步方法关闭watcher监听之后的回调。

代码示例:

let filename = path +"/test.txt"; let watcher = fileio.createWatcher(filename, 1, number =>{ console.info("Monitoring times: "+number); }); watcher.stop(() => { console.info("close watcher succeed"); })

文件流(Stream)

在调用Stream的方法前，需要先通过createStream()方法（同步或异步）来构建一个Stream实例。

close7+

close(): Promise<void>

关闭文件流，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
Promise<void> Promise对象。返回表示异步关闭文件流的结果。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.close().then(function(){ console.info("close fileStream succeed"); }).catch(error =>{ console.error("close fileStream failed with error:"+ error); });

close7+

close(callback: AsyncCallback<void>): void

异步关闭文件流，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 异步关闭文件流之后的回调。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.close(function (err) { // do something });

closeSync

closeSync(): void

同步关闭文件流。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.closeSync();

flush7+

flush(): Promise<void>

刷新文件流，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
Promise<void> Promise对象。返回表示异步刷新文件流的结果。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.flush().then(function (){ console.info("flush succeed"); }).catch(error =>{ console.error("flush failed with error:"+ error); });

flush7+

flush(callback: AsyncCallback<void>): void

异步刷新文件流，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 异步刷新文件流后的回调函数。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.flush(function (err) { // do something });

flushSync7+

flushSync(): void

同步刷新文件流。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.flushSync();

write7+

write(buffer: ArrayBuffer | string, options?: { offset?: number; length?: number; position?: number; encoding?: string; }): Promise<number>

将数据写入流文件，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer | string 是 待写入文件的数据，可来自缓冲区或字符串。
options Object 否 支持如下选项： - offset，number类型，表示期望写入数据的位置相对于数据首地址的偏移。可选，默认为0。 - length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。 - encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。 约束：offset+length<=buffer.size。

返回值：

类型 说明
Promise<number> Promise对象。返回实际写入的长度。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.write("hello, world",{offset: 1,length: 5,position: 5,encoding :'utf-8'}).then(function (number){ console.info("write succeed and size is:"+ number); }).catch(error =>{ console.error("write failed with error:"+ error); });

write7+

write(buffer: ArrayBuffer | string, options: { offset?: number; length?: number; position?: number; encoding?: string; }, callback: AsyncCallback<number>): void

将数据写入流文件，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer | string 是 待写入文件的数据，可来自缓冲区或字符串。
options Object 否 支持如下选项： - offset，number类型，表示期望写入数据的位置相对于数据首地址的偏移。可选，默认为0。 - length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。 - encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。 约束：offset+length<=buffer.size。
callback AsyncCallback<number> 是 异步写入完成后执行的回调函数。

代码示例:

let ss= fileio.createStreamSync(path, "r+"); ss.write("hello, world", {offset: 1, length: 5, position: 5, encoding :'utf-8'}, function (err, bytesWritten) { if (bytesWritten) { // do something console.info("write succeed and size is:"+ bytesWritten); } });

writeSync7+

writeSync(buffer: ArrayBuffer | string, options?: { offset?: number; length?: number; position?: number; encoding?: string; }): number

以同步方法将数据写入流文件。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer | string 是 待写入文件的数据，可来自缓冲区或字符串。
options Object 否 支持如下选项： - offset，number类型，表示期望写入数据的位置相对于数据首地址的偏移。可选，默认为0。 - length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。 - encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。 约束：offset+length<=buffer.size。

返回值：

类型 说明
number 实际写入的长度。

代码示例:

let ss= fileio.createStreamSync(path,"r+"); let num = ss.writeSync("hello, world", {offset: 1, length: 5, position: 5, encoding :'utf-8'});

read7+

read(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }): Promise<ReadOut>

从流文件读取数据，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer 是 用于读取文件的缓冲区。
options Object 否 支持如下选项： - offset，number类型，表示将数据读取到缓冲区的位置，即相对于缓冲区首地址的偏移。可选，默认为0。 - length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。 约束：offset+length<=buffer.size。

返回值：

类型 说明
Promise<ReadOut> Promise对象。返回读取的结果。

代码示例:

let ss = fileio.createStreamSync(path, "r+"); ss.read(new ArrayBuffer(4096), {offset: 1, length: 5, position: 5}).then(function (readOut){ console.info("read data succeed"); console.log(String.fromCharCode.apply(null, new Uint8Array(readOut.buffer))); }).catch(error =>{ console.error("read data failed with error:"+ error); });

read7+

read(buffer: ArrayBuffer, options: { position?: number; offset?: number; length?: number; }, callback: AsyncCallback<ReadOut>): void

从流文件读取数据，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer 是 用于读取文件的缓冲区。
options Object 否 支持如下选项： - offset，number类型，表示将数据读取到缓冲区的位置，即相对于缓冲区首地址的偏移。可选，默认为0。 - length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。 约束：offset+length<=buffer.size。
callback AsyncCallback<ReadOut> 是 异步从流文件读取数据之后的回调。

代码示例:

let ss = fileio.createStreamSync(path, "r+"); ss.read(new ArrayBuffer(4096),{offset: 1, length: 5, position: 5},function (err, readOut) { if (readOut) { console.info("read data succeed"); console.log(String.fromCharCode.apply(null, new Uint8Array(readOut.buffer))); } });

readSync7+

readSync(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }): number

以同步方法从流文件读取数据。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
buffer ArrayBuffer 是 用于读取文件的缓冲区。
options Object 否 支持如下选项： - offset，number类型，表示将数据读取到缓冲区的位置，即相对于缓冲区首地址的偏移。可选，默认为0。 - length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度减去偏移长度。 - position，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。 约束：offset+length<=buffer.size。

返回值：

类型 说明
number 实际读取的长度。

代码示例:

let ss = fileio.createStreamSync(path, "r+"); let num = ss.readSync(new ArrayBuffer(4096), {offset: 1, length: 5, position: 5});

 

管理目录(Dir)

在调用Dir的方法前，需要先通过opendir方法（同步或异步）来构建一个Dir实例。

read

read(): Promise<Dirent>

读取下一个目录项，使用Promise异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
Promise<Dirent> Promise对象。返回表示异步读取目录项的结果。

代码示例:

dir.read().then(function (dirent){ console.log("read succeed:"+JSON.stringify(dirent)); }).catch(error =>{ console.error("read failed with error:"+ error); });

read

read(callback: AsyncCallback<Dirent>): void

读取下一个目录项，使用callback异步回调。

系统能力：SystemCapability.FileManagement.File.FileIO

参数：

参数名 类型 必填 说明
callback AsyncCallback<Dirent> 是 异步读取下一个目录项之后的回调。

代码示例:

dir.read(function (err, dirent) { if (dirent) { // do something console.log("read succeed:"+JSON.stringify(dirent)); } });

readSync

readSync(): Dirent

同步读取下一个目录项。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
Dirent 表示一个目录项。

代码示例:

let dirent = dir.readSync();

close7+

close(): Promise<void>

异步关闭目录，使用promise形式返回结果。目录被关闭后，Dir中持有的文件描述将被释放，后续将无法从Dir中读取目录项。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

dir.close().then(err =>{ console.info("close dir successfully"); });

close7+

close(callback: AsyncCallback<void>): void

异步关闭目录，使用callback形式返回结果。目录被关闭后，Dir中持有的文件描述将被释放，后续将无法从Dir中读取目录项。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

dir.close(error =>{ if(error){ console.log("close dir successfully"); }else{ console.error("close dir failed with error : " + error) } });

closeSync

closeSync(): void

用于关闭目录。目录被关闭后，Dir中持有的文件描述将被释放，后续将无法从Dir中读取目录项。

系统能力：SystemCapability.FileManagement.File.FileIO

代码示例:

dir.closeSync();

Dirent

在调用Dirent的方法前，需要先通过dir.read()方法（同步或异步）来构建一个Dirent实例。

系统能力：以下各项对应的系统能力均为SystemCapability.FileManagement.File.FileIO。

属性

名称 参数类型 可读 可写 说明
name string 是 否 目录项的名称。

isBlockDevice

isBlockDevice(): boolean

用于判断当前目录项是否是块特殊文件。一个块特殊文件只能以块为粒度进行访问，且访问的时候带缓存。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是块特殊设备。

代码示例:

let dir = fileio.opendirSync(path); let isBLockDevice = dir.readSync().isBlockDevice();

isCharacterDevice

isCharacterDevice(): boolean

用于判断当前目录项是否是字符特殊设备。一个字符特殊设备可进行随机访问，且访问的时候不带缓存。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是字符特殊设备。

代码示例:

let dir = fileio.opendirSync(path); let isCharacterDevice = dir.readSync().isCharacterDevice();

isDirectory

isDirectory(): boolean

用于判断当前目录项是否是目录。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是目录。

代码示例:

let dir = fileio.opendirSync(path); let isDirectory = dir.readSync().isDirectory();

isFIFO

isFIFO(): boolean

用于判断当前目录项是否是命名管道（有时也称为FIFO）。命名管道通常用于进程间通信。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是FIFO。

代码示例:

let dir = fileio.opendirSync(path); let isFIFO = dir.readSync().isFIFO();

isFile

isFile(): boolean

用于判断当前目录项是否是普通文件。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是普通文件。

代码示例:

let dir = fileio.opendirSync(path); let isFile = dir.readSync().isFile();

isSocket

isSocket(): boolean

用于判断当前目录项是否是套接字。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是套接字。

代码示例:

let dir = fileio.opendirSync(path); let isSocket = dir.readSync().isSocket();

isSymbolicLink

isSymbolicLink(): boolean

用于判断当前目录项是否是符号链接。

系统能力：SystemCapability.FileManagement.File.FileIO

返回值：

类型 说明
boolean 表示当前目录项是否是符号链接。

代码示例:

let dir = fileio.opendirSync(path); let isSymbolicLink = dir.readSync().isSymbolicLink();

 

@ohos.fileManager用法详解

该模块提供公共文件访问和管理的服务接口，向下对接底层文件管理服务，如媒体库、外卡管理；向上对应用程序提供公共文件查询、创建的能力。

配置权限

在进行相机功能开发前需要先在配置文件中配置需要的权限信息。

Stage 模型配置 module.json5

{ "module":{ ... "requestPermissions": [ { "name": "ohos.permission.READ_MEDIA" }, { "name": "ohos.permission.WRITE_MEDIA" } ] } ... }

FA 模型配置 config.json

{ ... "module":{ ... "reqPermissions": [ { "name": "ohos.permission.READ_MEDIA" }, { "name": "ohos.permission.WRITE_MEDIA" } ] } ... }

请求用户授权

申请ohos.permission.READ_MEDIA权限

import bundle from '@ohos.bundle'; import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; async requestPermissionReadMedia() { var permissionNameUser = "ohos.permission.READ_MEDIA"; // 需要动态申请的权限 var bundleFlag = 0; // 数字枚举 var tokenID = undefined; var userID = 100; // 系统设置默认100 let bundleName = " " //此处填写当前应用的包名 var appInfo = await bundle.getApplicationInfo(bundleName, bundleFlag, userID);// 获取应用信息 tokenID = appInfo.accessTokenId; // 检验权限是否已授权 var atManager = abilityAccessCtrl.createAtManager(); var result = await atManager.verifyAccessToken(tokenID, permissionNameUser); if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { // 执行操作 console.log("ohos.permission.READ_MEDIA PERMISSION_GRANTED") } else { // 申请动态授权，使用接口：requestPermissionsFromUser console.log("start request permission ohos.permission.READ_MEDIA") globalThis.context.requestPermissionsFromUser([permissionNameUser], 1, (e, res) => { ... // 自己的逻辑 }) } }

申请ohos.permission.WRITE_MEDIA权限

async requestPermissionWriteMedia() { var permissionNameUser = "ohos.permission.WRITE_MEDIA"; // 需要动态申请的权限 var bundleFlag = 0; // 数字枚举 var tokenID = undefined; var userID = 100; // 系统设置默认100 // 获取应用信息 let bundleName = " " //此处填写当前应用的包名 var appInfo = await bundle.getApplicationInfo(bundleName, bundleFlag, userID); tokenID = appInfo.accessTokenId; // 检验权限是否已授权 var atManager = abilityAccessCtrl.createAtManager(); var result = await atManager.verifyAccessToken(tokenID, permissionNameUser); if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { // 执行操作 console.log("ohos.permission.WRITE_MEDIA PERMISSION_GRANTED") } else { // 申请动态授权，使用接口：requestPermissionsFromUser console.log("start request permission ohos.permission.WRITE_MEDIA") globalThis.context.requestPermissionsFromUser([permissionNameUser], 1, (e, res) => { ... // 自己的逻辑 }) } }

导入模块

import filemanager from '@ohos.fileManager';

该接口需要用户授予以下权限后才能使用：

  • ohos.permission.READ_MEDIA 媒体库读权限

  • ohos.permission.WRITE_MEDIA 媒体库写权限

filemanager.getRoot

getRoot(options? : {dev? : DevInfo}) : Promise<FileInfo[]>

以异步方法获取第一层相册，目录信息，包含file,image,audio,video四种类型，使用promise形式返回结果。

系统能力：SystemCapability.FileManagement.UserFileService

参数：

参数名 类型 必填 说明
options Object 否 支持如下选项： - dev，DevInfo类型，不填默认dev = {name: "local"}, 当前仅支持设备'local'

返回值：

类型 说明
Promise<FileInfo[]> 第一层目录相册信息

代码示例:

let opt= { dev : { name :"local" } } fileManager.getRoot(opt).then((fileInfo) => { if(Array.isArray(fileInfo)) { console.log("FileManager getRoot start") console.log("FileManager getRoot fileInfo length : " + fileInfo.length) for (var i = 0; i < fileInfo.length; i++) { console.log("file:"+JSON.stringify(fileInfo[i])); } console.log("FileManager getRoot end") } }).catch(error => { console.error("FileManager getRoot error : " + error) }) //FileManager getRoot start //FileManager getRoot fileInfo length : 4 //file:{"name":"image_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //file:{"name":"video_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //file:{"name":"audio_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //file:{"name":"file_folder","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //FileManager getRoot end

 

filemanager.listFile

listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}) : Promise<FileInfo[]>

输入根路径及文件类型，以异步方法获取相应类型的第二层文件相册信息。使用promise形式返回结果。

系统能力：SystemCapability.FileManagement.UserFileService

参数：

参数名 类型 必填 说明
path string 是 待查询目录uri，从getRoot方法中获取的file.path
type string 是 待查询文件类型, 支持以下类型 "file", "image", "audio", "video"
options Object 否 支持如下选项： - dev，DevInfo类型，不填默认dev = {name: "local"}, 当前仅支持设备'local'。 - offset，number类型，待查询文件偏移个数。 - count，number类型，待查询文件个数。

返回值：

类型 说明
Promise<FileInfo[]> 文件信息

异常：

错误名称 错误类型 错误码 说明
对应的目录、相册不存在 No such file or directory 2 uri对应的目录、相册不存在
获取FMS服务失败 No such process 3 获取FMS服务失败
path对应uri不是相册、目录 Not a directory 20 path对应uri不是相册、目录

代码示例:

console.log("FileManager getRoot start") //通过getRoot获取的文件path fileManager.getRoot().then(fileInfos => { console.log("FileManager getRoot.length : " + fileInfos.length ) for (let i = 0; i < fileInfos.length; i++) { console.log("L1 :"+JSON.stringify(fileInfos[i]).toString()) let type = fileInfos[i].name.split("_")[0].toString() //输入路径和文件类型，获取文件 fileManager.listFile("dataability:///album",type).then(files =>{ console.log("["+type + "] number =====" + files.length) for(let i=0; i<files.length;i++){ console.log("L2"+JSON.stringify(files[i]).toString()) } }).catch(error =>{ console.error("fileManager listFile : ["+type +"] , error : " + error) }) } console.log("FileManager getRoot end") }) //FileManager getRoot start //FileManager listFile getRoot.length : 4 //L1 :{"name":"image_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //L1 :{"name":"video_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //L1 :{"name":"audio_album","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //L1 :{"name":"file_folder","path":"dataability:///album","type":"album","size":0,"added_time":0,"modified_time":0} //FileManager getRoot end //fileManager listFile : [audio] , err : Error: Not a directory //fileManager listFile : [video] , err : Error: Not a directory //[image] number =====2 //L2{"name":"Camera","path":"datashare:///media/file/1","type":"7","size":0,"added_time":1501926565,"modified_time":1501926568} //L2{"name":"Screenshots","path":"datashare:///media/file/7","type":"7","size":0,"added_time":1501926581,"modified_time":1501926589} //[file] number =====2 //L2{"name":"Camera","path":"datashare:///media/file/1","type":"7","size":0,"added_time":1501926565,"modified_time":1501926568} //L2{"name":"Pictures","path":"datashare:///media/file/6","type":"7","size":0,"added_time":1501926581,"modified_time":1501926581} //根据以上代码，获取第二层相册目录，可知image类型的目录有两个：Camera和Screenshots //再根据Camera的路径和image类型，获取Camera下的image类型的文件 let cameraPath = "datashare:///media/file/1" //从上述日志获取的路径 fileManager.listFile(cameraPath,'image').then(files =>{ console.log("image type" + " files number =====" + files.length) if(Array.isArray(files)){ for (var i = 0; i < files.length; i++) { console.log("L3"+JSON.stringify(files[i])); } } }).catch(error =>{ console.error("fileManager listFile"+"level 3 image" +" error : " + error) }) //image type files number =====4 //L3{"name":"IMG_201785_094925.jpg","path":"datashare:///media/image/2","type":"1","size":4915200,"added_time":1501926565,"modified_time":1501926565} //L3{"name":"IMG_201785_094926.jpg","path":"datashare:///media/image/3","type":"1","size":4915200,"added_time":1501926566,"modified_time":1501926566} //L3{"name":"IMG_201785_094927.jpg","path":"datashare:///media/image/4","type":"1","size":4915200,"added_time":1501926567,"modified_time":1501926567} //L3{"name":"IMG_201785_094928.jpg","path":"datashare:///media/image/5","type":"1","size":4915200,"added_time":1501926568,"modified_time":1501926568}

 

filemanager.createFile

createFile(path : string, filename : string, options? : {dev? : DevInfo}) : Promise<string>

以异步方法创建文件到指定路径，返回文件uri。使用promise形式返回结果。

系统能力：SystemCapability.FileManagement.UserFileService

参数：

参数名 类型 必填 说明
filename string 是 待创建的文件名
path string 是 待保存目的相册uri
options Object 否 支持如下选项： - dev，DevInfo类型，不填默认dev = {name: "local"}, 当前仅支持设备'local'

返回值：

类型 说明
Promise<string> 文件uri

异常：

错误名称 错误类型 错误码 说明
创建文件不允许 Operation not permitted 1 已有重名文件
对应的目录、相册不存在 No such file or directory 2 uri对应的目录、相册不存在
获取FMS服务失败 No such process 3 获取FMS服务失败
path对应uri不是相册、目录 Not a directory 20 path对应uri不是相册、目录

代码示例:

let path = "datashare:///media/file/7" //从以上listFile代码获取的imageimage类型的文件路径 let fileName = "testPic.jpg" //新建文件的文件名 fileManager.createFile(path,fileName).then(uri => { console.log("file uri:"+uri) //file uri:datashare:///media/image/10 }).catch(error => { console.error("fileManager createFile with error : " + error) })

FileInfo

文件信息类型，通过getRoot, listFile等接口返回的类型。

系统能力：以下各项对应的系统能力均为SystemCapability.FileManagement.UserFileService。

属性

参数名 类型 可读 可写 说明
name string 是 否 文件名称
path string 是 否 文件Uri
type string 是 否 文件类型
size number 是 否 文件大小
addedTime number 是 否 媒体插入时间
modifiedTime number 是 否 媒体修改时间

DevInfo

设备类型，配置接口访问的设备类型。

系统能力：以下各项对应的系统能力均为SystemCapability.FileManagement.UserFileService。

属性

参数名 类型 可读 可写 说明
name string 是 是 设备名称

参考文献

[1]OpenHarmony文件管理.https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-fileio.md

[2]OpenHarmony媒体文件管理.https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-filemanager.md

Logo
欢迎加入Laval社区

社区规范：仅讨论OpenHarmony相关问题。

更多推荐

cover

《开源鸿蒙领学课堂-AI赋能系列-具身智能专题第三期》直播回顾

avatar Laval社区
cover

《开源鸿蒙领学课堂-AI赋能系列-具身智能专题第二期》直播回顾

avatar Laval社区
cover

开源鸿蒙 EmbodiedAI 1.0.1正式发布

avatar Laval社区