概述

fs 封装了对文件操作的接口，通过此模块可对文件或文件夹进行创建、删除、读取、写入等相关操作。

注意

在Android系统中如果需要读取外置sd卡上的文件，需要传入系统路径；如：file://storage/sdacrd/xxx.jpg

异步接口

createDir

创建目录

createDir({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true|false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,           //数字类型；错误码（详见文件操作错误码常量）
    msg: ''            //字符串；错误描述
}

示例代码

var fs = api.require('fs');
fs.createDir({
    path: 'fs://floder'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

rmdir

删除文件目录，里面的所有文件将会一起被删除

rmdir({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标文件路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true|false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,           //数字类型；错误码（详见文件操作错误码常量）
    msg: ''            //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.rmdir({
    path: 'fs://floder'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

createFile

创建文件

createFile({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true| false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,              //数字类型；错误码（详见文件操作错误码常量）
    msg: ''               //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.createFile({
    path: 'fs://file.txt'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

remove

删除文件

remove({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true            //布尔类型；操作成功状态值，true| false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,              //数字类型错误码（详见文件操作错误码常量）
    msg: ''               //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.remove({
    path: 'fs://file.txt'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

copyTo

拷贝文件

copyTo({params}, callback(ret, err))

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true| false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,             //数字类型；错误码（详见文件操作错误码常量）
    msg: ''              //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.copyTo({
    oldPath: 'fs://file.txt',
    newPath: 'fs://floder'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

moveTo

移动文件

moveTo({params}, callback(ret, err))

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true| false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,              //数字类型；错误码（详见文件操作错误码常量）
    msg: ''               //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.moveTo({
    oldPath: 'fs://file.txt',
    newPath: 'fs://floder'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

rename

重命名

rename({params}, callback(ret, err))

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true           //布尔类型；操作成功状态值，true| false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,              //数字类型；错误码（详见文件操作错误码常量）
    msg: ''               //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.rename({
    oldPath: 'fs://file.txt',
    newPath: 'fs://rename.txt'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

readDir

列出目录

readDir({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    data: []              //数组；文件夹内的所有子文件名称
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,              //数字类型；错误码（详见文件操作错误码常量）
    msg: ''               //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.readDir({
    path: 'fs://'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

open

打开文件

open({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

flags：

• 类型：字符串
• 默认值：read
• 描述：（可选项）文件打开方式（详见文件打开方式常量）

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,            //布尔类型；操作成功状态值，true| false
    fd:'14143124'            //字符串类型；操作文件的句柄
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,                //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                 //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.open({
    path: 'fs://file.txt',
    flags: 'read_write'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

read

读取文件

read({params}, callback(ret, err))

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

offset：

• 类型：数字
• 描述：（可选项）当前文件偏移量，以 byte 为单位
• 默认值：0

length：

• 类型：数字
• 描述：（可选项）读取内容长度
• 默认值：原文件文本内容的长度，以 byte 为单位

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，false |true
    data: ''              //字符串类型；文件内容
}

err：

类型：JSON 对象 内部字段：

{
    code: 0,             //数字类型；错误码（详见文件操作错误码常量）
    msg: ''              //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.read({
    fd: 'open 方法得到的文件句柄',
    offset: 0,
    length: 0
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

readUp

从当前文件句柄当前位置向上读取一页(页的大小如 length )数据

readUp({params}, callback(ret, err))

params

fd：

• 类型：字符串
• 描述：（可选项）open 方法得到的文件句柄
• 默认值：当前文件句柄

length：

• 类型：数字
• 默认值：（可选项）当前最近一次读取数据的 length，以 byte 为单位
• 描述：此次向上读取数据的长度

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true                //布尔类型；操作成功状态值，true|false
    data: ''                    //字符串类型；返回的文件内容
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,                  //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                   //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.readUp(function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

readDown

从当前文件句柄当前位置向下读取一页(页的大小如 length )数据

readDown({params}, callback(ret, err))

params

fd：

• 类型：字符串
• 描述：（可选项）open 方法得到的文件句柄
• 默认值：当前文件句柄

length：

• 类型：数字
• 描述：（可选项）此次向下读取数据的长度，以 byte 为单位
• 默认值：当前最近一次读取数据的 length

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true              //布尔类型；操作成功状态值，true|false
    data: ''                  //字符串类型；文件内容
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,               //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                //字符串类型，错误描述
}

示例代码

var fs = api.require('fs');
fs.readDown(function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

write

写入文件

write({params}, callback(ret, err))

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

data：

• 类型：字符串
• 描述：写入数据

offset：

• 类型：数字
• 描述：（可选项）写入内容的起始位置以 byte 为单位
• 默认值：原文件文本内容的长度

overwrite：

• 类型：布尔
• 描述：（可选项）是否覆盖指定偏移位置后面的内容
• 默认值：false

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围:gbk、utf8
• 默认值：utf8

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true            //布尔类型；操作成功状态值，true|false
}

err：

• 类型：JSON 对象

内部字段：

{
    code: 0,               //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.write({
    fd: 'open 方法得到的文件句柄',
    data: 'test',
    offset: 0
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

该文件句柄必须是写或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭文件

close({params}, callback(ret, err))

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true        //布尔类型；操作成功状态值，true|false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,                //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                 //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.close({
    fd: 'open 方法得到的文件句柄'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

exist

判断文件是否存在

注：android在云编译的情况下是不能判断一个文件是否是文件夹的情况

exist({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：要判断的文件路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    exist: true                //布尔类型；操作成功状态值，true|false在
    directory: false           //文件是否是文件夹
}

示例代码

var fs = api.require('fs');
fs.exist({
    path: 'fs://file.txt'
}, function(ret, err) {
    if (ret.exist) {
        if (ret.directory) {
            alert('文件夹');
        } else {
            alert('文件');
        }
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAttribute

获取指定路径下文件的属性

getAttribute({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
   status:                //布尔类型；操作状态；true||false
   attribute:             //JSON对象；文件属性
                          //内部字段：{
                            creationDate:    //字符串类型；创建日期 （时间戳），仅 iOS 支持此字段
                            modificationDate://字符串类型；修改日期（时间戳）
                            size:            //数字类型；文件大小，以 byte 为单位
                            type:            //字符串类型；表示文件类型，取值范围：folder（文件夹）、file（文件）
                           }
}

err：

• 类型：JSON 对象
• 内部字段：

{
    msg:            //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.getAttribute({
    path: 'fs://file.txt'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.1及更高版本

readByLength

按照字符串长度读取文件，本接口针对纯文本文件有效。无需 open

readByLength({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标文件路径，要求本地路径（fs://、widget://）

substring：

• 类型：JSON 对象
• 描述：(可选项) 读取字符串范围，以字符为单位
• 默认值：见内部字段
• 内部字段：

{
    start:    0,     //（可选项）非负整数；规定要提取的子串的第一个字符在文件中的位置；默认：0
    length: 199     //（可选项）非负整数；所要读取的文本字符串长度；默认：原文件文本内容的总长
}

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，false |true
    content: '',          //字符串类型；读取指定文件的内容
    codingType: 'utf8'    //字符串类型；文件编码类型，取值范围： utf8、gbk
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,             //数字类型；错误码（详见文件操作错误码常量）
    msg: ''              //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.readByLength({
    path: 'fs://file.txt',
    substring: {
        start: 0,
        length: 10
    }
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.1及更高版本

writeByLength

将字符串写入指定位置的文件，无需 open

writeByLength({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：目标文件路径，要求本地路径（fs://），不支持 widget 协议

content：

• 类型：字符串
• 描述：写入的数据

place：

• 类型：JSON 对象
• 描述：(可选项) 写入文件位置 以字符为单位
• 默认值：见内部字段
• 内容字段：

{
    start: 0,      //（可选项）非负的整数；写入文件起始位置；默认：0
    strategy: 199  //（可选项）数字类型；默认：-1；取值范围：
                   // -1 (覆盖起始位置后所有)
                   // 0 (不覆盖，插入)
                   //大于零的整数 (起始位置向后覆盖指定字符的长度)
}

codingType：

• 类型：字符串
• 描述：（可选项）保存的文本的编码格式，取值范围:gbk、utf8
• 默认值：utf8

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true            //布尔类型；操作成功状态值，true|false
}

err：

• 类型：JSON 对象
• 内部字段：

{
    code: 0,               //数字类型；错误码（详见文件操作错误码常量）
    msg: ''                //字符串类型；错误描述
}

示例代码

var fs = api.require('fs');
fs.writeByLength({
    path: 'fs://file.txt',
    content: 'test',
    place: {
        start: 0,
        strategy: 0
    }
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.1及更高版本

getMD5

获取文件 md5 值

getMD5({params}, callback(ret, err))

params

path：

• 类型：字符串
• 描述：要获取其 md5 值的文件路径

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,        //布尔类型；操作成功状态值，true|false在
    md5Str: ''           //字符串类型；文件的 md5 值
}

示例代码

var fs = api.require('fs');
fs.getMD5({
    path: 'fs://file.txt'
}, function(ret) {
    if (ret.status) {
        alert(ret.md5Str);
    }
});

可用性

iOS系统，Android系统

可提供的1.0.1及更高版本

cutFile

大文件切割

cutFile({params})

params

path：

• 类型：字符串
• 描述：文件路径，支持fs,widget（android不支持widget）

cutFiles：

• 类型：字符串
• 描述：切割完成保存的文件路径（不包含文件名），文件切割后的小文件会保存在此路径文件夹下，仅支持fs
• 示例路径：‘fs://cutFiles’

cutSize：

• 类型：数字
• 描述：（可选项）切割后的文件单个大小；单位 MB
• 默认：1

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,        //布尔类型；是否切割成功，true|false
    cutFiles:[]          //数组类型；切割后的文件路径（包含文件名）
}

示例代码

var fs = api.require('fs');
var ret = fs.cutFile({
    path: '',
    cutSize:1,
    cutFiles:''
}, function(ret, err) {
   if (ret) {
   alert(JSON.stringify(ret));
   }
   });

可用性

iOS系统，Android系统

可提供的1.0.6及更高版本

同步接口

createDirSync

创建目录

createDirSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,      //布尔类型；操作成功状态值，true|false
    code: 0,           //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''            //字符串；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.createDirSync({
    path: 'fs://floder'
});
if (ret.status) {
    alert('创建成功！');
} else {
    alert('创建失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

rmdirSync

删除文件目录，里面的所有文件将会一起被删除

rmdirSync({params})

params

path：

• 类型：字符串
• 描述：目标文件路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,      //布尔类型；操作成功状态值，true|false
    code: 0,           //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''            //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.rmdirSync({
    path: 'fs://floder'
});
if (ret.status) {
    alert('删除成功！');
} else {
    alert('删除失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

createFileSync

创建文件

createFileSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    code: 0,              //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.createFileSync({
    path: 'fs://file.txt'
});
if (ret.status) {
    alert('创建成功！');
} else {
    alert('创建失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

removeSync

删除文件

removeSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.removeSync({
    path: 'fs://file.txt'
});
if (ret.status) {
    alert('删除成功！');
} else {
    alert('删除失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

copyToSync

拷贝文件

copyToSync({params})

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.copyToSync({
    oldPath: 'fs://file.txt',
    newPath: 'fs://floder'
});
if (ret.status) {
    alert('拷贝成功！');
} else {
    alert('拷贝失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

moveToSync

移动文件

moveToSync({params})

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.moveToSync({
    oldPath: 'fs://file.txt',
    newPath: 'fs://floder'
});
if (ret.status) {
    alert('移动成功！');
} else {
    alert('移动失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

renameSync

重命名

renameSync({params})

params

oldPath：

• 类型：字符串
• 描述：源路径

newPath：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.renameSync({
    oldPath: 'fs://file.txt',
    newPath: 'fs://rename.txt'
});
if (ret.status) {
    alert('重命名成功！');
} else {
    alert('重命名失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

readDirSync

列出目录

readDirSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    data: [] ,            //数组；文件夹内的所有子文件名称
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.readDirSync({
    path: 'fs://'
});
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

openSync

打开文件

openSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

flags：

• 类型：字符串
• 默认值：read
• 描述：（可选项）文件打开方式（详见文件打开方式常量）

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，true| false
    fd:'14143124',        //字符串类型；操作文件的句柄
    code: 0,              //数字类型错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''               //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.openSync({
    path: 'fs://file.txt',
    flags: 'read_write'
});
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

readSync

读取文件

readSync({params})

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

offset：

• 类型：数字
• 描述：（可选项）当前文件偏移量，以 byte 为单位
• 默认值：0

length：

• 类型：数字
• 描述：（可选项）读取内容长度
• 默认值：原文件文本内容的长度，以 byte 为单位

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，false |true
    data: '',            //字符串类型；文件内容
    code: 0,             //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''              //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.readSync({
    fd: 'open 方法得到的文件句柄',
    offset: 0,
    length: 0
});
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

readUpSync

从当前文件句柄当前位置向上读取一页(页的大小如 length )数据

readUpSync({params})

params

fd：

• 类型：字符串
• 描述：（可选项）open 方法得到的文件句柄
• 默认值：当前文件句柄

length：

• 类型：数字
• 默认值：（可选项）当前最近一次读取数据的 length，以 byte 为单位
• 描述：此次向上读取数据的长度

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true        //布尔类型；操作成功状态值，true|false
    data: '',           //字符串类型；返回的文件内容
    code: 0,            //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''             //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.readUpSync();
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

readDownSync

从当前文件句柄当前位置向下读取一页(页的大小如 length )数据

readDownSync({params})

params

fd：

• 类型：字符串
• 描述：（可选项）open 方法得到的文件句柄
• 默认值：当前文件句柄

length：

• 类型：数字
• 描述：（可选项）此次向下读取数据的长度，以 byte 为单位
• 默认值：当前最近一次读取数据的 length

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围: gbk、utf8
• 默认值：utf8

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true        //布尔类型；操作成功状态值，true|false
    data: '',           //字符串类型；返回的文件内容
    code: 0,            //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''             //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.readDownSync();
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

补充说明

该文件句柄必须是读或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

writeSync

写入文件

writeSync({params})

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

data：

• 类型：字符串
• 描述：写入数据

offset：

• 类型：数字
• 描述：（可选项）写入内容的起始位置以 byte 为单位
• 默认值：原文件文本内容的长度

overwrite：

• 类型：布尔
• 描述：（可选项）是否覆盖指定偏移位置后面的内容
• 默认值：false

codingType：

• 类型：字符串
• 描述：（可选项）所要阅读的文本的编码格式，取值范围:gbk、utf8
• 默认值：utf8

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,          //布尔类型；操作成功状态值，true|false
    code: 0,               //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''                //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.writeSync({
    fd: 'open 方法得到的文件句柄',
    data: 'test',
    offset: 0
});
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

补充说明

该文件句柄必须是写或读写方式打开的，否则会引起异常

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

closeSync

关闭文件

closeSync({params})

params

fd：

• 类型：字符串
• 描述：open 方法得到的文件句柄

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,          //布尔类型；操作成功状态值，true|false
    code: 0,               //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''                //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.closeSync({
    fd: 'open 方法得到的文件句柄'
});
if (ret.status) {
    alert('操作成功！');
} else {
    alert('操作失败！');
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

existSync

判断文件是否存在

注：android在云编译的情况下是不能判断一个文件是否是文件夹的情况

existSync({params})

params

path：

• 类型：字符串
• 描述：要判断的文件路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    exist: true                //布尔类型；操作成功状态值，true|false在
    directory: false           //文件是否是文件夹
}

示例代码

var fs = api.require('fs');
var ret = fs.existSync({
    path: 'fs://file.txt'
});
if (ret.exist) {
    if (ret.directory) {
        alert('文件夹');
    } else {
        alert('文件');
    }
} else {
    alert(JSON.stringify(err));
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

getAttributeSync

获取指定路径下文件的属性

getAttributeSync({params})

params

path：

• 类型：字符串
• 描述：目标路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
   status:                //布尔类型；操作状态；true||false
   attribute: {           //JSON对象；文件属性
       creationDate:       //字符串类型；创建日期 （时间戳），仅 iOS 支持此字段
       modificationDate:   //字符串类型；修改日期（时间戳）
       size:               //数字类型；文件大小，以 byte 为单位
       type:               //字符串类型；表示文件类型，取值范围：folder（文件夹）、file（文件）
   }
}

示例代码

var fs = api.require('fs');
var ret = fs.getAttributeSync({
    path: 'fs://file.txt'
});
if (ret.status) {
    alert(JSON.stringify(ret));
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

readByLengthSync

按照字符串长度读取文件，本接口针对纯文本文件有效。无需 open

readByLengthSync({params})

params

path：

• 类型：字符串
• 描述：目标文件路径，要求本地路径（fs://、widget://）

substring：

• 类型：JSON 对象
• 描述：(可选项) 读取字符串范围，以字符为单位
• 默认值：见内部字段
• 内部字段：

{
    start:    0,     //（可选项）非负整数；规定要提取的子串的第一个字符在文件中的位置；默认：0
    length: 199     //（可选项）非负整数；所要读取的文本字符串长度；默认：原文件文本内容的总长
}

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,         //布尔类型；操作成功状态值，false |true
    content: '',          //字符串类型；读取指定文件的内容
    codingType: 'utf8',   //字符串类型；文件编码类型，取值范围： utf8、gbk
    code: 0,             //数字类型；错误码（详见文件操作错误码常量），仅当 status 为false 时有值
    msg: ''              //字符串类型；错误描述，仅当 status 为false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.readByLengthSync({
    path: 'fs://file.txt',
    substring: {
        start: 0,
        length: 10
    }
});
if (ret.status) {
    alert(JSON.stringify(ret));
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

writeByLengthSync

将字符串写入指定位置的文件，无需 open(openSync)

writeByLengthSync({params})

params

path：

• 类型：字符串
• 描述：目标文件路径，要求本地路径（fs://），不支持 widget 协议

content：

• 类型：字符串
• 描述：写入的数据

place：

• 类型：JSON 对象
• 描述：(可选项) 写入文件位置 以字符为单位
• 默认值：见内部字段
• 内容字段：

{
    start: 0,      //（可选项）非负的整数；写入文件起始位置；默认：0
    strategy: 199  //（可选项）数字类型；默认：-1；取值范围：
                   // -1 (覆盖起始位置后所有)
                   // 0 (不覆盖，插入)
                   // 大于零的整数 (起始位置向后覆盖指定字符的长度)
}

codingType：

• 类型：字符串
• 描述：（可选项）保存的文本的编码格式，取值范围:gbk、utf8
• 默认值：utf8

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true             //布尔类型；操作成功状态值，true|false
    code: 0,             //数字类型；错误码（详见文件操作错误码常量），仅当 status 为 false 时有值
    msg: ''              //字符串类型；错误描述，仅当 status 为 false 时有值
}

示例代码

var fs = api.require('fs');
var ret = fs.writeByLengthSync({
    path: 'fs://file.txt',
    content: 'test',
    place: {
        start: 0,
        strategy: 0
    }
});

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

getMD5Sync

获取文件 md5 值

getMD5Sync({params})

params

path：

• 类型：字符串
• 描述：要获取其 md5 值的文件路径

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,        //布尔类型；操作成功状态值，true|false在
    md5Str: ''           //字符串类型；文件的 md5 值
}

示例代码

var fs = api.require('fs');
var ret = fs.getMD5Sync({
    path: 'fs://file.txt'
});
if (ret.status) {
    alert(ret.md5Str);
}

可用性

iOS系统，Android系统

可提供的1.0.5及更高版本

cutFileSync

大文件切割

cutFileSync({params})

params

path：

• 类型：字符串
• 描述：文件路径，支持fs,widget（android不支持widget）

cutFiles：

• 类型：字符串
• 描述：切割完成保存的文件路径（不包含文件名），文件切割后的小文件会保存在此路径文件夹下，仅支持fs
• 示例路径：‘fs://cutFiles’

cutSize：

• 类型：数字
• 描述：（可选项）切割后的文件单个大小；单位 MB
• 默认：1

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,        //布尔类型；是否切割成功，true|false
    cutFiles:[]          //数组类型；切割后的文件路径（包含文件名）
}

示例代码

var fs = api.require('fs');
var ret = fs.cutFileSync({
    path: '',
    cutSize:1,
    cutFiles:''
});
if (ret.status) {
    api.alert({ msg:JSON.stringify(ret)});
}

可用性

iOS系统，Android系统

可提供的1.0.6及更高版本

requestAllFilesAccessPermission

请求所有文件的管理权限

requestAllFilesAccessPermission(callback())

return

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,        //布尔类型；是否已经获得权限；如果没有会跳到权限设置页面；注意：Android系统设置权限返回后无法获取权限状态
}

示例代码

var fs = api.require('fs');
fs.requestAllFilesAccessPermission(function(ret){
    alert(JSON.stringify(ret));
});

可用性

iOS系统，Android系统

可提供的1.0.6及更高版本

错误码

文件操作错误码，数字类型

取值范围：

• 0 //没有错误
• 1 //找不到文件错误
• 2 //不可读取错误
• 3 //编码格式错误
• 4 //无效操作错误
• 5 //无效修改错误
• 6 //磁盘溢出错误
• 7 //文件已存在错误

文件打开方式

文件打开方式，字符串类型

取值范围：

• read //只读
• write //只写
• read_write //读写