File API

File API

Версия документа от 18 августа 2020 года. Ссылка на оригинальную версию документа https://w3c.github.io/FileAPI/

 

Аннотация

Эта спецификация предоставляет API для представления файловых объектов в веб-приложениях, а также для их программного выбора и доступа к их данным. Это включает:

  • Интерфейс FileList, который представляет собой массив индивидуально выбранных файлов из базовой системы. Пользовательский интерфейс для выбора может быть вызван через <input type = "file">, т.е. когда элемент ввода находится в состоянии загрузки файла [HTML].
  • Интерфейс Blob, который представляет неизменяемые необработанные двоичные данные и позволяет получить доступ к диапазонам байтов в объекте Blob как отдельному Blob.
  • Интерфейс File, который включает информационные атрибуты только для чтения о файле, такие как его имя и дата последнего изменения (на диске) файла.
  • Интерфейс FileReader, который предоставляет методы для чтения File или Blob и модель событий для получения результатов этих чтений.
  • Схема URL-адресов для использования с двоичными данными, такими как файлы, чтобы на них можно было ссылаться в веб-приложениях.

Кроме того, эта спецификация определяет объекты, которые будут использоваться в многопоточных веб-приложениях для синхронного чтения файлов.

Требования и варианты использования раскрывают мотивацию этой спецификации.

Этот API предназначен для использования в сочетании с другими API и элементами на веб-платформе, в частности: XMLHttpRequest (например, с перегруженным методом send() для аргументов File или Blob), postMessage(), DataTransfer (часть API перетаскивания и бросания, определенный в [HTML]) и Web Workers. Кроме того, должна быть возможность программно получить список файлов из элемента ввода <input>, когда он находится в состоянии File Upload (загрузки файла) [HTML]. Эти виды поведения определены в соответствующих связанных спецификациях.

 

Оглавление

1. Введение
2. Терминология и алгоритмы
3. Интерфейс Blob и двоичные данные
3.1. Конструкторы
3.1.1. Параметры конструктора
3.2. Атрибуты
3.3. Методы и параметры
3.3.1. Метод slice()
3.3.2. Метод stream()
3.3.3. Метод text()
3.3.4. Метод arrayBuffer()
4. Интерфейс File
4.1. Конструктор
4.1.1. Параметры конструктора
4.2. Атрибуты
5. Интерфейс FileList
5.1. Атрибуты
5.2. Методы и параметры
6. Чтение данных
6.1. Источник задачи чтения файла
6.2. FileReader API
6.2.1. Атрибуты содержимого обработчика событий
6.2.2. Состояния чтения файлов
6.2.3. Чтение файла или большого двоичного объекта
6.2.3.1. Метод readAsDataURL()
6.2.3.2. Метод readAsText()
6.2.3.3. Метод readAsArrayBuffer()
6.2.3.4. Метод readAsBinaryString()
6.2.3.5. Метод abort()
6.3. Данные упаковки
6.4. События
6.4.1. Резюме события
6.4.2. Сводка инвариантов событий
6.5. Чтение по темам
6.5.1. API FileReaderSync
6.5.1.1. Конструкторы
6.5.1.2. Метод readAsText()
6.5.1.3. Метод readAsDataURL()
6.5.1.4. Метод readAsArrayBuffer()
6.5.1.5. Метод readAsBinaryString()
7. Ошибки и исключения
7.1. Создание исключения или возврат ошибки
8. URL-адрес для ссылки на Blob и MediaSource
8.1. Введение
8.2. Модель
8.3. Модель разыменования для URL-адресов больших двоичных объектов
8.3.1. Происхождение URL-адресов больших двоичных объектов
8.3.2. Время жизни URL-адресов больших двоичных объектов
8.4. Создание и отзыв URL-адреса большого двоичного объекта
8.4.1. Примеры создания и отзыва URL-адреса большого двоичного объекта
9. Вопросы безопасности и конфиденциальности
10. Требования и варианты использования
Благодарности
Соответствие
Условные обозначения документа
Соответствующие алгоритмы
Индекс
Термины, определенные в данной спецификации
Термины определены ссылкой
Ссылки
Нормативные ссылки
Информативные ссылки
Индекс IDL
Указатель проблем

 

1. Введение

Этот раздел носит информативный характер.

Веб-приложения должны иметь возможность манипулировать как можно более широким диапазоном пользовательского ввода, включая файлы, которые пользователь может пожелать загрузить на удаленный сервер или манипулировать внутри полнофункционального веб-приложения. Эта спецификация определяет базовые представления файлов, списки файлов, ошибки, возникающие при доступе к файлам, и программные способы чтения файлов. Кроме того, эта спецификация также определяет интерфейс, который представляет «необработанные данные» (raw data), которые могут асинхронно обрабатываться в основном потоке соответствующих пользовательских агентов. Интерфейсы и API, определенные в этой спецификации, могут использоваться с другими интерфейсами и API, доступными для веб-платформы.

Интерфейс File представляет данные файла, обычно получаемые из базовой файловой системы, а интерфейс Blob («Большой двоичный объект» (Binary Large Object) — имя, первоначально введенное для веб-API в Google Gears) представляет неизменяемые необработанные данные. Чтение файла File или большого двоичного объекта Blob должно происходить асинхронно в основном потоке с дополнительным синхронным API, используемым в многопоточных веб-приложениях. Асинхронный API для чтения файлов предотвращает блокировку и «зависание» (freezing) пользовательского интерфейса в основном потоке пользовательского агента. Эта спецификация определяет асинхронный API на основе модели событий (event model) для чтения и доступа к данным файла File или большого двоичного объекта Blob. Объект FileReader предоставляет методы асинхронного чтения для доступа к данным этого файла с помощью атрибутов содержимого обработчика событий и запуска событий. Использование событий и обработчиков событий позволяет отдельным блокам кода отслеживать ход чтенияprogress of the read (что особенно полезно для удаленных дисков или смонтированных дисков, где производительность доступа к файлам может отличаться от локальных дисков) и состояния ошибок, которые могут возникнуть во время чтения файла. Пример будет иллюстративным.

 

Пример № 1

В приведенном ниже примере различные блоки кода обрабатывают условия выполнения, ошибки и успеха.

function startRead() {
  // получить элемент ввода через DOM

  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {

  var reader = new FileReader();

  // Прочитать файл в память как UTF-16
  reader.readAsText(readFile, "UTF-16");

  // Обработка прогресса, успеха и ошибок
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loaded и evt.total - свойства ProgressEvent
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // Увеличьте длину полосы прогона
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {
  // Получить данные прочитанного файла
  var fileString = evt.target.result;
  // Обработка дампа файла UTF-16
  if(utils.regexp.isChinese(fileString)) {
    // Китайские иероглифы + проверка имени
  }
  else {
    // запустить другой тест кодировки
  }
  // xhr.send(fileString)
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableError") {
    // Файл не может быть прочитан
  }
}

 

2. Терминология и алгоритмы

Когда эта спецификация говорит о завершении алгоритма (terminate an algorithm), пользовательский агент должен завершить алгоритм после завершения шага, на котором он находится. Методы асинхронного чтения, определенные в этой спецификации, могут возвращаться до того, как рассматриваемый алгоритм будет завершен, и могут быть прекращены вызовом abort().

  • Алгоритмы и шаги в этой спецификации используют следующие математические операции:
  • max (a, b) возвращает максимум a и b и всегда выполняется для целых чисел, как они определены в WebIDL [WebIDL]; в случае max (6,4) результат будет 6. Эта операция также определена в ECMAScript [ECMA-262].
  • min (a, b) возвращает минимум a и b и всегда выполняется для целых чисел, как они определены в WebIDL [WebIDL]; в случае min (6,4) результат будет 4. Эта операция также определена в ECMAScript [ECMA-262].
  • Математические сравнения, такие как <(меньше чем), ≤ (меньше или равно) и> (больше чем), такие же, как в ECMAScript [ECMA-262].

Термин Unix Epoch используется в этой спецификации для обозначения времени 00:00:00 UTC 1 января 1970 года (или 1970-01-01T00: 00: 00Z ISO 8601); это то же время, которое концептуально равно «0» в ECMA-262 [ECMA-262].

 

3. Интерфейс BLOB и двоичные данные

Объект Blob относится к байтовой последовательности и имеет:

  1. атрибут размера «size«, который представляет собой общее количество байтов в байтовой последовательности, и
  2. атрибут типа «type«, который представляет собой строку в кодировке ASCII в нижнем регистре, представляющую тип носителя байтовой последовательности.

Каждый Blob должен иметь внутреннее состояние моментального снимка (snapshot state), которое должно быть изначально установлено равным состоянию базового хранилища, если такое базовое хранилище существует. Дополнительное нормативное определение состояния снимка можно найти для File-ов.

[Exposed=(Window,Worker), Serializable]
interface Blob {
constructor(optional sequence<BlobPart> blobParts,
            optional BlobPropertyBag options = {});
readonly attribute unsigned long long size;
readonly attribute DOMString type;
// разрезать Blob на фрагменты с байтовым диапазоном
Blob slice(optional [Clamp] long long start,
           optional [Clamp] long long end,
           optional DOMString contentType);
// чтение из Blob
[NewObject] ReadableStream stream();
[NewObject] Promise<USVString> text();
[NewObject] Promise<ArrayBuffer> arrayBuffer();
};
enum EndingType { "transparent", "native" };
dictionary BlobPropertyBag {
DOMString type = "";
EndingType endings = "transparent";
};
typedef (BufferSource or Blob or USVString) BlobPart;

Объекты Blob — это сериализуемые объекты. Их шаги сериализации с заданным value и serialized:

1. Установите serialized.[[SnapshotState]] в состояние снимка value.
2. Установите serialized.[[ByteSequence]] равным базовой байтовой последовательности value.

Их этап десериализации (deserialization step) с учетом value и serialized:

1. Установите value состояние снимка как serialized.[[SnapshotState]].
2. Установить value базовую последовательность байтов как serialized.[[ByteSequence]].

Blob blob имеет связанный «алгоритм получения потока»  (get stream algorithm), который выполняет следующие шаги:

1. Пусть stream будет результатом создания объекта ReadableStream.
2. Параллельно выполните следующие шаги:
   1. Пока не все байты прочитаны из blob:
      1. Пусть байты bytes будут последовательностью байтов, полученной в результате чтения кусочка (chunk) из blob.
      2. Если произошла ошибка чтения файла, пока читаются байты bytes, обработайте ошибку потока stream  с указанием причины сбоя и прервите эти шаги.
      3. Поставить в очередь объект Uint8Array, обертывающий ArrayBuffer, содержащий байты bytes, в поток stream. Если это вызвало исключение, обработайте ошибку потока stream с этим исключением и прервите эти шаги.
      Проблема! (Нам нужно более конкретно указать, что на самом деле происходит при чтении из Blob, какие возможные ошибки могут произойти, возможно, что-то о размерах блоков и т. д.)
3. Вернуть stream

 

3.1. Конструкторы

Конструктор Blob() может быть вызван с нулем или несколькими параметрами. Когда вызывается конструктор Blob(), пользовательские агенты должны выполнить следующие шаги:

1. Если вызывается с нулевыми параметрами, вернуть новый объект Blob, состоящий из 0 байтов, с размером "size", равным 0, и с типом "type", установленным на пустую строку.
2. Пусть байты bytes будут результатом обработки частей большого двоичного объекта, заданных "blobParts" и "options".
3. Если член "type" аргумента "options" не является пустой строкой, выполните следующие подэтапы:
   1. Пусть t будет членом словаря "type". Если t содержит какие-либо символы вне диапазона от U+0020 до U+007E, тогда установите t в пустую строку и вернитесь с этих подшагов.
   2. Преобразуйте каждый символ в t в нижний регистр ASCII.
4. Вернуть объект Blob, ссылающийся на байты bytes как на связанную с ним последовательность байтов, с размером "size", установленным равным длине байтов bytes, и его типом "type", установленным на значение t из подшагов выше.

 

3.1.1. Параметры конструктора Blob()

Конструктор Blob() можно вызвать со следующими параметрами:

Последовательность blobParts

который принимает любое количество из следующих типов элементов и в любом порядке:

— Элементы BufferSource

— Элементы Blob

— Элементы USVString

Необязательный BlobPropertyBag

который принимает эти необязательные члены:

- type, строка в кодировке ASCII в нижнем регистре, представляющая медиа-тип Blob. Нормативные условия для этого члена приведены в 3.1 Конструкторы.
- endings, перечисление, которое может принимать значения «прозрачный» или «собственный» ("transparent" или "native"). По умолчанию установлено значение "transparent". Если установлено значение "native", окончания строк будут преобразованы в собственные в любых элементах USVString в blobParts.

 

Чтобы обработать части большого двоичного объекта (process blob parts) с учетом последовательности частей BlobPart и параметров BlobPropertyBag, выполните следующие действия:

1. Пусть байты bytes будут пустой последовательностью байтов.
2. По каждому элементу element по частям parts:
   1. Если элемент element является USVString, выполните следующие подшаги:
      1. Пусть s будет element.
      2. Если endings член options является "native", установите s равным результату преобразования окончаний строк в родные из element.
      3. Добавить результат кодировки UTF-8 s в байты bytes.
      Примечание. Алгоритм из WebIDL [WebIDL] заменяет несогласованные суррогаты в недопустимой строке utf-16 символами замены U+FFFD. Существуют сценарии, когда конструктор Blob может привести к потере данных из-за потерянных или зашифрованных последовательностей символов.
   2. Если element является BufferSource, получить копию байтов, содержащихся в источнике буфера, и добавить эти байты к bytes.
   3. Если element является Blob, добавьте байты, которые он представляет, к bytes.
   Примечание. "type" элемента массива Blob игнорируется и не влияет на "type" возвращаемого объекта Blob.
3. Вернуть bytes

 

Чтобы преобразовать окончания строк в собственные (convert line endings to native) в строке s, выполните следующие действия:

1. Пусть native line ending (окончание собственной строки) будет кодовой точкой U+000A LF.
2. Если соглашения базовой платформы должны представлять символы новой строки как последовательность возврата каретки и перевода строки, установите native line ending на кодовую точку U+000D CR, за которой следует кодовая точка U+000A LF.
3. Установите результат result в пустую строку.
4. Пусть position будет переменной положения для s, изначально указывающей на начало s.
5. Пусть token будет результатом сбора последовательности кодовых точек, которые не равны U+000A LF или U+000D CR с заданной позиции position.
6. Добавить токен token к результату result.
7. Пока позиция position не находится за концом s:
   1. Если кодовая точка в позиции position внутри s равна U+000D CR:
      1. Добавить окончание родной строки native line ending к результату result.
      2. Продвинуть позицию position на 1.
      3. Если позиция position не превышает конец s, а кодовая точка в позиции position в s равна U+000A LF, продвиньте позицию position на 1.
   2. В противном случае, если кодовая точка в позиции position внутри s равна U+000A LF, продвинуть позицию position на 1 и добавить окончание собственной строки native line ending к результату result.
   3. Пусть токен token будет результатом сбора последовательности кодовых точек, которые не равны U+000A LF или U+000D CR с заданной позиции position.
   4. Добавить токен token к результату result.
8. Вернуть result

 

Пример № 2

Примеры использования конструктора приведены ниже.

// Создайте новый объект Blob

var a = new Blob();

// Создайте 1024-байтовый ArrayBuffer
// буфер также может быть получен при чтении файла

var buffer = new ArrayBuffer(1024);

// Создавать объекты ArrayBufferView на основе буфера

var shorts = new Uint16Array(buffer, 512, 128);
var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);

var b = new Blob(["foobarbazetcetc" + "birdiebirdieboo"], {type: "text/plain;charset=utf-8"});

var c = new Blob([b, shorts]);

var a = new Blob([b, c, bytes]);

var d = new Blob([buffer, b, c, bytes]);

 

3.2. Атрибуты

Атрибут size

size, типа unsigned long long, только для чтения

Возвращает размер байтовой последовательности в байтах. При получении соответствующие пользовательские агенты должны возвращать общее количество байтов, которые могут быть прочитаны объектами FileReader или FileReaderSync, или 0, если у Blob нет байтов для чтения.

Атрибут type

type, тип DOMString, только для чтения

Строка в кодировке ASCII в нижнем регистре, представляющая медиа-тип Blob. При получении пользовательские агенты должны возвращать тип Blob в виде строки в кодировке ASCII в нижнем регистре, чтобы при преобразовании в последовательность байтов это был анализируемый тип MIME или пустая строка — 0 байтов — если тип не может быть определен.

Атрибут «type» может быть установлен самим веб-приложением посредством вызова конструктора и вызова slice(); в этих случаях дополнительные нормативные условия для этого атрибута находятся в §3.1 Конструкторы, §4.1 Конструктор и §3.3.1 Метод slice() соответственно. Пользовательские агенты также могут определять тип Blob, особенно если последовательность байтов берется из файла на диске; в этом случае дополнительные нормативные условия указаны в рекомендациях по типам файлов.

Примечание. Тип t объекта Blob считается анализируемым типом MIME, если выполнение синтаксического анализа алгоритма типа MIME в последовательность байтов, преобразованную из строки в кодировке ASCII, представляющей тип объекта Blob, не возвращает ошибку.

Примечание. Использование атрибута «type» информирует алгоритм данных пакета и определяет заголовок «Content-Type» при выборке (fetching) URL-адресов больших двоичных объектов.

 

3.3. Методы и параметры

3.3.1. Метод slice()

Метод slice() возвращает новый объект Blob с байтами в диапазоне от необязательного начального параметра «start«, до необязательного конечного параметра «end«, но не включая его, а также с атрибутом «type«, который является значением необязательного параметра contentType. Он должен действовать следующим образом:

1. Пусть O будет контекстным объектом Blob, для которого вызывается метод slice().

2. Необязательный параметр «start» — это значение для начальной точки вызова slice(), и его следует рассматривать как позицию байтового порядка, при этом нулевая позиция представляет первый байт. Пользовательские агенты должны обрабатывать slice() с нормализацией «start» в соответствии со следующим:

a. Если необязательный параметр «start» не используется в качестве параметра при выполнении этого вызова, пусть relativeStart будет 0.

b. Если «start» отрицательный, пусть relativeStart будет «max((size + start), 0)«.

c. В противном случае пусть relativeStart будет «min(start, size)«.

3. Необязательный конечный параметр «end» — это значение конечной точки вызова slice(). Пользовательские агенты должны обрабатывать slice() с «end«, нормализованным в соответствии со следующим:

a. Если необязательный параметр «end» не используется в качестве параметра при выполнении этого вызова, пусть relativeEnd будет «size«.

b. Если «end» отрицательный, пусть relativeEnd будет «max((size + end), 0)».

c. В противном случае пусть relativeEnd будет «min(end, size)».

4. Необязательный параметр «contentType» используется для установки строки в кодировке ASCII в нижнем регистре, представляющей тип носителя Blob. Пользовательские агенты должны обрабатывать slice() с contentType, нормализованным в соответствии со следующим:

a. Если параметр «contentType» не указан, пусть для relativeContentType будет установлена пустая строка.

b. В противном случае пусть для параметра relativeContentType будет установлено значение «contentType«, и выполните следующие подэтапы:

1. Если relativeContentType содержит какие-либо символы за пределами диапазона от U+0020 до U+007E, тогда установите relativeContentType в пустую строку и вернитесь с этих подшагов.

2. Преобразуйте каждый символ в relativeContentType в нижний регистр ASCII.

5. Пусть диапазон span равен «max((relativeEnd — relativeStart), 0)«.

6. Верните новый объект Blob S со следующими характеристиками:

a. S относится к диапазону последовательных байтов от O, начиная с байта в позиции порядка байтов relativeStart.

b. S.size = span

c. S.type = relativeContentType

 

Пример № 3

Приведенные ниже примеры иллюстрируют различные типы возможных вызовов slice(). Поскольку интерфейс File наследуется от интерфейса Blob, примеры основаны на использовании интерфейса File.

// получить элемент ввода через DOM

var file = document.getElementById('file').files[0];
if(file)
{
  // создать идентичную копию файла
  // два вызова ниже эквивалентны

  var fileClone = file.slice();
  var fileClone2 = file.slice(0, file.size);

  // разрезать файл на 1/2 части, начиная с середины файла
  // Обратите внимание на использование отрицательного числа

  var fileChunkFromEnd = file.slice(-(Math.round(file.size/2)));

  // разрезать файл на 1/2 части, начиная с начала файла

  var fileChunkFromStart = file.slice(0, Math.round(file.size/2));

  // файл среза от начала до 150 байт до конца

  var fileNoMetadata = file.slice(0, -150, "application/experimental");
}

3.3.2. Метод stream()

Метод stream() при вызове должен возвращать результат вызова get stream для объекта контекста (this).

 

3.3.3. Метод text()

При вызове метода text() необходимо выполнить следующие шаги:

1. Пусть stream будет результатом вызова get stream для объекта контекста.

2. Пусть reader будет результатом получения читателя из потока stream. Если это вызвало исключение, верните новое обещание, отклоненное с этим исключением.

3. Пусть обещание будет результатом чтения всех байтов из потока stream с помощью reader.

4. Вернуть результат преобразования обещания promise обработчиком выполнения, который возвращает результат выполнения декодирования UTF-8 для своего первого аргумента.

Примечание. Это отличается от поведения readAsText(), чтобы лучше согласовываться с text() Fetch-выборки. В частности, этот метод всегда будет использовать UTF-8 в качестве кодировки, в то время как FileReader может использовать другую кодировку в зависимости от типа большого двоичного объекта и переданного имени кодировки.

3.3.4. Метод arrayBuffer()

При вызове метода arrayBuffer() необходимо выполнить следующие действия:

1. Пусть stream будет результатом вызова get stream для объекта контекста.

2. Пусть reader будет результатом получения читателя из потока stream. Если это вызвало исключение, верните новое обещание, отклоненное с этим исключением.

3. Пусть обещание promise будет результатом чтения всех байтов из потока stream с помощью reader.

4. Вернуть результат преобразования обещания promise обработчиком выполнения, который возвращает новый ArrayBuffer, содержимое которого является его первым аргументом.

 

4. Интерфейс File

Объект File — это объект Blob с атрибутом «name«, который является строкой; он может быть создан в веб-приложении с помощью конструктора или является ссылкой на последовательность байтов из файла из базовой файловой системы (ОС).

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

Примечание. Это нетривиальное требование для пользовательских агентов, поэтому оно не является обязательным, но требуемым [RFC2119]. Пользовательские агенты должны стремиться установить для состояния моментального снимка объекта File состояние базового хранилища на диске в момент взятия ссылки. Если файл изменяется на диске после того, как была сделана ссылка, состояние моментального снимка файла будет отличаться от состояния базового хранилища. Пользовательские агенты могут использовать метки времени модификации и другие механизмы для поддержания состояния моментального снимка, но это оставлено как деталь реализации.

Когда объект File ссылается на файл на диске, пользовательские агенты должны возвращать тип этого файла и должны следовать приведенным ниже рекомендациям по типам файлов (file type guidelines):

  • Пользовательские агенты должны возвращать «type» в виде строки в кодировке ASCII в нижнем регистре, чтобы при преобразовании в соответствующую последовательность байтов это был анализируемый тип MIME или пустая строка — 0 байтов — если тип не может быть определен.
  • Когда файл имеет «type»  — «text/plain», пользовательские агенты НЕ ДОЛЖНЫ добавлять параметр набора символов в часть словаря параметров (dictionary of parameters) типа носителя [MIMESNIFF].
  • Пользовательские агенты не должны пытаться эвристически определять кодировку, включая статистические методы.

 

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
   constructor(sequence<BlobPart> fileBits,
      USVString fileName,
      optional FilePropertyBag options = {});
   readonly attribute DOMString name;
   readonly attribute long long lastModified;
};
dictionary FilePropertyBag : BlobPropertyBag {
   long long lastModified;
};

Объекты File — это сериализуемые объекты. Их шаги сериализации с заданным value и serialized:

1. Установите serialized.[[SnapshotState]] в состояние снимка value.

2. Установите serialized.[[ByteSequence]] равным базовой байтовой последовательности value.

3. Установите serialized. [[Name]] в значение атрибута «name» value.

4. Установите для параметра serialized. [[LastModified]] значение атрибута «lastModified» значения.

 

Их шаги десериализации с заданным value и serialized:

1. Установите состояние снимка значения value как serialized.[[SnapshotState]].

2. Установить базовую последовательность байтов значения value как serialized.[[ByteSequence]].

3. Инициализируйте значение атрибута «name» значения value как serialized.[[Name]].

4. Инициализируйте значение атрибута «lastModified» значения value как serialized.[[LastModified]].

 

4.1. Конструктор

Конструктор File вызывается с двумя или тремя параметрами в зависимости от того, используется ли необязательный параметр словаря. Когда вызывается конструктор File(), пользовательские агенты должны выполнить следующие шаги:

1. Пусть байты bytes будут результатом обработки частей большого двоичного объекта с учетом «fileBits» и «options«.

2. Пусть n будет новой строкой того же размера, что и аргумент «fileName» конструктора. Скопируйте каждый символ из «fileName» в n, заменив любой символ «/» (U+002F SOLIDUS) на «:» (U+003A COLON).

Примечание. В файловых системах базовой ОС используются разные соглашения для имен файлов; со сконструированными файлами, указание UTF-16 снижает двусмысленность при преобразовании имен файлов в байтовые последовательности.

3. Обработайте аргумент словаря FilePropertyBag, выполнив следующие подшаги:

1. Если член «type» предоставлен и не является пустой строкой, пусть t будет установлено равным члену словаря «type«. Если t содержит какие-либо символы вне диапазона от U+0020 до U+007E, тогда установите t в пустую строку и вернитесь с этих подшагов.

2. Преобразуйте каждый символ в t в нижний регистр ASCII.

3. Если предоставлен член «lastModified«, пусть d будет установлен на член словаря lastModified. Если он не указан, установите для d текущие дату и время, представленные как количество миллисекунд, прошедших с начала эпохи Unix (что эквивалентно Date.now() [ECMA-262]).

Примечание. Поскольку объекты Date ECMA-262 преобразуются в «long long» значения, представляющие количество миллисекунд, прошедших с эпохи Unix, последним элементом lastModified может быть объект Date [ECMA-262].

4. Верните новый объект File F, такой что:

1. F относится к байтовой последовательности bytes.

2. F.size устанавливается равным общему количеству байтов в bytes.

3. F.name установлено на n.

4. F.type установлен на t.

5. F.lastModified имеет значение d.

 

4.1.1. Параметры конструктора

Конструктор File() можно вызвать со следующими параметрами:

  • Последовательность fileBits
  • Параметр fileName
  • Необязательный словарь FilePropertyBag

Последовательность fileBits, которая принимает любое количество следующих элементов и в любом порядке:

  • Элементы BufferSource
  • Элементы Blob, в том числе элементы File
  • Элементы USVString

Параметр fileNameПараметр USVString, представляющий имя файла; нормативные условия для этого параметра конструктора можно найти в §4.1 Конструктор.

Необязательный словарь FilePropertyBag. который в дополнение к членам BlobPropertyBag принимает еще одного члена:

  • Необязательный член lastModified, который должен быть «long long»; нормативные условия для этого члена приведены в §4.1 Конструктор.

 

4.2. Атрибуты

«name«, типа DOMString, только чтение

Имя файла. При получении это должно вернуть имя файла в виде строки. Существует множество вариаций имен файлов и соглашений, используемых в различных файловых системах ОС; это просто имя файла без информации о пути. При получении, если пользовательские агенты не могут сделать эту информацию доступной, они должны вернуть пустую строку. Если объект File создается с помощью конструктора, дополнительные нормативные условия для этого атрибута можно найти в §4.1 Конструктор.

«lastModified«, типа long long, только для чтения

Дата последнего изменения файла. При получении, если пользовательские агенты могут сделать эту информацию доступной, она должна вернуть long long, равный времени последнего изменения файла в виде количества миллисекунд с момента Unix Epoch. Если дата и время последнего изменения неизвестны, атрибут должен возвращать текущую дату и время в виде long long, представляющего количество миллисекунд с начала Unix Epoch; это эквивалентно Date.now() [ECMA-262]. Если объект File создается с помощью конструктора, дополнительные нормативные условия для этого атрибута можно найти в §4.1 Конструктор.

Интерфейс File доступен для объектов, которые предоставляют атрибут типа FileList; эти объекты определены в HTML [HTML]. Интерфейс File, который наследуется от Blob, является неизменяемым и, таким образом, представляет данные файла, которые могут быть считаны в память в момент инициации операции чтения. Пользовательские агенты должны обрабатывать чтение файлов, которые больше не существуют на момент чтения, как ошибки, генерируя исключение NotFoundError при использовании FileReaderSync на Web Worker [Workers] или инициируя событие «error» с атрибутом «error«, возвращающим NotFoundError.

Пример № 4

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

var file = document.getElementById("filePicker").files[0];
var date = new Date(file.lastModified);
println("Вы выбрали файл " + file.name + " который был изменен на " + date.toDateString() + ".");

...

// Создать файл с определенной датой последнего изменения

var d = new Date(2013, 12, 5, 16, 23, 45, 600);
var generatedFile = new File(["Rough Draft ...."], "Draft1.txt", {type: "text/plain", lastModified: d})

...

 

5. Интерфейс FileList

Примечание

Интерфейс FileList следует рассматривать как «подверженный риску», поскольку общая тенденция на веб-платформе заключается в замене таких интерфейсов на объект платформы Array в ECMAScript [ECMA-262]. В частности, это означает, что синтаксис сортировки filelist.item(0) находится под угрозой; на большинство других программных применений FileList вряд ли повлияет возможный переход к типу Array.

Этот интерфейс представляет собой список файловых объектов File.

[Exposed=(Window, Worker), Serializable]
interface FileList {
  getter File? item(unsigned long index);
  readonly attribute unsigned long length;
};

Объекты FileList — это сериализуемые объекты. Их шаги сериализации с заданным value и serialized:

1. Установите serialized.[[Files]] в пустой список.
2. Для каждого файла file в значении value добавьте суб-сериализацию файла file к serialized.[[Files]].

Их этап десериализации с учетом value и serialized:

1. Для каждого файла file из serialized.[[Files]] добавьте суб-десериализацию файла file к значению value.

 

Пример № 5

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

// uploadData - это элемент формы
// fileChooser - это элемент ввода типа 'file'
var file = document.forms['uploadData']['fileChooser'].files[0];

// альтернативный синтаксис может быть
// var file = document.forms['uploadData']['fileChooser'].files.item(0);

if(file)
{
  // Выполнить файловые операции
}

 

5.1. Атрибуты

«length» типа unsigned long (беззнаковый длинный), только для чтения

должен возвращать количество файлов в объекте FileList. Если файлов нет, этот атрибут должен возвращать 0.

 

5.2. Методы и параметры

«item(index

должен возвращать индексный (index) объект File в FileList. Если в списке файлов нет index-ного объекта File, этот метод должен возвращать значение null.

index должен обрабатываться пользовательскими агентами как значение для позиции объекта File в FileList, где «0» представляет первый файл. Поддерживаемые индексы свойств — это числа в диапазоне от нуля до единицы, меньшие, чем количество объектов File, представленных объектом FileList. Если таких объектов File нет, значит, нет поддерживаемых индексов свойств.

Примечание

Интерфейс HTMLInputElement имеет атрибут только для чтения типа FileList, к которому осуществляется доступ в приведенном выше примере. Другие интерфейсы с атрибутом только для чтения типа FileList включают интерфейс DataTransfer.

 

6. Чтение данных

6.1. Источник задачи чтения файла

Эта спецификация определяет новый общий источник задачи, называемый источником задачи чтения файла (file reading task source), который используется для всех задач, поставленных в очередь в этой спецификации, для чтения последовательностей байтов, связанных с объектами Blob и File. Он должен использоваться для функций, которые запускаются в ответ на асинхронное чтение двоичных данных.

 

6.2. FileReader API

[Exposed=( Window, Worker )]
interface FileReader: EventTarget {
 constructor();

 // методы асинхронного чтения
 undefined readAsArrayBuffer(Blob blob);
 undefined readAsBinaryString(Blob blob);
 undefined readAsText(Blob blob, optional DOMString encoding);
 undefined readAsDataURL(Blob blob);

 undefined abort();

 // состояния
 const unsigned short EMPTY = 0;
 const unsigned short LOADING = 1;
 const unsigned short DONE = 2;
 readonly attribute unsigned short readyState;

 //  данные File или Blob
 readonly attribute (DOMString или ArrayBuffer)? result;
 readonly attribute DOMException? error;

 // атрибуты содержимого обработчика событий
 attribute EventHandler onloadstart;
 attribute EventHandler onprogress;
 attribute EventHandler onload;
 attribute EventHandler onabort;
 attribute EventHandler onerror;
 attribute EventHandler onloadend;
};

FileReader имеет связанное состояние (state): «empty«, «loading» или «done«. Изначально он «empty«.

FileReader имеет связанный результат (result) (null, DOMString или ArrayBuffer). Изначально он null.

FileReader имеет связанную ошибку (error) (null или DOMException). Изначально он null.

Конструктор FileReader() при вызове должен возвращать новый объект FileReader.

Получатель атрибута readyState при вызове переключает состояние объекта контекста (этого this) и выполняет связанный шаг:

«empty»
Вернуть EMPTY

«loading»
Вернуть LOADING

«done»
Вернуть DONE

Получатель атрибута result при вызове должен возвращать результат объекта контекста (этого this).

Получатель атрибута error при вызове должен возвращать ошибку объекта контекста (этого this).

FileReaderfr имеет связанный алгоритм операции чтения, который при заданном blob, type и необязательном encodingName выполняет следующие шаги:

1. Если состояние fr — «loading«, выбросить исключение InvalidStateError DOMException.

2. Установите для fr состояние «loading«.

3. Установите для результата fr значение null.

4. Установите для ошибки fr значение null.

5. Пусть stream будет результатом вызова get stream для blob.

6. Пусть reader будет результатом получения читателя из потока stream.

7. Пусть байты bytes будут пустой последовательностью байтов.

8. Пусть chunkPromise будет результатом чтения фрагмента из потока stream с помощью средства чтения reader.

9. Пусть isFirstChunk будет истинным — true.

10. Параллельно, пока правда — true:

1. Подождите, пока chunkPromise будет выполнен или отклонен.

2. Если chunkPromise выполняется, а isFirstChunk имеет значение true, поставить задачу в очередь для запуска события выполнения, называемого «loadstart«, на fr.

Мы могли бы изменить loadstart, чтобы он отправлялся синхронно, чтобы соответствовать поведению XMLHttpRequest. <https://github.com/w3c/FileAPI/issues/119>

3. Установите для isFirstChunk значение false.

4. Если chunkPromise выполняется с помощью объекта, свойство «done» которого имеет значение false, а свойство value — объект Uint8Array, выполните следующие действия:

1. Пусть bs будет байтовой последовательностью (byte sequence), представленной объектом Uint8Array.

2. Добавить bs к байтам bytes.

3. Если с момента последнего вызова этих шагов прошло примерно 50ms, поставьте задачу в очередь для запуска события прогресса, которое называется «progress» в fr.

4. Установите chunkPromise равным результату чтения фрагмента из потока stream с помощью средства чтения reader.

5. В противном случае, если chunkPromise выполняется с объектом, свойство «done» которого истинно, поставьте задачу в очередь для выполнения следующих шагов и прервите этот алгоритм:

1. Установите для fr состояние «done» (готово).

2. Пусть result будет результатом данных пакета с заданными байтами bytes, типом type, «type» blob и encodingName.

3. Если данные пакета вызвали ошибку исключения error:

1. Установите для ошибки fr значение error.

2. Запустить событие прогресса под названием «error» на fr.

4. Иначе:

1. Установите результат fr равным result.

2. Запустить событие выполнения под названием «load» на fr.

5. Если состояние fr не «loading«, вызовите событие прогресса, называемое «loadend«, на fr.

Примечание: обработчик событий для событий «load» или «error» (загрузки или ошибок) мог запустить другую загрузку, если это произойдет, событие «loadend» для этой загрузки не запускается.

6. В противном случае, если chunkPromise отклоняется с ошибкой error, поставьте задачу в очередь для выполнения следующих шагов и прервите этот алгоритм:

1. Установите для состояния fr — «done«.

2. Установите для ошибки fr значение error.

3. Запустить событие прогресса под названием «error» на fr.

4. Если состояние fr не «loading«, вызовите событие прогресса с именем «loadend» на fr.

Примечание. Обработчик события «error» мог запустить другую загрузку, в этом случае событие «loadend» для этой загрузки не запускается.

Используйте источник задачи чтения файла для всех этих задач.

 

6.2.1. Атрибуты содержимого обработчика событий

Ниже приведены атрибуты содержимого обработчика событий (и соответствующие им типы событий обработчика событий), которые пользовательские агенты должны поддерживать в FileReader как атрибуты DOM:

Атрибут содержимого обработчика событий Тип события обработчика события
onloadstart loadstart
onprogress progress
onabort abort
onerror error
onload load
onloadend loadend

 

6.2.2. Состояния чтения файлов

Объект FileReader может находиться в одном из трех состояний. Атрибут readyState сообщает вам, в каком состоянии находится объект:

EMPTY (numeric value 0)

Объект FileReader создан, и ожидающих чтения нет. Ни один из методов чтения не был вызван. Это состояние по умолчанию для вновь созданного объекта FileReader до тех пор, пока для него не будет вызван один из методов чтения.

LOADING (numeric value 1)

Читается File или Blob. Один из методов чтения обрабатывается, и во время чтения ошибок не произошло.

DONE (numeric value 2)

Весь File или Blob был прочитан в память, ИЛИ произошла ошибка чтения файла, ИЛИ чтение было прервано с помощью abort(). FileReader больше не читает File или Blob. Если для параметра readyState установлено значение DONE, это означает, что в этом FileReader был вызван по крайней мере один из методов чтения.

 

6.2.3. Чтение файла File или большого двоичного объекта Blob

Интерфейс FileReader предоставляет несколько методов асинхронного чтения (asynchronous read methods) — readAsArrayBuffer(), readAsBinaryString(), readAsText() и readAsDataURL(), которые считывают файлы в память.

Примечание. Если для одного и того же объекта FileReader вызывается несколько одновременных методов чтения, пользовательские агенты генерируют ошибку InvalidStateError для любого из методов чтения, возникающих, когда «readyState = LOADING».

(FileReaderSync предоставляет несколько методов синхронного чтения. В совокупности методы синхронного и асинхронного чтения FileReader и FileReaderSync называются просто методами чтения (read methods).)

 

6.2.3.1. Метод readAsDataURL()

Метод readAsDataURL( blob ) при вызове должен инициировать операцию чтения для большого двоичного объекта blob с DataURL.

 

6.2.3.2. Метод readAsText()

Метод readAsText( blob, encoding ) при вызове должен инициировать операцию чтения для большого двоичного объекта blob с текстом Text и кодировкой encoding.

 

6.2.3.3. Метод readAsArrayBuffer()

Метод readAsArrayBuffer( blob ) при вызове должен инициировать операцию чтения для большого двоичного объекта blob с помощью ArrayBuffer.

 

6.2.3.4. Метод readAsBinaryString()

Метод readAsBinaryString( blob ) при вызове должен инициировать операцию чтения для большого двоичного объекта blob с помощью BinaryString.

Примечание. Использование readAsArrayBuffer() предпочтительнее readAsBinaryString(), которое предусмотрено для обратной совместимости.

 

6.2.3.5. Метод abort()

Когда вызывается метод abort(), пользовательский агент должен выполнить следующие шаги:

1. Если состояние объекта контекста — «empty» или если состояние объекта контекста «done«, установите результат объекта контекста равным null и завершите этот алгоритм.

2. Если состояние объекта контекста — «loading«, установите состояние объекта контекста на «done» и установите для результата объекта контекста значение null.

3. Если есть какие-либо задачи из объекта контекста в источнике задач чтения файла в связанной очереди задач, удалите эти задачи из этой очереди задач.

4. Завершить алгоритм обрабатываемого метода чтения.

5. Запустить событие выполнения, называемое прерыванием «abort«, в объекте контекста.

6. Если состояние объекта контекста не «loading«, запускайте событие выполнения, называемое «loadend«, в объекте контекста.

 

6.3. Данные упаковки

Blob имеет связанный алгоритм упаковки данных (package data), заданные байты bytes, тип type, необязательный mimeType и необязательный encodingName, который включает тип type и выполняет связанные шаги:

DataURL

Возвращать байты bytes как DataURL [RFC2397 #] с учетом следующих соображений:

Используйте mimeType как часть URL-адреса данных, если он доступен в соответствии со спецификацией URL-адреса данных [RFC2397].

Если mimeType недоступен, верните URL-адрес данных без медиа-типа. [RFC2397].

(Лучше указать, как генерируется DataURL. <https://github.com/w3c/FileAPI/issues/104>)

Text

1. Пусть кодирование encoding будет неудачным.

2. Если encodingName присутствует, установите кодировку encoding на результат получения кодировки из encodingName.

3. Если кодировка encoding не удалась и присутствует mimeType:

1. Пусть type будет результатом синтаксического анализа MIME-типа, заданного mimeType.

2. Если type не является ошибкой, установите кодировку на результат получения кодировки из параметров type — [«charset»].

Пример № 6

Если у blob есть атрибут «type» — text/plain;charset=utf-8, то получение кодировки выполняется с использованием «utf-8» в качестве метки. Обратите внимание, что пользовательские агенты должны анализировать и извлекать часть параметра Charset, которая составляет метку label кодировки.

4. Если кодировка encoding не удалась, установите кодировку encoding UTF-8.

5. Расшифруйте байты bytes с использованием резервной кодировки encoding и верните результат.

ArrayBuffer

Верните новый ArrayBuffer, содержимое которого — байты bytes.

BinaryString

Возвращает байты bytes как двоичную строку, в которой каждый байт представлен единицей кода равного значения [0..255].

 

6.4. События

Объект FileReader должен быть целью для всех событий в этой спецификации.

Когда в этой спецификации говорится, что нужно запускать событие выполнения с именем « (для некоторого ProgressEvent « у данного средства чтения FileReader в качестве объекта контекста), следующее является нормативным:

  • Событие прогресса «e» не всплывает. «e.bubbles» должно иметь значение false [DOM]
  • Событие прогресса «e» НЕ отменяется. «e.cancelable» должен иметь значение false [DOM]

 

6.4.1. Резюме события

Следующие события запускаются в объектах FileReader.

Название события Интерфейс Сработало, когда…
loadstart ProgressEvent Когда начнется чтение.
progress ProgressEvent При чтении (и декодировании) blob
abort ProgressEvent Когда чтение было прервано. Например, вызвав метод abort().
error ProgressEvent Когда чтение не удалось (см. Ошибки чтения файла).
load ProgressEvent Когда чтение успешно завершено.
loadend ProgressEvent Когда запрос выполнен (успешно или неудачно).

 

6.4.2. Сводка инвариантов событий

Этот раздел носит информативный характер.

Ниже приведены инварианты, применимые к запуску события для данного метода асинхронного чтения в этой спецификации:

1. После запуска «loadstart» соответствующая нагрузка срабатывает по «loadend«, ЕСЛИ не выполняется одно из следующих условий:

— метод чтения был отменен с помощью abort(), и был вызван новый метод чтения

— функция обработчика событий для события загрузки «load» инициирует новое чтение

— функция обработчика события ошибки «error» инициирует новое чтение.

Примечание. События loadstart и loadend не связаны однозначно.

Пример № 7

В этом примере демонстрируется «цепочка чтения»: инициирование другого чтения из обработчика событий, в то время как «первое» чтение продолжает обработку.

// В коде вроде ...
reader.readAsText(file);
reader.onload = function(){reader.readAsText(alternateFile);}

.....

//... событие loadend не должно запускаться при первом чтении

reader.readAsText(file);
reader.abort();
reader.onabort = function(){reader.readAsText(updatedFile);}

//... событие loadend не должно запускаться при первом чтении

2. Одно событие «progress» будет срабатывать, когда большой двоичный объект blob будет полностью считан в память.

3. Перед загрузкой не запускается событие прогресса «progress«.

4. После срабатывания прерывания (abort), загрузки (load) или ошибки(error) событие «progress» не запускается. Для данного чтения не более одного срабатывания прерывания, загрузки и ошибки. (Самое большее один из прерываний, загрузок и ошибок срабатывает для данного чтения.)

5. После загрузки не возникает никаких событий «abort«, «load» или «error» (прерывания, загрузки или ошибки).

 

6.5. Чтение по темам

Веб-воркеры позволяют использовать синхронные API чтения File или Blob (файлов или больших двоичных объектов), поскольку такие чтения в потоках не блокируют основной поток. В этом разделе определяется синхронный API, который можно использовать в Workers [[Web Workers]]. Рабочие могут использовать как асинхронный API (объект FileReader), так и синхронный API (объект FileReaderSync).

 

6.5.1. API FileReaderSync

Этот интерфейс предоставляет методы для синхронного чтения объектов File или Blob в память.

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
constructor();
// Синхронно возвращать строки

ArrayBuffer readAsArrayBuffer(Blob blob);
DOMString readAsBinaryString(Blob blob);
DOMString readAsText(Blob blob, optional DOMString encoding);
DOMString readAsDataURL(Blob blob);
};

 

6.5.1.1. Конструкторы

Когда вызывается конструктор FileReaderSync(), пользовательский агент должен вернуть новый объект FileReaderSync.

 

6.5.1.2. Метод readAsText()

При вызове метода readAsText( blob, encoding ) необходимо выполнить следующие действия:

1. Пусть stream будет результатом вызова получения потока для blob.

2.  Пусть reader будет результатом получения читателя из потока stream.

3.  Пусть обещание promise будет результатом чтения всех байтов из потока stream с помощью reader.

4. Подождите, пока обещание promise будет выполнено или отклонено.

5. Если обещание promise выполнено с байтовой последовательностью bytes:

1. Возвращает результат данных пакета с указанием байтов bytes, текста Text, типа «type»  blob и encoding.

6. Укажите причину отклонения обещания promise.

 

6.5.1.3. Метод readAsDataURL()

При вызове метода readAsDataURL( blob ) необходимо выполнить следующие действия:

1. Пусть stream будет результатом вызова получения потока для blob.

2. Пусть reader будет результатом получения читателя из потока stream.

3. Пусть обещание promise будет результатом чтения всех байтов из потока stream с помощью reader.

4. Подождите, пока обещание promise будет выполнено или отклонено.

5. Если обещание promise выполнено с байтовой последовательностью bytes:

1. Возвращает результат данных пакета с указанием байтов bytes, DataURL и типа «type» blob.

6. Укажите причину отклонения обещания promise.

 

6.5.1.4. Метод readAsArrayBuffer()

Метод readAsArrayBuffer( blob ) при вызове должен выполнить следующие шаги:

1. Пусть stream будет результатом вызова получения потока для blob.

2. Пусть reader будет результатом получения читателя из потока stream.

3. Пусть обещание promise будет результатом чтения всех байтов из потока stream с помощью reader.

4. Подождите, пока обещание promise будет выполнено или отклонено.

5. Если обещание promise выполнено с байтовой последовательностью bytes:

1. Возвращает результат данных пакета с указанием байтов bytes, ArrayBuffer и типа «type» blob.

6. Укажите причину отклонения обещания promise.

 

6.5.1.5. Метод readAsBinaryString()

Метод readAsBinaryString( blob ) при вызове должен выполнить следующие шаги:

1. Пусть stream будет результатом вызова получения потока для blob.

2. Пусть reader будет результатом получения читателя из потока stream.

3. Пусть обещание promise будет результатом чтения всех байтов из потока stream с помощью reader.

4. Подождите, пока обещание promise будет выполнено или отклонено.

5. Если обещание promise выполнено с байтовой последовательностью bytes:

1. Вернуть результат данных пакета с указанием байтов bytes, BinaryString и типа «type» blob.

6. Укажите причину отклонения обещания promise.

Примечание. Использование readAsArrayBuffer() предпочтительнее readAsBinaryString(), которое предусмотрено для обратной совместимости.

 

7. Ошибки и исключения

Ошибки чтения файлов (File read errors) могут возникать при чтении файлов из базовой файловой системы. Приведенный ниже список возможных состояний ошибки является информативным.

  • Доступ к File или Blob может не существовать в момент вызова одного из методов асинхронного чтения или синхронного чтения. Это может быть связано с тем, что он был перемещен или удален после того, как ссылка на него была получена (например, одновременная модификация с другим приложением). См. «NotFoundError«.
  • File или Blob может быть нечитаемым. Это может быть связано с проблемами разрешения, которые возникают после получения ссылки на File или Blob (например, одновременная блокировка с другим приложением). Кроме того, состояние моментального снимка могло измениться. См. «NotReadableError«.
  • Пользовательские агенты МОГУТ определить, что некоторые файлы небезопасны для использования в веб-приложениях. Файл может измениться на диске с момента выбора исходного файла, что приведет к недопустимому чтению. Кроме того, некоторые структуры файлов и каталогов могут считаться ограниченными базовой файловой системой; попытки чтения из них могут рассматриваться как нарушение безопасности. См. §9 «Вопросы безопасности и конфиденциальности» и «SecurityError«.

 

7.1. Создание исключения или возврат ошибки

Этот раздел является нормативным.

При чтении File или Blob могут возникнуть условия ошибки.

Операция чтения может завершиться из-за состояния ошибки при чтении File или Blob; конкретное состояние ошибки, которое вызывает сбой алгоритма получения потока, называется причиной сбоя (failure reason). Причина сбоя — одна из NotFound, UnsafeFile, TooManyReads, SnapshotState или FileLock.

Методы синхронного чтения генерируют исключения типа, указанного в таблице ниже, если произошла ошибка из-за конкретной причины сбоя.

Асинхронные методы чтения используют атрибут «error» объекта FileReader, который должен возвращать объект DOMException наиболее подходящего типа из приведенной ниже таблицы, если произошла ошибка из-за конкретной причины сбоя, или в противном случае возвращать значение null.

Тип Описание и причина неисправности
NotFoundError Если ресурс File или Blob не может быть найден во время обработки чтения, это является причиной сбоя NotFound.
Для методов асинхронного чтения атрибут «error» должен возвращать исключение NotFoundError, а методы синхронного чтения должны вызывать исключение NotFoundError.
SecurityError Если:

  • определено, что определенные файлы небезопасны для доступа в веб-приложении, это причина отказа UnsafeFile.
  • определено, что для ресурсов File или Blob выполняется слишком много вызовов чтения, это причина сбоя TooManyReads.
Для методов асинхронного чтения атрибут ошибки «error» может возвращать исключение SecurityError, а методы синхронного чтения могут вызывать исключение SecurityError.
Это ошибка безопасности, которую следует использовать в ситуациях, на которые не распространяются другие причины сбоя.
NotReadableError Если:

  • состояние моментального снимка File или Blob не соответствует состоянию базового хранилища, это причина сбоя SnapshotState.
  • File или Blob не могут быть прочитаны, как правило, из-за проблем с разрешениями, которые возникают после того, как состояние моментального снимка было установлено (например, одновременная блокировка базового хранилища с другим приложением), тогда это причина сбоя FileLock.
Для методов асинхронного чтения атрибут «error» должен возвращать исключение NotReadableError, а методы синхронного чтения должны вызывать исключение NotReadableError.

 

8. URL-адрес для ссылки на Blob и MediaSource

В этом разделе определяется схема URL-адреса, используемого для ссылки на объекты Blob и MediaSource.

 

8.1. Введение

Этот раздел носит информативный характер.

URL-адреса BLOB-объектов (или объектов) — это URL-адреса типа «blob:http://example.com/550e8400-e29b-41d4-a716-446655440000″. Это позволяет интегрировать Blob-объекты и MediaSources с другими API, которые предназначены только для использования с URL-адресами, например с элементом <img>. URL-адреса BLOB-объектов также могут использоваться для перехода к локально созданным данным и для их запуска.

Для этого в интерфейсе URL представлены два статических метода:

  • createObjectURL(obj)
  • revokeObjectURL(url)

Первый метод создает сопоставление URL-адреса с Blob-объектом, а второй метод отменяет указанное сопоставление. Пока существует сопоставление, Blob не может быть обработан сборщиком мусора, поэтому необходимо позаботиться о том, чтобы отозвать URL, как только ссылка больше не понадобится. Все URL-адреса аннулируются, когда глобал, создавший сам URL-адрес, уходит.

 

8.2. Модель

Каждый пользовательский агент должен поддерживать хранилище URL-адресов больших двоичных объектов (blob URL store). Хранилище URL-адресов больших двоичных объектов — это карта, где ключи являются допустимыми строками URL, а значения — записями URL-адресов больших двоичных объектов.

Запись URL-адреса большого двоичного объекта (blob URL entry) состоит из объекта — object (типа Blob или MediaSource) и среды — environment (объекта параметров среды).

Ключи в хранилище URL-адресов Blob (также известные как URL-адреса Blob — blob URLs) представляют собой допустимые строки URL-адресов, которые при синтаксическом анализе приводят к получению URL-адреса со схемой, равной «blob», с пустым хостом и путем, состоящим из одного элемента, а также действительной строки URL.

Чтобы сгенерировать новый URL-адрес Blob (generate a new blob URL), выполните следующие действия:

1. Пусть результатом result будет пустая строка.

2. Добавьте к результату result строку «blob:».

3. Пусть settings будет текущим объектом настроек

4. Пусть origin будет источником настроек settings.

5. Пусть serialized будет сериализацией источника ASCII.

6. Если serialized — «null», установите для него значение, определяемое реализацией.

7. Добавьте serialized к результату result.

8. Добавьте U+0024 SOLIDUS (/) к результату result.

9. Создайте UUID [RFC4122] в виде строки и добавьте ее к результату result.

10. Верните result

Пример № 8

Примером URL-адреса blob’а, который может быть создан с помощью этого алгоритма, является «blob:https://example.org/40a5fb5a-d56d-4a33-b4e2-0acf6a8e5f641«.

 

Чтобы добавить запись в хранилище URL-адресов большого двоичного объекта (add an entry to the blob URL store) для данного объекта object, выполните следующие действия:

1. Пусть store будет хранилищем URL-адресов BLOB-объектов пользовательского агента.

2. Пусть url будет результатом создания нового URL-адреса большого двоичного объекта.

3. Пусть entry будет новой записью URL-адреса большого двоичного объекта, состоящей из объекта и текущего объекта настроек.

4. Установите store[url] на запись entry.

5. Верните url

 

Чтобы удалить запись из хранилища URL-адресов больших двоичных объектов (remove an entry from the blob URL store) для данного URL-адреса, выполните следующие действия:

1. Пусть store будет хранилищем URL-адресов больших двоичных объектов пользовательского агента;

2. Пусть строка url будет результатом сериализации url.

3. Удалить store[url string].

 

8.3. Модель разыменования для URL-адресов больших двоичных объектов

Чтобы разрешить URL-адрес большого двоичного объекта с учетом url (URL-адреса), выполните следующие действия:

1. Утверждаю: схема url — «blob«.

2. Пусть store будет хранилищем URL-адресов BLOB-объектов пользовательского агента.

3. Пусть url string будет результатом сериализации url с установленным флагом исключения фрагмента (exclude fragment flag).

4. Если store[url string] существует, вернуть store[url string]; в противном случае вернуть отказ.

Дополнительные требования к модели синтаксического анализа и сопоставления для URL-адресов больших двоичных объектов определены в спецификациях [URL] и [Fetch].

 

8.3.1. Происхождение URL-адресов больших двоичных объектов

Этот раздел носит информативный характер.

Источник URL-адреса большого двоичного объекта всегда совпадает с источником URL-адреса среды, в которой был создан этот URL-адрес, если URL-адрес еще не отозван. Это достигается за счет того, что спецификация [URL] ищет URL-адрес в хранилище URL-адресов больших двоичных объектов при синтаксическом анализе URL-адреса и использует эту запись для возврата правильного источника.

Если URL-адрес был отозван, сериализация источника по-прежнему останется такой же, как сериализация источника среды, создавшей URL-адрес большого двоичного объекта, но для непрозрачных источников само происхождение может быть другим. Однако эта разница не заметна, поскольку URL-адрес отозванного большого двоичного объекта в любом случае не может быть разрешен / получен.

 

8.3.2. Время жизни URL-адресов больших двоичных объектов

Эта спецификация расширяет этапы очистки документа при выгрузке следующими этапами:

1. Пусть environment будет соответствующим объектом настроек документа.

2. Пусть store будет хранилищем URL-адресов больших двоичных объектов пользовательского агента;

3. Удалите из хранилища store все записи, для которых окружение значения равно environment.

Для этого нужен аналогичный крючок, когда рабочий выгружен.

 

8.4. Создание и отзыв URL-адреса большого двоичного объекта

URL-адреса BLOB-объектов создаются и отзываются с помощью статических методов, представленных в объекте URL. Отзыв URL-адреса большого двоичного объекта отделяет URL-адрес большого двоичного объекта от ресурса, на который он ссылается, и, если он разыменован после отзыва, пользовательские агенты должны действовать так, как если бы произошла сетевая ошибка. В этом разделе описывается дополнительный интерфейс к спецификации URL [URL] и представлены методы создания и отзыва URL-адреса большого двоичного объекта.

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
static DOMString createObjectURL((Blob or MediaSource) obj);
static undefined revokeObjectURL(DOMString url);
};

Статический метод createObjectURL( obj ) должен возвращать результат добавления записи в хранилище URL-адресов больших двоичных объектов для obj.

Статический метод revokeObjectURL( url ) должен выполнять следующие действия:

1. Пусть url record будет результатом парсинга url.

2. Если схема url record не является «blob», вернитесь.

3. Пусть origin будет источником url record.

4. Пусть settings будет текущим объектом настроек.

5. Если origin не совпадает с исходной точкой настроек settings, вернитесь.

6. Удалите запись из хранилища URL-адресов BLOB-объектов для url.

Примечание. Это означает, что попытка отозвать незарегистрированный URL-адрес не приведет к возникновению какой-либо ошибки. В этом случае пользовательские агенты могут отобразить сообщение на консоли ошибок.

Примечание. Попытки разыменовать URL-адрес после того, как он был отозван, приведет к сетевой ошибке. Запросы, которые были запущены до того, как URL-адрес был отозван, все равно будут успешными.

Пример № 9

В приведенном ниже примере «window1» и «window2» разделены, но находятся в одном источнике; «window2» может быть iframe внутри «window1«.

myurl = window1.URL.createObjectURL(myblob);
window2.URL.revokeObjectURL(myurl);

Поскольку пользовательский агент имеет одно глобальное хранилище URL-адресов больших двоичных объектов, можно отозвать URL-адрес объекта из окна, отличного от того, в котором он был создан. Вызов URL.revokeObjectURL() гарантирует, что последующее разыменование myurl приведет к тому, что пользовательский агент будет действовать так, как если бы произошла сетевая ошибка.

 

8.4.1. Примеры создания и отзыва URL-адреса большого двоичного объекта

URL-адреса BLOB-объектов — это строки, которые используются для извлечения объектов Blob-объектов и могут сохраняться до тех пор, пока документ, из которого они были созданы, с помощью URL.createObjectURL() — см. §8.3.2 Время жизни URL-адресов BLOB-объектов.

В этом разделе приведены примеры использования создания и отзыва URL-адресов больших двоичных объектов с пояснениями.

Пример № 10

В приведенном ниже примере два элемента <img> [HTML] относятся к одному и тому же URL-адресу большого двоичного объекта:

url = URL.createObjectURL(blob);
img1.src = url;
img2.src = url;

Пример № 11

В приведенном ниже примере явно вызывается URL.revokeObjectURL().

var blobURLref = URL.createObjectURL(file);
img1 = new Image();
img2 = new Image();

// Оба задания ниже работают должным образом
img1.src = blobURLref;
img2.src = blobURLref;

// ... После нагрузки на тело
// Проверьте, загружены ли оба изображения
if(img1.complete && img2.complete) {
  // Убедитесь, что последующие ссылки вызывают исключение
  URL.revokeObjectURL(blobURLref);
} else {
  msg("Изображения не могут быть просмотрены!");
  // отозвать строковую ссылку
  URL.revokeObjectURL(blobURLref);
}

В приведенном выше примере допускается несколько ссылок на один URL-адрес большого двоичного объекта, а затем веб-разработчик отменяет строку URL-адреса большого двоичного объекта после загрузки обоих объектов изображения. Отсутствие ограничения количества использований URL-адреса большого двоичного объекта обеспечивает большую гибкость, но увеличивает вероятность утечек; разработчики должны связать его с соответствующим вызовом URL.revokeObjectURL().

 

9. Вопросы безопасности и конфиденциальности

Этот раздел носит информативный характер.

Эта спецификация позволяет веб-контенту читать файлы из базовой файловой системы, а также предоставляет средства для доступа к файлам с помощью уникальных идентификаторов, и, как таковые, подлежит некоторым соображениям безопасности. Эта спецификация также предполагает, что основное взаимодействие пользователя происходит с элементом <input type = «file» /> HTML-форм [HTML], и что все файлы, которые читаются объектами FileReader, сначала были выбраны пользователем. Важные соображения безопасности включают предотвращение атак выбора вредоносных файлов (зацикливание выбора), предотвращение доступа к файлам, чувствительным к системе, и защиту от изменений файлов на диске после того, как выбор был произведен.

Предотвращение зацикливания выбора (Preventing selection looping)

Во время выбора файла на пользователя может попасть средство выбора файлов, связанное с <input type = «file» /> (в цикле «должен выбрать», который принудительно выбирает перед закрытием средства выбора файлов), и пользовательский агент может предотвратить доступ к файлу. к любому выбору, сделав возвращаемый объект FileList размером 0.

Файлы, чувствительные к системе (System-sensitive files)

(например, файлы в /usr/bin, файлы паролей и другие исполняемые файлы собственной операционной системы) обычно не должны быть доступны веб-контенту, и к ним нельзя обращаться через URL-адреса больших двоичных объектов. Пользовательские агенты могут генерировать исключение SecurityError для методов синхронного чтения или возвращать исключение SecurityError для асинхронных чтений.

Этот раздел является предварительным; дополнительные данные безопасности могут дополнить это в последующих проектах.

 

10. Требования и варианты использования

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

 

После того как пользователь предоставил разрешение, пользовательские агенты должны предоставить возможность программно читать и анализировать данные непосредственно из локального файла.

Пример № 12

Средство просмотра текстов песен. Пользователь хочет читать тексты песен из песен в своем файле plist. Пользователь просматривает файл plist. Файл открывается, читается, анализируется и представляется пользователю в виде сортируемого списка действий в веб-приложении. Пользователь может выбрать песни, чтобы получить тексты песен. Пользователь использует диалог «Обзор файла».

 

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

Пример № 13

Приложение «Календарь». У компании пользователя есть календарь. Пользователь хочет синхронизировать местные события с календарем компании, отмеченные как «занятые» слоты (без утечки личной информации). Пользователь просматривает файл и выбирает его. «text/calendar» файл анализируется в браузере, что позволяет пользователю объединить файлы в одно представление календаря. Затем пользователь хочет сохранить файл обратно в свой локальный файл календаря (используя «Сохранить как»?). Пользователь также может асинхронно отправить интегрированный файл календаря обратно в хранилище календаря сервера.

 

Пользовательские агенты должны предоставлять возможность программно сохранять локальный файл с учетом количества данных и имени файла.

Примечание. Хотя эта спецификация не предоставляет явного вызова API для запуска загрузок, спецификация HTML5 решает эту проблему. Атрибут загрузки «download» элемента <a> инициирует загрузку, сохраняя файл с указанным именем. Комбинация этого API и атрибута «download» в элементах <a> позволяет создавать файлы в веб-приложениях и сохранять их локально.

Пример № 14

Приложение для работы с электронными таблицами. Пользователь взаимодействует с формой и генерирует ввод. Затем форма генерирует вывод CSV (переменные, разделенные запятыми), который пользователь может импортировать в электронную таблицу, и использует команду «Сохранить …». Сгенерированный вывод также может быть напрямую интегрирован в электронную таблицу в Интернете и загружен асинхронно.

 

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

Пример № 15

Приложение для загрузки видео/фото. Пользователь может выбирать большие файлы для загрузки, которые затем могут быть «переданы по частям» (chunk-transfered) на сервер.

 

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

 

Благодарности

Эта спецификация была первоначально разработана рабочей группой SVG. Большое спасибо Марку Бейкеру и Анне ван Кестерен за их отзывы.

Спасибо Робину Берджону, Йонасу Сикингу и Всеволоду Шмироффу за редактирование оригинальной спецификации.

Особая благодарность Олли Петтаю, Никунджу Мехте, Гаррету Смиту, Аарону Будману, Майклу Нордману, Цзян Ли, Дмитрию Титову, Яну Хиксону, Дарину Фишеру, Сэму Вейнигу, Адриану Бейтману и Джулиану Решке.

Спасибо WG W3C WebApps и участникам на listserv public-webapps@w3.org

 

Соответствие

Условные обозначения документа

Требования соответствия выражаются с помощью комбинации описательных утверждений и терминологии RFC 2119. Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ОБЯЗАТЕЛЬНО», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ДОПОЛНИТЕЛЬНО» в нормативных частях. этого документа следует интерпретировать, как описано в RFC 2119. Однако для удобства чтения эти слова не отображаются в этой спецификации всеми прописными буквами.

Весь текст данной спецификации является нормативным, за исключением разделов, явно отмеченных как ненормативные, примеров и примечаний. [RFC2119]

Примеры в этой спецификации вводятся словами «например» или выделяются отдельно от нормативного текста с помощью class = «example», например:

Это информативный пример.

Информационные заметки начинаются со слова «Примечание» и выделяются отдельно от нормативного текста с помощью class = «note», например:

Обратите внимание, это информативное примечание.

 

Соответствующие алгоритмы

Требования, сформулированные в императиве как часть алгоритмов (например, «удалить все начальные пробелы» или «вернуть ложь и прервать эти шаги»), должны интерпретироваться со значением ключевого слова («обязан», «должен», » может «и т. д.), использованные при представлении алгоритма.

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

 

Индекс

Термины, определенные в данной спецификации

abort, in §6.4.1
abort(), in §6.2.3.5
add an entry, in §8.2
add an entry to the blob URL store, in §8.2
adding an entry to the blob URL store, in §8.2
add the entry, in §8.2
add the entry to the blob URL store, in §8.2
arrayBuffer(), in §3.3.4
asynchronous read method, in §6.2.3
Blob, in §3
Blob(), in §3
Blob(blobParts), in §3
Blob(blobParts, options), in §3
BlobPart, in §3
BlobPropertyBag, in §3
blob URL, in §8.2
blob URL entry, in §8.2
blob URL store, in §8.2
constructor()
constructor for Blob, in §3
constructor for FileReader, in §6.2
constructor for FileReaderSync, in §6.5.1
constructor(blobParts), in §3
constructor(blobParts, options), in §3
constructor(fileBits, fileName), in §4
constructor(fileBits, fileName, options), in §4
converting line endings to native, in §3.1.1
convert line endings to native, in §3.1.1
createObjectURL(obj), in §8.4
DONE, in §6.2
EMPTY, in §6.2
endings, in §3.1.1
EndingType, in §3
environment, in §8.2
error
attribute for FileReader, in §6.2
dfn for FileReader, in §6.2
event for FileReader, in §6.4.1
failure reason, in §7.1
File, in §4
File(fileBits, fileName), in §4
File(fileBits, fileName, options), in §4
FileList, in §5
FileLock, in §7.1
FilePropertyBag, in §4
FileReader, in §6.2
FileReader(), in §6.2
file read error, in §7
FileReaderSync, in §6.5.1
FileReaderSync(), in §6.5.1
file reading task source, in §6.1
file type guidelines, in §4
fire a progress event, in §6.4
generate a new blob URL, in §8.2
generating a new blob URL, in §8.2
get stream, in §3
item(index), in §5.2
lastModified
attribute for File, in §4.2
dict-member for FilePropertyBag, in §4.1.1
length, in §5.1
lifetime, in §8.3.1
lifetime stipulation, in §8.3.1
load, in §6.4.1
loadend, in §6.4.1
LOADING, in §6.2
loadstart, in §6.4.1
name, in §4.2
«native», in §3
NotFound, in §7.1
object, in §8.2
object URL, in §8.2
onabort, in §6.2.1
onerror, in §6.2.1
onload, in §6.2.1
onloadend, in §6.2.1
onloadstart, in §6.2.1
onprogress, in §6.2.1
package data, in §6.3
process blob parts, in §3.1.1
processing blob parts, in §3.1.1
progress, in §6.4.1
readAsArrayBuffer(blob)
method for FileReader, in §6.2.3.3
method for FileReaderSync, in §6.5.1.4
readAsBinaryString(blob)
method for FileReader, in §6.2.3.4
method for FileReaderSync, in §6.5.1.5
readAsDataURL(blob)
method for FileReader, in §6.2.3.1
method for FileReaderSync, in §6.5.1.3
readAsText(blob)
method for FileReader, in §6.2.3.2
method for FileReaderSync, in §6.5.1.2
readAsText(blob, encoding)
method for FileReader, in §6.2.3.2
method for FileReaderSync, in §6.5.1.2
read method, in §6.2.3
read operation, in §6.2
readyState, in §6.2
remove an entry, in §8.2
remove an entry from the blob URL store, in §8.2
remove the entry, in §8.2
remove the entry from the blob URL store, in §8.2
resolve, in §8.3
result
attribute for FileReader, in §6.2
dfn for FileReader, in §6.2
revokeObjectURL(url), in §8.4
size, in §3.2
slice(), in §3.3.1
slice(start), in §3.3.1
slice(start, end), in §3.3.1
slice(start, end, contentType), in §3.3.1
slice(start, end, contentType), slice(start, end), slice(start), slice(), in §3.3.1
snapshot state, in §3
SnapshotState, in §7.1
state, in §6.2
stream(), in §3.3.2
synchronous read method, in §6.5.1
terminate an algorithm, in §2
terminate this algorithm, in §2
text(), in §3.3.3
TooManyReads, in §7.1
«transparent», in §3
type
attribute for Blob, in §3.2
dict-member for BlobPropertyBag, in §3.1.1
Unix Epoch, in §2
UnsafeFile, in §7.1

 

Термины определены ссылкой

[DOM] defines the following terms:
Document
EventTarget
context object
fire an event
[ECMA-262] defines the following terms:
Array
Date
[ENCODING] defines the following terms:
decode
getting an encoding
utf-8
utf-8 decode
utf-8 encode
[Fetch] defines the following terms:
construct a readablestream object
enqueue
error
fetch
get a reader
network error
read a chunk
read all bytes
text()
[HTML] defines the following terms:
DataTransfer
EventHandler
HTMLInputElement
Serializable
a
ascii serialization of an origin
current settings object
deserialization steps
environment settings object
event handler content attribute
event handler event type
iframe
img
in parallel
input
origin
postMessage(message, options)
queue a task
relevant settings object
same origin
serializable objects
serialization steps
sub-deserialization
sub-serialization
task
task source
unloading document cleanup steps
[INFRA] defines the following terms:
ascii lowercase
assert
byte
byte sequence
code point
collecting a sequence of code points
exist
for each
key
list
map
position variable
remove
set
string
value
[media-source] defines the following terms:
MediaSource
[MIMESNIFF] defines the following terms:
parameters
parsable mime type
parse a mime type
[STREAMS] defines the following terms:
chunk
[SVG2] defines the following terms:
download
[URL] defines the following terms:
URL
empty host
origin
path
scheme
url
url parser
url serializer
valid url string
[WebIDL] defines the following terms:
ArrayBuffer
BufferSource
Clamp
DOMException
DOMString
Exposed
InvalidStateError
NewObject
NotFoundError
NotReadableError
SecurityError
USVString
get a copy of the buffer source
long long
supported property indices
throw
undefined
unsigned long
unsigned long long
unsigned short
[XHR] defines the following terms:
ProgressEvent
XMLHttpRequest
send()

 

Ссылки

Нормативные ссылки

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/

[ECMA-262]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/

[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/

[Fetch]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/

[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/

[MEDIA-SOURCE]
Matthew Wolenetz; et al. Media Source Extensions™. 17 November 2016. REC. URL: https://www.w3.org/TR/media-source/

[MIMESNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

[RFC2397]
L. Masinter. The «data» URL scheme. August 1998. Proposed Standard. URL: https://tools.ietf.org/html/rfc2397

[RFC4122]
P. Leach; M. Mealling; R. Salz. A Universally Unique IDentifier (UUID) URN Namespace. July 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4122

[STREAMS]
Adam Rice; Domenic Denicola; 吉野剛史 (Takeshi Yoshino). Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/

[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/

[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

[XHR]
Anne van Kesteren. XMLHttpRequest Standard. Living Standard. URL: https://xhr.spec.whatwg.org/

 

Информативные ссылки

[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL: https://www.w3.org/TR/SVG2/

[Workers]
Ian Hickson. Web Workers. 24 September 2015. WD. URL: https://www.w3.org/TR/workers/

 

Индекс IDL

[Exposed=(Window,Worker), Serializable]
interface Blob {
constructor(optional sequence<BlobPart> blobParts,
optional BlobPropertyBag options = {});

readonly attribute unsigned long long size;
readonly attribute DOMString type;

// slice Blob into byte-ranged chunks
Blob slice(optional [Clamp] long long start,
optional [Clamp] long long end,
optional DOMString contentType);

// read from the Blob.
[NewObject] ReadableStream stream();
[NewObject] Promise<USVString> text();
[NewObject] Promise<ArrayBuffer> arrayBuffer();
};

enum EndingType { «transparent», «native» };

dictionary BlobPropertyBag {
DOMString type = «»;
EndingType endings = «transparent»;
};

typedef (BufferSource or Blob or USVString) BlobPart;

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
constructor(sequence<BlobPart> fileBits,
USVString fileName,
optional FilePropertyBag options = {});
readonly attribute DOMString name;
readonly attribute long long lastModified;
};

dictionary FilePropertyBag : BlobPropertyBag {
long long lastModified;
};

[Exposed=(Window,Worker), Serializable]
interface FileList {
getter File? item(unsigned long index);
readonly attribute unsigned long length;
};

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
constructor();
// async read methods
undefined readAsArrayBuffer(Blob blob);
undefined readAsBinaryString(Blob blob);
undefined readAsText(Blob blob, optional DOMString encoding);
undefined readAsDataURL(Blob blob);

undefined abort();

// states
const unsigned short EMPTY = 0;
const unsigned short LOADING = 1;
const unsigned short DONE = 2;

readonly attribute unsigned short readyState;

// File or Blob data
readonly attribute (DOMString or ArrayBuffer)? result;

readonly attribute DOMException? error;

// event handler content attributes
attribute EventHandler onloadstart;
attribute EventHandler onprogress;
attribute EventHandler onload;
attribute EventHandler onabort;
attribute EventHandler onerror;
attribute EventHandler onloadend;
};

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
constructor();
// Synchronously return strings

ArrayBuffer readAsArrayBuffer(Blob blob);
DOMString readAsBinaryString(Blob blob);
DOMString readAsText(Blob blob, optional DOMString encoding);
DOMString readAsDataURL(Blob blob);
};

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
static DOMString createObjectURL((Blob or MediaSource) obj);
static undefined revokeObjectURL(DOMString url);
};

 

Указатель проблем

Нам нужно более конкретно указать, что на самом деле происходит при чтении из Blob, какие возможные ошибки могут произойти, возможно, что-то о размерах блоков и т. Д. ↵

Мы могли бы изменить loadstart, чтобы он отправлялся синхронно, чтобы соответствовать поведению XMLHttpRequest. <https://github.com/w3c/FileAPI/issues/119> ↵

Лучше указать, как генерируется DataURL. <https://github.com/w3c/FileAPI/issues/104> ↵

Для этого нужен аналогичный крючок, когда рабочий выгружен. ↵

Этот раздел является предварительным; дополнительные данные безопасности могут дополнить это в последующих проектах. ↵