HTML5 File API 简介

最新推荐文章于 2024-03-11 15:00:43 发布

原创最新推荐文章于 2024-03-11 15:00:43 发布 · 2.2k 阅读

1 ·

CC 4.0 BY-SA版权

HTML 专栏收录该内容

3 篇文章

订阅专栏

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

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