Reading local files in JavaScript

By Eric Bidelman

Опубликовано: Июнь 18th, 2010 Comments: 0

Введение

Наконец появилась возможность взаимодействия с локальными файлами с помощью HTML5. Для этого служит спецификация API файлов. В частности, API файлов можно использовать для создания уменьшенных изображений при передаче соответствующих картинок на сервер или для того, чтобы приложение могло сохранить ссылку на файл, если пользователя нет в сети. Кроме того, с помощью кода на стороне клиента можно проверить, отвечает ли тип MIME загружаемого файла его расширению, или установить ограничения по размеру.

В спецификации указаны некоторые интерфейсы для доступа к файлам в локальной файловой системе.

File – отдельный файл. Такая информация, как название, размер файла, тип MIME и ссылка на обработчик, доступна только для чтения.
FileList – последовательность объектов File в виде массива, позволяющая, например, реализовать функцию <input type="file" multiple> или перетаскивание папки с файлами с рабочего стола.
Blob – позволяет разделить файл на фрагменты заданной величины.

В сочетании с описанными выше структурами данных интерфейс FileReader можно использовать для асинхронного чтения файла с помощью знакомых функций обработки событий в JavaScript. Это позволяет отслеживать процесс чтения, обнаруживать ошибки и определять, что загрузка завершена. API во многом напоминают модель событий XMLHttpRequest.

Примечание. На момент составления этого руководства API, необходимые для работы с локальными файлами, поддерживались в браузерах Chrome 6.0 и Firefox 3.6. Начиная с версии Firefox 3.6.3 метод File.slice() не поддерживается.

Выбор файлов

Сначала проверьте, поддерживает ли ваш браузер API файлов.

// Check for the various File API support.
if (window.File && window.FileReader && window.FileList && window.Blob) {
  // Great success! All the File APIs are supported.
} else {
  alert('The File APIs are not fully supported in this browser.');
}

Разумеется, если для работы приложения требуются лишь некоторые из этих API, скорректируйте фрагмент кода соответствующим образом.

Выбор файлов с помощью формы ввода данных

Самый простой способ загрузки файлов – использование стандартного элемента <input type="file">. JavaScript возвращает список выбранных объектов File в виде объекта FileList. Вот пример использования атрибута multiple для выбора сразу нескольких файлов:

<input type="file" id="files" name="files[]" multiple />
<output id="list"></output>

<script>
  function handleFileSelect(evt) {
    var files = evt.target.files; // FileList object

    // files is a FileList of File objects. List some properties.
    var output = [];
    for (var i = 0, f; f = files[i]; i++) {
      output.push('<li><strong>', escape(f.name), '</strong> (', f.type || 'n/a', ') - ',
                  f.size, ' bytes, last modified: ',
                  f.lastModifiedDate.toLocaleDateString(), '</li>');
    }
    document.getElementById('list').innerHTML = '<ul>' + output.join('') + '</ul>';
  }

  document.getElementById('files').addEventListener('change', handleFileSelect, false);
</script>

Пример: выбор файлов с помощью формы ввода данных. Попробуйте сами!

Выбор файлов с помощью перетаскивания

Еще одним способом загрузки файлов является их перетаскивание с рабочего стола в браузер. Чтобы включить поддержку перетаскивания, достаточно внести небольшие изменения в код из предыдущего примера.

<div id="drop_zone">Drop files here</div>
<output id="list"></output>

<script>
  function handleFileSelect(evt) {
    evt.stopPropagation();
    evt.preventDefault();

    var files = evt.dataTransfer.files; // FileList object.

    // files is a FileList of File objects. List some properties.
    var output = [];
    for (var i = 0, f; f = files[i]; i++) {
      output.push('<li><strong>', escape(f.name), '</strong> (', f.type || 'n/a', ') - ',
                  f.size, ' bytes, last modified: ',
                  f.lastModifiedDate.toLocaleDateString(), '</li>');
    }
    document.getElementById('list').innerHTML = '<ul>' + output.join('') + '</ul>';
  }

  function handleDragOver(evt) {
    evt.stopPropagation();
    evt.preventDefault();
    evt.dataTransfer.dropEffect = 'copy'; // Explicitly show this is a copy.
  }

  // Setup the dnd listeners.
  var dropZone = document.getElementById('drop_zone');
  dropZone.addEventListener('dragover', handleDragOver, false);
  dropZone.addEventListener('drop', handleFileSelect, false);
</script>

Пример: выбор файлов с помощью перетаскивания. Попробуйте сами!

Перетащите сюда файлы

Примечание. Некоторые браузеры обрабатывают элементы <input type="file"> как целевые области для перетаскивания файлов. Попробуйте перетащить файлы в поле ввода в предыдущем примере.

Чтение файлов

А теперь самое интересное.

Получив ссылку на объект File, создайте экземпляр объекта FileReader, который сохранит его содержание в память. Как только завершается загрузка, на стороне пользователя вызывается событие onload. Его атрибут result можно использовать для доступа к данным в файле.

Существует четыре метода асинхронного чтения файлов с помощью объекта FileReader.

FileReader.readAsBinaryString(Blob|File) – свойство result содержит данные о файле или его фрагменте в виде строки бинарного кода. Каждый байт представлен целым числом от 0 до 255.
FileReader.readAsText(Blob|File, opt_encoding) – свойство result содержит данные о файле или его фрагменте в виде текстовой строки. По умолчанию используется кодировка UTF-8. Чтобы задать другой формат, используйте необязательный параметр кодировки opt_encoding.
FileReader.readAsDataURL(Blob|File) – свойство result содержит данные о файле или его фрагменте в виде схемы data:URL.
FileReader.readAsArrayBuffer(Blob|File) – свойство result содержит данные о файле или его фрагменте в виде объекта ArrayBuffer.

Если для объекта FileReader вызывается один из этих методов, то ход его обработки можно отслеживать с помощью атрибутов onloadstart, onprogress, onload, onabort, onerror и onloadend.

В примере ниже из выделенных пользователем файлов выбираются картинки, вызывается функция reader.readAsDataURL() и выводится уменьшенное изображение путем установки для атрибута src значения, представляющего URL данных.

<style>
  .thumb {
    height: 75px;
    border: 1px solid #000;
    margin: 10px 5px 0 0;
  }
</style>

<input type="file" id="files" name="files[]" multiple />
<output id="list"></output>

<script>
  function handleFileSelect(evt) {
    var files = evt.target.files; // FileList object

    // Loop through the FileList and render image files as thumbnails.
    for (var i = 0, f; f = files[i]; i++) {

      // Only process image files.
      if (!f.type.match('image.*')) {
        continue;
      }

      var reader = new FileReader();

      // Closure to capture the file information.
      reader.onload = (function(theFile) {
        return function(e) {
          // Render thumbnail.
          var span = document.createElement('span');
          span.innerHTML = ['<img class="thumb" src="', e.target.result,
                            '" title="', escape(theFile.name), '"/>'].join('');
          document.getElementById('list').insertBefore(span, null);
        };
      })(f);

      // Read in the image file as a data URL.
      reader.readAsDataURL(f);
    }
  }

  document.getElementById('files').addEventListener('change', handleFileSelect, false);
</script>

Пример: чтение файлов. Попробуйте сами!

Перетащите сюда папку с картинками.

Разделение файла на фрагменты

В некоторых случаях считывание всего файла в память не является оптимальным вариантом. Предположим, вы решили создать инструмент для асинхронной загрузки файлов. Чтобы увеличить ее скорость, можно разделить файл на фрагменты одинаковой величины, которые будут считываться и отправляться по отдельности. На сервере фрагменты будут снова объединяться в нужном порядке.

Интерфейс File поддерживает метод slice для разбиения файла на фрагменты. Первым аргументом этого метода является начальный байт файла, вторым – его последний байт, а третьим – необязательная строка с описанием типа содержания. Семантика этого метода недавно была изменена, и теперь необходимо использовать префикс браузера:

if (file.webkitSlice) {
  var blob = file.webkitSlice(startingByte, endindByte);
} else if (file.mozSlice) {
  var blob = file.mozSlice(startingByte, endindByte);
}
reader.readAsBinaryString(blob);

Ниже представлен код для считывания фрагментов файла. Обратите внимание на то, что вместо события onload в нем используется событие onloadend, а также проверяется условие evt.target.readyState.

<style>
  #byte_content {
    margin: 5px 0;
    max-height: 100px;
    overflow-y: auto;
    overflow-x: hidden;
  }
  #byte_range { margin-top: 5px; }
</style>

<input type="file" id="files" name="file" /> Read bytes: 
<span class="readBytesButtons">
  <button data-startbyte="0" data-endbyte="4">1-5</button>
  <button data-startbyte="5" data-endbyte="14">6-15</button>
  <button data-startbyte="6" data-endbyte="7">7-8</button>
  <button>entire file</button>
</span>
<div id="byte_range"></div>
<div id="byte_content"></div>

<script>
  function readBlob(opt_startByte, opt_stopByte) {

    var files = document.getElementById('files').files;
    if (!files.length) {
      alert('Please select a file!');
      return;
    }

    var file = files[0];
    var start = parseInt(opt_startByte) || 0;
    var stop = parseInt(opt_stopByte) || file.size - 1;

    var reader = new FileReader();

    // If we use onloadend, we need to check the readyState.
    reader.onloadend = function(evt) {
      if (evt.target.readyState == FileReader.DONE) { // DONE == 2
        document.getElementById('byte_content').textContent = evt.target.result;
        document.getElementById('byte_range').textContent = 
            ['Read bytes: ', start + 1, ' - ', stop + 1,
             ' of ', file.size, ' byte file'].join('');
      }
    };

    if (file.webkitSlice) {
      var blob = file.webkitSlice(start, stop + 1);
    } else if (file.mozSlice) {
      var blob = file.mozSlice(start, stop + 1);
    }
    reader.readAsBinaryString(blob);
  }
  
  document.querySelector('.readBytesButtons').addEventListener('click', function(evt) {
    if (evt.target.tagName.toLowerCase() == 'button') {
      var startByte = evt.target.getAttribute('data-startbyte');
      var endByte = evt.target.getAttribute('data-endbyte');
      readBlob(startByte, endByte);
    }
  }, false);
</script>

Пример: разделение файла на фрагменты. Попробуйте сами!

Считать байт:

Контроль хода чтения

Одним из преимуществ асинхронной обработки событий является возможность отслеживать ход чтения: это особенно удобно при работе с большими файлами, для контроля ошибок и для определения момента завершения чтения.

Ход чтения можно отслеживать с помощью событий onloadstart и onprogress.

Ниже приведен код, отображающий строку хода чтения. Чтобы оценить его в действии, загрузите файл, имеющий большой размер или находящийся на удаленном диске.

<style>
  #progress_bar {
    margin: 10px 0;
    padding: 3px;
    border: 1px solid #000;
    font-size: 14px;
    clear: both;
    opacity: 0;
    -moz-transition: opacity 1s linear;
    -o-transition: opacity 1s linear;
    -webkit-transition: opacity 1s linear;
  }
  #progress_bar.loading {
    opacity: 1.0;
  }
  #progress_bar .percent {
    background-color: #99ccff;
    height: auto;
    width: 0;
  }
</style>

<input type="file" id="files" name="file" />
<button onclick="abortRead();">Cancel read</button>
<div id="progress_bar"><div class="percent">0%</div></div>

<script>
  var reader;
  var progress = document.querySelector('.percent');

  function abortRead() {
    reader.abort();
  }

  function errorHandler(evt) {
    switch(evt.target.error.code) {
      case evt.target.error.NOT_FOUND_ERR:
        alert('File Not Found!');
        break;
      case evt.target.error.NOT_READABLE_ERR:
        alert('File is not readable');
        break;
      case evt.target.error.ABORT_ERR:
        break; // noop
      default:
        alert('An error occurred reading this file.');
    };
  }

  function updateProgress(evt) {
    // evt is an ProgressEvent.
    if (evt.lengthComputable) {
      var percentLoaded = Math.round((evt.loaded / evt.total) * 100);
      // Increase the progress bar length.
      if (percentLoaded < 100) {
        progress.style.width = percentLoaded + '%';
        progress.textContent = percentLoaded + '%';
      }
    }
  }

  function handleFileSelect(evt) {
    // Reset progress indicator on new file selection.
    progress.style.width = '0%';
    progress.textContent = '0%';

    reader = new FileReader();
    reader.onerror = errorHandler;
    reader.onprogress = updateProgress;
    reader.onabort = function(e) {
      alert('File read cancelled');
    };
    reader.onloadstart = function(e) {
      document.getElementById('progress_bar').className = 'loading';
    };
    reader.onload = function(e) {
      // Ensure that the progress bar displays 100% at the end.
      progress.style.width = '100%';
      progress.textContent = '100%';
      setTimeout("document.getElementById('progress_bar').className='';", 2000);
    }

    // Read in the image file as a binary string.
    reader.readAsBinaryString(evt.target.files[0]);
  }

  document.getElementById('files').addEventListener('change', handleFileSelect, false);
</script>

Пример: отслеживание хода чтения. Попробуйте сами!

Совет. Чтобы сделать контроль хода чтения еще более наглядным, загрузите файл, имеющий большой размер или находящийся на удаленном диске.

Ссылки

Спецификация API файлов
Спецификация интерфейса FileReader
Спецификация интерфейса Blob
Спецификация интерфейса FileError
Спецификация ProgressEvent

HTML5 Rocks

Чтение файлов в JavaScript с помощью API файлов