HTML5 File API 简介

File API 有以下几部分 JavaScript 类组成：

• 读取、操作文件的类：File/Blob, FileList, FileReader
• 创建、写入文件的类：BlobBuilder, FileWriter
• 目录、文件系统访问的类：DirectoryReader, FileEntry/DirectoryEntry,LocalFileSystem

1.File

概要

File 接口提供了文件的信息，以及文件内容的存取方法。

对象可以用来获取某个文件的信息,还可以用来读取这个文件的内容.通常情况下,File对象是来自用户在一个<input>元素上选择文件后返回的FileList对象,也可以是来自由拖放操作生成的 DataTransfer对象.

方法概述

DOMString getAsBinary(); 非标准 已废弃 Gecko 7.0

DOMString getAsDataURL(); 非标准 已废弃 Gecko 7.0

DOMString getAsText(in DOMString encoding); 非标准 已废弃 Gecko 7.0

属性

属性名	类型	描述
fileName	DOMString	当前File对象所引用文件的文件名. 只读. 已废弃 Gecko 7.0
fileSize	unsigned long long	当前File对象所引用文件的文件大小,单位为字节. 只读. 已废弃 Gecko 7.0
lastModifiedDate	jsval	当前File对象所引用文件最后修改时间. 只读. JSContext *cx Requires Gecko 15.0
mozFullPath	DOMString	当前File对象所引用文件的完整本地路径,只在特权代码中可用. 只读. 非标准 Requires Gecko 1.9.2
mozFullPathInternal	DOMString	这是一个内部使用的属性,没有做安全检查. 只读. Native code only! 非标准 Requires Gecko 2.0
mozLastModifiedDate	uint64_t	当前File对象所引用文件最后修改时间. 只读. Native code only! Requires Gecko 19.0
name	DOMString	当前File对象所引用文件的文件名. 只读. Requires Gecko 1.9.2
size	unsigned long long	当前File对象所引用文件的文件大小,单位为字节. 只读. Requires Gecko 1.9.2
type	DOMString	当前File对象所引用文件的文件类型(MIME类型). 只读. Requires Gecko 1.9.2

方法

些方法都是非标准的.想要读取一个文件的内容,你应该使用一个FileReader对象.查看如何在web应用程序中使用文件一文了解详情.

getAsBinary()

已废弃 Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

返回一个字符串,包含了文件内容的原始二进制形式.

注: 该方法已经过时,你应该使用 FileReader 对象的 readAsBinaryString()方法或者 readAsArrayBuffer()方法来替代.

DOMString getAsBinary();

参数

无

返回值

一个字符串,包含了文件内容的原始二进制形式.

getAsDataURL()

已废弃 Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

返回一个将所引用文件的完整内容进行编码后的data: URL字符串.

注: 该方法已经过时,你应该使用 FileReader对象的 readAsDataURL()方法来代替.

DOMString getAsDataURL();

参数

无

返回值

一个字符串,包含了将所引用文件的文件内容进行编码后的data: URL.

getAsText()

已废弃 Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

返回一个字符串,其内容为根据参数encoding指定的编码读取文件内容形成的文本.

注: 该方法已经过时,你应该使用 FileReader对象的 readAsText()方法来代替.

DOMString getAsText(
  in DOMString encoding
 );

参数

encoding

一个字符串,表示了返回数据所使用的编码,如果不指定该参数,则默认使用UTF-8编码.

返回值

一个字符串,其内容为根据参数encoding指定的编码读取文件内容形成的文本.

附注

Gecko附注

Gecko 6.0 note

(Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

从Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)开始,在特权代码(比如扩展中的代码)中,可以将一个nsIFile对象传入File构造函数,从而生成一个File对象.

Gecko 8.0 note

(Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5)

从Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5)开始,在XPCOM组件代码中,你可以直接使用new File来创建一个 File对象,而不需要像以前那样必须实例化一个nsIDOMFile对象.

浏览器兼容性

• Desktop
• Mobile

Feature	Chrome	Firefox (Gecko)	Internet Explorer	Opera	Safari (WebKit)
File	13 webkit	未实现	未实现	未实现	未实现
FileReader	6 webkit	4.0 moz	10	12	未实现
FileWriter	13 webkit	未实现	未实现	未实现	未实现
FileSystem	13 webkit	未实现	未实现	未实现	未实现
BlobBuilder	8 webkit	6.0 (6.0) 4.0 moz	10	未实现	未实现
BlobURL	8 webkit	4.0 4.0moz	10	未实现	未实现

2.Blob

一个Blob对象就是一个包含有只读原始数据的类文件对象.Blob对象中的数据并不一定得是JavaScript中的原生形式.File接口基于Blob,继承了Blob的功能,并且扩展支持了用户计算机上的本地文件.

创建Blob对象的方法有几种,可以调用Blob构造函数,还可以使用一个已有Blob对象上的slice()方法切出另一个Blob对象,还可以调用canvas对象上的toBlob方法.

属性

属性名	类型	描述
size	unsigned long long	Blob对象中所包含数据的大小. 只读.
type	DOMString	一个字符串,表明该Blob对象所包含数据的MIME类型.如果类型未知,则该值为空字符串. 只读.

构造函数

Blob Blob(
  [optional] Array parts,
  [optional] BlobPropertyBag properties
);

参数

parts

一个数组,包含了将要添加到 Blob对象中的数据.数组元素可以是任意多个的 ArrayBuffer,ArrayBufferView (typed array), Blob,或者 DOMString对象.

properties

一个对象,设置 Blob对象的一些属性.查看 BlobPropertyBag一节.

方法

slice()

返回一个新的Blob对象,包含了源Blob对象中指定范围内的数据.

Blob slice(
  optional long long start,
  optional long long end,
  optional DOMString contentType
};

参数

start 可选

开始索引,可以为负数,语法类似于数组的 slice方法.默认值为0.

end 可选

结束索引,可以为负数,语法类似于数组的 slice方法.默认值为 最后一个索引.

contentType 可选

新的 Blob对象的MIME类型,这个值将会成为新的 Blob对象的 type属性的值,默认为一个空字符串.

返回值

一个新的Blob对象,包含了源Blob对象中指定范围内的数据.

注意

如果start参数的值比源Blob对象的size属性的值还大,则返回的Blob对象的size值为0,也就是不包含任何数据.

BlobPropertyBag

一个包含有两个属性type和endings的对象.

type

设置该 Blob对象的 type属性.

endings(已废弃)

对应于 BlobBuilder.append()方法的 endings参数.该参数的值可以是"transparent"或者"native".

Blob构造函数用法举例

下面的代码:

var aFileParts = ["<a id=\"a\"><b id=\"b\">hey!<\/b><\/a>"];
var oMyBlob = new Blob(aFileParts, { "type" : "text\/xml" }); // the blob

等价于:

var oBuilder = new BlobBuilder();
var aFileParts = ["<a id=\"a\"><b id=\"b\">hey!<\/b><\/a>"];
oBuilder.append(aFileParts[0]);
var oMyBlob = oBuilder.getBlob("text\/xml"); // the blob

BlobBuilder接口提供了另外一种创建Blob对象的方式,但该方式现在已经废弃,所以不应该再使用了.

例子:使用类型数组和Blob对象创建一个对象URL

使用FileList

所有type属性(attribute)为file的 <input> 元素都有一个files属性(property),用来存储用户所选择的文件. 例如:

<input id="fileItem" type="file">

下面的一行代码演示如何获取到一个FileList对象中的第一个文件(File 对象):

var file = document.getElementById('fileItem').files[0];

方法概述

File item(index);

Edit属性

属性名	类型	描述
length	integer	一个只读的整数值,用来返回该FileList对象中的文件数量

方法

Edititem()

根据给定的索引值.返回FileList对象中对应的File对象.

File item(
   index
 );

Edit参数

index

File对象在FileList对象中的索引值,从0开始.

Edit返回值

所请求的File对象.

例子

这个例子迭代了用户通过一个input元素选择的多个文件:

// fileInput是一个 HTML input 元素: <input type="file" id="myfileinput" multiple>
var fileInput = document.getElementById("myfileinput");

// files 是一个 FileList 对象(类似于NodeList对象)
var files = fileInput.files;
var file;

//遍历所有文件
for (var i = 0; i < files.length; i++) {

    // 取得一个文件
    file = files.item(i);
    // 这样也行
    file = files[i];
    // 取得文件名
    alert(file.name);
}

下面是一个更完整的例子.

<!DOCTYPE HTML>
<html>
<head>
</head>
<body>
// multiple属性可以让用户能选择多个文件

<input id="myfiles" multiple type="file">

</body>

<script>

var pullfiles=function(){ 
    // 获取到input元素
    var fileInput = document.querySelector("#myfiles");
    var files = fileInput.files;
    // 获取到所选文件数量 
    var fl=files.length;
    var i=0;

    while ( i < fl) {
        var file = files[i];
        alert(file.name);
        i++;
    }    
}

// 设置change事件处理函数
document.querySelector("#myfiles").onchange=pullfiles;

</script>

</html>

4.FileReader
使用FileReader对象,web应用程序可以异步的读取存储在用户计算机上的文件(或者原始数据缓冲)内容,可以使用File对象或者Blob对象来指定所要处理的文件或数据.其中File对象可以是来自用户在一个<input>元素上选择文件后返回的FileList对象,也可以来自拖放操作生成的 DataTransfer对象,还可以是来自在一个HTMLCanvasElement上执行mozGetAsFile()方法后的返回结果.
想要创建一个FileReader对象,很简单,如下:
var reader = new FileReader();

如何在web应用程序中使用文件一文中有更详细的解释和例子.

方法概述

void abort();

void readAsArrayBuffer(in Blob blob);

void readAsBinaryString(in Blob blob);

void readAsDataURL(in Blob blob);

void readAsText(in Blob blob, [optional] in DOMString encoding);

状态常量

常量名	值	描述
EMPTY	0	还没有加载任何数据.
LOADING	1	数据正在被加载.
DONE	2	已完成全部的读取请求.

属性

属性名	类型	描述
error	DOMError	在读取文件时发生的错误. 只读.
readyState	unsigned short	表明FileReader对象的当前状态. 值为State constants中的一个. 只读
result	jsval	读取到的文件内容.这个属性只在读取操作完成之后才有效,并且数据的格式取决于读取操作是由哪个方法发起的. 只读.

方法

abort()

中止该读取操作.在返回时,readyState属性的值为DONE.

void abort();

参数

无.

抛出的异常

DOM_FILE_ABORT_ERR

当该FileReader对象没有在进行读取操作时(也就是readyState属性的值不为 LOADING时),调用 abort()方法会抛出该异常.

Note: 实现于Gecko 6.0.

readAsArrayBuffer()

Requires Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

开始读取指定的Blob对象或File对象中的内容. 当读取操作完成时,readyState属性的值会成为DONE,如果设置了onloadend事件处理程序,则调用之.同时,result属性中将包含一个ArrayBuffer对象以表示所读取文件的内容.

void readAsArrayBuffer(
  in Blob blob
);

参数

blob

将要读取到一个 ArrayBuffer中的 Blob对象或者 File对象.

readAsBinaryString()

开始读取指定的Blob对象或File对象中的内容. 当读取操作完成时,readyState属性的值会成为DONE,如果设置了onloadend事件处理程序,则调用之.同时,result属性中将包含所读取文件的原始二进制数据.

void readAsBinaryString(
  in Blob blob
);

参数

blob

将要读取的 Blob对象或者 File对象.

readAsDataURL()

开始读取指定的Blob对象或File对象中的内容. 当读取操作完成时,readyState属性的值会成为DONE,如果设置了onloadend事件处理程序,则调用之.同时,result属性中将包含一个data: URL格式的字符串以表示所读取文件的内容.

void readAsDataURL(
  in Blob blob
);

参数

file

将要读取的 Blob对象或者 File对象.

例子

这个方法很有用,比如,可以实现图片的本地预览(在线演示):

<!doctype html>
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
<title>Image preview example</title>
<script type="text/javascript">
oFReader = new FileReader(), rFilter = /^(?:image\/bmp|image\/cis\-cod|image\/gif|image\/ief|image\/jpeg|image\/jpeg|image\/jpeg|image\/pipeg|image\/png|image\/svg\+xml|image\/tiff|image\/x\-cmu\-raster|image\/x\-cmx|image\/x\-icon|image\/x\-portable\-anymap|image\/x\-portable\-bitmap|image\/x\-portable\-graymap|image\/x\-portable\-pixmap|image\/x\-rgb|image\/x\-xbitmap|image\/x\-xpixmap|image\/x\-xwindowdump)$/i;

oFReader.onload = function (oFREvent) {
  document.getElementById("uploadPreview").src = oFREvent.target.result;
};

function loadImageFile() {
  if (document.getElementById("uploadImage").files.length === 0) { return; }
  var oFile = document.getElementById("uploadImage").files[0];
  if (!rFilter.test(oFile.type)) { alert("You must select a valid image file!"); return; }
  oFReader.readAsDataURL(oFile);
}
</script>
</head>

<body onload="loadImageFile();">
  <form name="uploadForm">
    <table>
      <tbody>
        <tr>
          <td><img id="uploadPreview" style="width: 100px; height: 100px;" src="data:image/svg+xml,%3C%3Fxml%20version%3D%221.0%22%3F%3E%0A%3Csvg%20width%3D%22153%22%20height%3D%22153%22%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%3E%0A%20%3Cg%3E%0A%20%20%3Ctitle%3ENo%20image%3C/title%3E%0A%20%20%3Crect%20id%3D%22externRect%22%20height%3D%22150%22%20width%3D%22150%22%20y%3D%221.5%22%20x%3D%221.500024%22%20stroke-width%3D%223%22%20stroke%3D%22%23666666%22%20fill%3D%22%23e1e1e1%22/%3E%0A%20%20%3Ctext%20transform%3D%22matrix%286.66667%2C%200%2C%200%2C%206.66667%2C%20-960.5%2C%20-1099.33%29%22%20xml%3Aspace%3D%22preserve%22%20text-anchor%3D%22middle%22%20font-family%3D%22Fantasy%22%20font-size%3D%2214%22%20id%3D%22questionMark%22%20y%3D%22181.249569%22%20x%3D%22155.549819%22%20stroke-width%3D%220%22%20stroke%3D%22%23666666%22%20fill%3D%22%23000000%22%3E%3F%3C/text%3E%0A%20%3C/g%3E%0A%3C/svg%3E" alt="Image preview" /></td>
          <td><input id="uploadImage" type="file" name="myPhoto" onchange="loadImageFile();" /></td>
        </tr>
      </tbody>
    </table>

    <p><input type="submit" value="Send" /></p>
  </form>
</body>
</html>

注: IE10以下的版本不支持 FileReader()构造函数.不过可以利用滤镜来兼容旧版本的IE: 兼容IE的图片本地预览.

readAsText()

开始读取指定的Blob对象或File对象中的内容. 当读取操作完成时,readyState属性的值会成为DONE,如果设置了onloadend事件处理程序,则调用之.同时,result属性中将包含一个字符串以表示所读取的文件内容.

void readAsText(
  in Blob blob,
  in DOMString encoding 可选
);

参数

blob

将要读取的 Blob对象或者 File对象.

encoding 可选

一个字符串,表示了返回数据所使用的编码.如果不指定,默认为UTF-8.

事件处理程序

onabort

当读取操作被终止时调用.

onerror

当读取操作发生错误时调用.

onload

当读取操作成功完成时调用.

onloadend

当读取操作完成时调用,不管是成功还是失败.该处理程序在 onload或者 onerror之后调用.

onloadstart

当读取操作将要开始之前调用.

onprogress

在读取数据过程中周期性调用.

5.