# io

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

## 常量：

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

## 方法：

- requestFileSystem: 请求本地文件系统对象
- resolveLocalFileSystemURL: 通过URL参数获取目录对象或文件对象
- convertLocalFileSystemURL: 将本地URL路径转换成平台绝对路径
- convertAbsoluteFileSystem: 将平台绝对路径转换成本地URL路径
- getAudioInfo: 获取音频文件信息
- getFileInfo: 获取文件信息
- getImageInfo: 获取图片信息
- getVideoInfo: 获取视频文件信息

## 对象：

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

## 回调方法：

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

## 权限：

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对象是向设备文件系统写入文件的一种方式，用户注册自己的事件监听器来接收writestart、progress、write、writeend、error和abort事件。 一个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一致。

# AudioInfo

JSON对象，音频文件信息对象

## 说明：

通过getAudioInfo方法的成功回调函数返回

## 属性：

- duration: (Number 类型 )音频长度

  单位为秒（s）。

# FileInfo

JSON对象，文件信息对象

## 说明：

通过getFileInfo方法的成功回调函数返回

## 属性：

- digest: (String 类型 )文件摘要

  按照传入的 digestAlgorithm 计算得出的文件摘要信息。

- size: (Number 类型 )文件大小

  单位为字节。

# ImageInfo

JSON对象，图片信息对象

## 说明：

通过getImageInfo方法的成功回调函数返回

## 属性：

- height: (Number 类型 )图片的原始高度

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

- orientation: (String 类型 )拍照时设备方向信息

  可取值： "up" - 默认方向（手机横持拍照），对应 Exif 中的 1，或无 orientation 信息； "up-mirrored" - 同 up，但镜像翻转，对应 Exif 中的 2； "down" - 旋转180度，对应 Exif 中的 3； "down-mirrored" - 同 down，但镜像翻转，对应 Exif 中的 4； "left-mirrored" - 同 left，但镜像翻转，对应 Exif 中的 5； "right" - 顺时针旋转90度，对应 Exif 中的 6； "right-mirrored" - 同 right，但镜像翻转，对应 Exif 中的 7； "left" - 逆时针旋转90度，对应 Exif 中的 8。 更多详情参考图片扩展中的方向信息：http://sylvana.net/jpegcrop/exif_orientation.html。

- path: (String 类型 )图片的本地路径

  绝对路径，以"file://"开头。

- type: (String 类型 )图片格式
- width: (Number 类型 )图片的原始宽度

  单位为像素（px），不考虑旋转。

# VideoInfo

JSON对象，视频文件信息对象

## 说明：

通过getVideoInfo方法的成功回调函数返回

## 属性：

- duration: (Number 类型 )视频长度

  单位为秒（s）。

- height: (Number 类型 )视频高度

  视频的真实像素值高度。

- resolution: (String 类型 )视频分辨率

  格式为“宽*高”，如“1280*720”。

- size: (Number 类型 )文件大小

  单位为字节。

- width: (Number 类型 )视频宽度

  视频的真实像素值宽度。

# 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 : 无

# IOSuccessCallback

成功回调函数

    void onSuccess(event){
    }

## 说明：

不同接口触发的成功回调参数event包含的属性存在差异，具体参考对应的接口描述说明。

## 参数：

- event: ( json ) 必选 回调参数
  回调参数包含的属性由调用接口决定，具体参考对应的接口描述说明。

## 返回值：

void : 无

# IOFailCallback

失败回调函数

    function void onFail(DOMException error){
    	// Handle error
    	var code = error.code; // 错误编码
    	var message = error.message; // 错误描述信息
    }

## 参数：

- error: ( DOMException ) 必选 回调参数，错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无

# IOCompleteCallback

操作完成回调函数

    function void onComplete(event){
    }

## 说明：

调用成功或失败都会触发此回调。

## 参数：

- event: ( json ) 可选 回调参数
  调用成功时回调参数与IOSuccessCallback一致，调用失败时回调参数与IOFailCallback一致。

## 返回值：

void : 无