选择用户本地设备上的文件并与其交互是 Web 最常用的功能之一。它可让用户选择文件并将其上传到服务器,例如在分享照片或提交税务单据时。它还允许网站读取和操纵它们,而无需通过网络传输数据。本页详细介绍了如何使用 JavaScript 与文件交互。
新型 File System Access API
File System Access API 提供对用户本地系统上的文件和目录执行读写操作的方法。Chrome 和 Edge 等大多数基于 Chromium 的浏览器都提供此功能如需了解详情,请参阅 File System Access API。
由于 File System Access API 并非与所有浏览器都兼容,因此我们建议您使用 browser-fs-access,这是一个帮助程序库,可在新 API 可用时使用新 API,并在新 API 不可用时回退到旧方法。
以经典方式处理文件
本指南介绍了如何使用旧版 JavaScript 方法与文件交互。
选择文件
选择文件的方式主要有两种:一种是使用 HTML 输入元素,一种是使用拖放区域。
HTML 输入元素
用户选择文件的最简单方法是使用 <input type="file">
元素,所有主流浏览器都支持该元素。点击该按钮后,用户可以使用操作系统的内置文件选择界面选择一个或多个文件(如果包含 multiple
属性)。当用户选择完一个或多个文件后,会触发该元素的 change
事件。您可以通过 event.target.files
访问文件列表,它是一个 FileList
对象。FileList
中的每一项都是一个 File
对象。
<!-- The `multiple` attribute lets users select multiple files. -->
<input type="file" id="file-selector" multiple>
<script>
const fileSelector = document.getElementById('file-selector');
fileSelector.addEventListener('change', (event) => {
const fileList = event.target.files;
console.log(fileList);
});
</script>
以下示例允许用户使用操作系统的内置文件选择界面选择多个文件,然后将每个选定文件记录到控制台中。
限制用户可以选择的文件类型
在某些情况下,您可能希望限制用户可以选择的文件类型。例如,图片编辑应用应只接受图片,不能接受文本文件。如需设置文件类型限制,请将 accept
属性添加到输入元素中,以指定接受哪些文件类型:
<input type="file" id="file-selector" accept=".jpg, .jpeg, .png">
自定义拖放
在某些浏览器中,<input type="file">
元素也是一个拖放目标,允许用户将文件拖放到您的应用中。不过,此放置目标很小,可能不好用。相反,在使用 <input type="file">
元素提供核心功能后,您可以提供较大的自定义拖放界面。
选择停靠区
拖放界面取决于应用的设计。您可能只想将窗口的一部分用作拖放界面,但您也可以使用整个窗口。
![Squoosh(一款图片压缩 Web 应用)的屏幕截图。](https://web.developers.google.cn/static/articles/read-files/image/a-screenshot-squoosh-i-9973c866302e4.png?authuser=0000&hl=el)
图片压缩应用 Squoosh 允许用户将图片拖动到窗口中的任意位置,然后点击选择一张图片以调用 <input type="file">
元素。无论您选择将哪个拖放区域作为放置区,请务必明确告知用户,他们可以将文件拖动到该界面上。
定义拖放区域
如需将某个元素设为拖放区域,请为以下两个事件创建监听器:dragover
和 drop
。dragover
事件会更新浏览器界面,直观地表明拖放操作正在创建文件的副本。drop
事件会在用户将文件拖放到 Surface 后触发。与输入元素一样,您可以通过 event.dataTransfer.files
(一个 FileList
对象)访问文件列表。FileList
中的每一项都是一个 File
对象。
const dropArea = document.getElementById('drop-area');
dropArea.addEventListener('dragover', (event) => {
event.stopPropagation();
event.preventDefault();
// Style the drag-and-drop as a "copy file" operation.
event.dataTransfer.dropEffect = 'copy';
});
dropArea.addEventListener('drop', (event) => {
event.stopPropagation();
event.preventDefault();
const fileList = event.dataTransfer.files;
console.log(fileList);
});
event.stopPropagation()
和 event.preventDefault()
会停止浏览器的默认行为,改为运行代码。如果没有它们,浏览器就会离开您的网页,并打开用户在浏览器窗口中放置的文件。
如需观看现场演示,请参阅自定义拖放。
能否使用目录?
遗憾的是,还没有一个好的方法使用 JavaScript 访问目录。
<input type="file">
元素的 webkitdirectory
属性可让用户选择一个或多个目录。除了适用于 Android 的 Firefox 和 iOS 上的 Safari 外,大多数主流浏览器都支持此扩展程序。
如果启用了拖放功能,用户可能会尝试将目录拖动到拖放区域。当拖放事件触发时,它会包含目录的 File
对象,但不提供对目录中任何文件的访问权限。
读取文件元数据
File
对象包含有关文件的元数据。大多数浏览器都会提供文件名、文件大小和 MIME 类型,但不同的浏览器可能会提供不同或其他信息,具体取决于平台。
function getMetadataForFileList(fileList) {
for (const file of fileList) {
// Not supported in Safari for iOS.
const name = file.name ? file.name : 'NOT SUPPORTED';
// Not supported in Firefox for Android or Opera for Android.
const type = file.type ? file.type : 'NOT SUPPORTED';
// Unknown cross-browser support.
const size = file.size ? file.size : 'NOT SUPPORTED';
console.log({file, name, type, size});
}
}
您可以在 input-type-file
演示中查看此操作的实际效果。
读取文件的内容
使用 FileReader
将 File
对象的内容读取到内存中。您可以指示 FileReader
以数组缓冲区、数据网址或文本的形式读取文件:
function readImage(file) {
// Check if the file is an image.
if (file.type && !file.type.startsWith('image/')) {
console.log('File is not an image.', file.type, file);
return;
}
const reader = new FileReader();
reader.addEventListener('load', (event) => {
img.src = event.target.result;
});
reader.readAsDataURL(file);
}
此示例读取用户提供的 File
,然后将其转换为数据网址,并使用该数据网址在 img
元素中显示图片。如需了解如何验证用户是否已选择图片文件,请参阅 read-image-file
演示。
监控文件读取进度
读取大型文件时,提供某种用户体验来告知用户读取进度会很有帮助。为此,请使用 FileReader
提供的 progress
事件。progress
事件有两个属性:loaded
(读取量)和 total
(读取量)。
function readFile(file) {
const reader = new FileReader();
reader.addEventListener('load', (event) => {
const result = event.target.result;
// Do something with result
});
reader.addEventListener('progress', (event) => {
if (event.loaded && event.total) {
const percent = (event.loaded / event.total) * 100;
console.log(`Progress: ${Math.round(percent)}`);
}
});
reader.readAsDataURL(file);
}
主打图片,作者:Unsplash 用户 Vincent Botta