# io

IO模块管理本地文件系统，用于对文件系统的目录浏览、文件的读取、文件的写入等操作。通过plus.io可获取文件系统管理对象。

## 常量：

- PRIVATE_WWW: 应用运行资源目录常量
- PRIVATE_DOC: 应用私有文档目录常量
- PUBLIC_DOCUMENTS: 程序公用文档目录常量
- PUBLIC_DOWNLOADS: 程序公用下载目录常量

## 方法：

- requestFileSystem: 请求本地文件系统对象
- resolveLocalFileSystemURL: 通过URL参数获取目录对象或文件对象
- convertLocalFileSystemURL: 将本地URL路径转换成平台绝对路径
- convertAbsoluteFileSystem: 将平台绝对路径转换成本地URL路径

## 对象：

- DirectoryEntry: 文件系统中的目录对象，用于管理特定的本地目录
- DirectoryReader: 读取目录信息对象，用于获取目录中包含的文件及子目录
- File: 文件系统中的文件数据对象，用于获取文件的数据
- FileEntry: 文件系统中的文件对象，用于管理特定的本地文件
- FileReader: 文件系统中的读取文件对象，用于获取文件的内容
- FileWriter: 文件系统中的写文件对象，用于写入文件内容
- FileSystem: 文件系统对象，用于管理特定本地文件目录
- Flags: JSON对象，获取文件操作的参数
- Metadata: JSON对象，保存文件或目录的状态信息对象
- FileEvent: 文件或目录操作事件对象
- URLType: 文件路径类型
- RelativeURL: 相对路径URL
- LocalURL: 本地路径URL
- RemoteURL: 网络路径URL

## 回调方法：

- FileEventCallback: 文件事件回调
- FileSystemSuccessCallback: 请求文件系统成功的回调函数
- FileResolveSuccessCallback: 通过URL参数获取目录或文件对象成功的回调函数
- MetadataSuccessCallback: 获取文件或目录状态信息成功的回调函数
- EntrySuccessCallback: 操作文件或目录对象成功的回调函数
- EntrysSuccessCallback: 操作文件或目录对象数组成功的回调函数
- FileWriterSuccessCallback: 写文件操作成功的回调函数
- FileSuccessCallback: 文件操作成功的回调函数
- FileErrorCallback: 文件操作失败的回调函数

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"File": {
    		"description": "文件系统"
    	}
    }
    }

# DirectoryEntry

文件系统中的目录对象，用于管理特定的本地目录

## 属性：

- isFile: 操作对象的是否为文件，DirectoryEntry对象固定其值为false
- isDirectory: 操作对象是否为目录，DirectoryEntry对象固定其值为true
- name: 目录操作对象的名称，不包括路径
- fullPath: 目录操作对象的完整路径，文件系统的绝对路径
- fileSystem: 文件操作对象所属的文件系统对象，参考FileSystem

## 方法：

- getMetadata: 获取目录的属性
- moveTo: 移动目录
- copyTo: 拷贝目录
- toURL: 获取目录路径转换为URL地址
- toLocalURL: 获取目录路径转换为本地路径URL地址
- toRemoteURL: 获取目录路径转换为网络路径URL地址
- remove: 删除目录
- getParent: 获取目录所属的父目录
- createReader: 创建目录读取对象
- getDirectory: 创建或打开子目录
- getFile: 创建或打开文件
- removeRecursively: 递归删除目录

# DirectoryReader

读取目录信息对象，用于获取目录中包含的文件及子目录

## 方法：

- readEntries: 获取当前目录中的所有文件和子目录

# File

文件系统中的文件数据对象，用于获取文件的数据

## 属性：

- size: 文件数据对象的数据大小，单位为字节
- type: 文件数据对象MIME类型
- name: 文件数据对象的名称，不包括路径
- lastModifiedDate: 文件对象的最后修改时间

## 方法：

- slice: 获取文件指定的数据内容
- close: 关闭文件数据对象

# FileEntry

文件系统中的文件对象，用于管理特定的本地文件

## 属性：

- isFile: 文件操作对象的是否为文件，FileEntry对象固定其值为true
- isDirectory: 文件操作对象是否为目录，FileEntry对象固定其值为false
- name: 文件操作对象的名称，不包括路径
- fullPath: 文件操作对象的完整路径，文件系统的绝对路径
- fileSystem: 文件操作对象所属的文件系统对象，参考FileSystem

## 方法：

- getMetadata: 获取文件的属性信息
- moveTo: 移动文件
- copyTo: 拷贝文件
- toURL: 获取文件路径转换为URL地址
- toLocalURL: 获取文件路径转换为本地路径URL地址
- toRemoteURL: 获取文件路径转换为网络路径URL地址
- remove: 删除文件
- getParent: 获取文件所属的父目录
- createWriter: 获取文件关联的写文件操作对象FileWriter
- file: 获取文件数据对象

# FileReader

文件系统中的读取文件对象，用于获取文件的内容

## 说明：

FileReader对象是从设备文件系统读取文件FileReader对象是从设备文件系统读取文件的一种方式，文件以文本或者Base64编码的字符串形式读出来。 用户注册自己的事件监听器来接收loadstart、progress、load、loadend、error和abort事件。

## 构造：

- FileReader: 创建读取文件对象

## 常量：

- EMPTY: 值为0，开始读取文件状态
- LOADING: 值为1，正在读取文件状态
- DONE: 值为2，读文件操作完成状态

## 属性：

- readyState: 当前读取文件所处的状态
- result: 已读取文件的内容
- error: 文件操作错误代码

## 方法：

- abort: 终止文件读取操作
- readAsDataURL: 以URL编码格式读取文件数据内容
- readAsText: 以文本格式读取文件数据内容

## 事件：

- onloadstart: 读取文件开始时的回调函数
- onprogress: 读取文件过程中的回调函数
- onload: 读取文件成功完成的回调函数
- onabort: 取消读取文件时的回调函数
- onerror: 文件读取操作失败时调用的回调函数
- onloadend: 文件读取操作完成时的回调函数

# FileWriter

文件系统中的写文件对象，用于写入文件内容

## 说明：

FileWriter对象是从设备文件系统写入文件FileWriter对象是从设备文件系统写入文件的一种方式，用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个FileWriter对象是为单个文件的操作而创建。你可以使用该对象多次对相应文件进行写入操作。FileWriter维护该文件的指针位置及长度属性，这样你就可以寻找和写入文件的任何地方。 默认情况下，FileWriter从文件的开头开始写入（将覆盖现有数据）。FileWriter对象的seek方法可设置文件操作指定位置，如fw.seek(fw.length-1)写入操作就会从文件的末尾开始。

## 常量：

- INIT: 值为0，写文件初始化状态
- WRITING: 值为1，正在写入文件状态
- DONE: 值为2，写文件操作完成状态

## 属性：

- readyState: 当前写入文件所处的状态
- length: 文件当前的长度，单位为字节
- position: 文件当前操作的指针位置
- error: 文件写入操作错误代码

## 方法：

- abort: 终止文件写入操作
- seek: 定位文件操作位置
- truncate: 按照指定长度截断文件
- write: 向文件中写入数据

## 事件：

- onwritestart: 写入文件开始时的回调函数
- onprogress: 写入文件过程中的回调函数
- onwrite: 写入文件成功完成的回调函数
- onabort: 取消写入文件时的回调函数
- onerror: 文件写入操作失败时调用的回调函数
- onwriteend: 文件写入操作完成时的回调函数

# FileSystem

文件系统对象，用于管理特定本地文件目录

## 说明：

文件系统对象表示一个应用可访问的根目录。name属性用于标识此根目录的名称，与LocalFileSystem中的文件系统类型一一对应。root属性为文件目录对象，用于实际操作文件系统，参考DirectoryEntry。

## 属性：

- name: 文件系统的名称
- root: 文件系统的根目录

# Flags

JSON对象，获取文件操作的参数

## 属性：

- create: (Boolean 类型 )是否创建对象标记

  指示如果文件或目录不存在时是否进行创建，默认值为false。

- exclusive: (Boolean 类型 )反向操作标记

  其本身没有任何效果，需与create属性值设置为true时一起使用，如果目标文件或目录已经存在则会导致文件或目录打开失败，默认值为false。

# Metadata

JSON对象，保存文件或目录的状态信息对象

## 说明：

可通过DirectoryEntry或FileEntry对象的getMetaData方法获取

## 属性：

- modificationTime: (Date 类型 )文件或目录的最后修改时间
- size: (Number 类型 )文件的大小

  若获取的是目录对象的属性则值为0。

- directoryCount: (Number 类型 )包含的子目录数

  若自身是文件则其值为0。

- fileCount: (Number 类型 )目录的文件数

  若自身是文件则其值为0。

# FileEvent

文件或目录操作事件对象

## 说明：

所有文件或目录操作事件回调函数中都创建该对象的实例。 该对象从DOMEvent继承而来，可通过该其target属性获取事件触发的文件或目录操作对象。

## 属性：

- target: (DirectoryEntry 类型 )文件或目录操作对象

  在不同的回调中指向的对象不同，可指向的对象包括：FileEntry、DirectoryEntry、FileReader、FileWriter。

# URLType

文件路径类型

## 说明：

在文件系统中的文件路径需转换成URL格式，已方便runtime快速加载。

# RelativeURL

相对路径URL

## 说明：

只能在扩展API中使用，相对于基座提供的特定目录，以“_”开头。

## 常量：

- "_www": (DOMString 类型 )应用资源目录

  保存应用的所有html、css、js等资源文件，与文件系统中根目录PRIVATE_WWW一致，后面加相对路径如“_www/res/icon.png”。 注意：应用资源目录是只读目录，只能读取次目录下的文件，不能修改或新建。

- "_doc": (DOMString 类型 )应用私有文档目录

  用于保存应用运行期业务逻辑数据，与文件系统中根目录PRIVATE_DOCUMENTS，如“_doc/userdata.xml”。

- "_documents": (DOMString 类型 )程序公用文档目录

  用于保存程序中各应用间可共享文件的目录，与文件系统中根目录PUBLIC_DOCUMENTS，如“_document/share.doc”。

- "_downloads": (DOMString 类型 )程序公用下载目录

  用于保存程序下载文件的目录，与文件系统中根目录PUBLIC_DOWNLOADS，如“_download/mydoc.doc”。

# LocalURL

本地路径URL

## 说明：

可在html页面中直接访问本地资源，以“file:///”开头，后面跟随系统的绝对路径。 如示例：“file:///D:/res/hello.html”。

# RemoteURL

网络路径URL

## 说明：

可在html页面中以网络资源模式访问本地资源，以“http://”开头，后面跟随相对路径。 如示例：“http://localhost:13131/_www/res/icon.png”，其中“_www”字段可支持类型与相对路径URL一致。

# FileEventCallback

文件事件回调

    void onEvent( event ) {
    	// Event code.
    }

## 说明：

文件或目录操作回调事件。 通常在FileReader和FileWriter对象的事件函数中触发。

## 参数：

- event: ( FileEvent ) 必选 文件事件对象

## 返回值：

void : 无

# FileSystemSuccessCallback

请求文件系统成功的回调函数

    void onSuccess( fs ) {
    	// File System operate code.
    }

## 参数：

- fs: ( FileSystem ) 必选 请求到的文件系统对象

## 返回值：

void : 无

# FileResolveSuccessCallback

通过URL参数获取目录或文件对象成功的回调函数

    void onSuccess( entry ) {
    	// File or Direcory entry operate code.
    }

## 参数：

- entry: ( DirectoryEntry ) 必选 请求到的目录或文件对象
  可指向文件或目录对象（DirectoryEntry|FileEntry）。

## 返回值：

void : 无

# MetadataSuccessCallback

获取文件或目录状态信息成功的回调函数

    void onSuccess( metadata ) {
    	// Metadata code.
    }

## 参数：

- metadata: ( Metadata ) 必选 文件或目录的状态信息

## 返回值：

void : 无

# EntrySuccessCallback

操作文件或目录对象成功的回调函数

    void onSuccess( entry ) {
    	// Entry code.
    }

## 参数：

- entry: ( DirectoryEntry ) 必选 文件或目录对象的引用
  可指向文件或目录对象（DirectoryEntry|FileEntry）。

## 返回值：

void : 无

# EntrysSuccessCallback

操作文件或目录对象数组成功的回调函数

    void onSuccess( entrys ) {
    	// Entrys code.
    }

## 参数：

- entrys: ( DirectoryEntry ) 必选 文件或目录对象数组
  可指向文件或目录对象数组（DirectoryEntry[]|FileEntry[]）。

## 返回值：

void : 无

# FileWriterSuccessCallback

写文件操作成功的回调函数

    void onSuccess( writer ) {
    	// FileWriter code.
    }

## 参数：

- writer: ( FileWriter ) 必选 写文件对象的引用

## 返回值：

void : 无

# FileSuccessCallback

文件操作成功的回调函数

    void onSuccess( file ) {
    	// file code.
    }

## 参数：

- file: ( File ) 必选 文件数据对象的引用

## 返回值：

void : 无

# FileErrorCallback

文件操作失败的回调函数

    void onError( error ) {
    	// Error code.
    }

## 参数：

- error: ( DOMException ) 必选 文件操作失败的信息

## 返回值：

void : 无