FileSystemFileHandle: метод createWritable()

Метод createWritable() интерфейса FileSystemFileHandle создаёт поток FileSystemWritableFileStream, который можно использовать для записи в файл. Метод возвращает Promise, который разрешается в этот созданный поток.

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

options Необязательно

Объект со следующими свойствами:

keepExistingData Необязательно

Boolean. Значение по умолчанию: false. Если установлено true, и файл существует, то сначала существующий файл копируется во временный файл. В противном случае временный файл создаётся пустым.

mode Необязательно Нестандартный

Строка, определяющая режим блокировки для потока записи файла. Значение по умолчанию: "siloed". Возможные значения:

"exclusive"

Только один FileSystemWritableFileStream писатель может быть открыт. Попытка открыть последующих писателей до закрытия первого писателя приведёт к исключению NoModificationAllowedError.

"siloed"

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

A Promise, который разрешается в объект FileSystemWritableFileStream.

NotAllowedError DOMException

Выбрасывается, если PermissionStatus.state для обработчика не равно 'granted' в режиме readwrite.

NotFoundError DOMException

Выбрасывается, если текущая запись не найдена.

NoModificationAllowedError DOMException

Выбрасывается, если браузер не может заблокировать файл, связанный с файловым обработчиком. Это может произойти, если mode установлено в exclusive и одновременно делается попытка открыть нескольких писателей.

AbortError DOMException

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

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

async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();

  // Write the contents of the file to the stream.
  await writable.write(contents);

  // Close the file and write the contents to disk.
  await writable.close();
}

Наш пример createWritable() тест режима предоставляет <button> для выбора файла для записи, текстовое поле <input>, в которое можно ввести текст для записи в файл, и вторую кнопку <button> для записи текста в файл.

В демонстрации выше, попробуйте выбрать текстовый файл в вашей файловой системе (или ввести новое имя файла), введите некоторый текст в поле ввода и запишите текст в файл. Откройте файл в вашей файловой системе, чтобы проверить, была ли запись успешной.

Также попробуйте открыть страницу в двух вкладках браузера одновременно. Выберите файл для записи в первой вкладке, а затем немедленно попробуйте выбрать тот же файл для записи во второй вкладке. Вы получите сообщение об ошибке, так как мы установили mode: "exclusive" в вызове createWritable().

Ниже мы рассмотрим код.

HTML

Два элемента <button> и текстовое поле <input> выглядят так:

<ol>
  <li>
    Select a file to write to: <button class="select">Select file</button>
  </li>
  <li>
    <label for="file-text">Enter text to write to the file:</label>
    <input type="text" id="file-text" name="file-text" disabled />
  </li>
  <li>
    Write your text to the file:
    <button class="write" disabled>Write text</button>
  </li>
</ol>

Поле ввода текста и кнопка «Записать текст» изначально отключены с помощью атрибута disabled — они не должны использоваться, пока пользователь не выберет файл для записи.

JavaScript

Начнём с получения ссылок на кнопку выбора файла, кнопку «Записать текст» и поле ввода текста. Мы также объявляем глобальную переменную writableStream, которая будет хранить ссылку на поток записи для записи текста в файл после его создания. Изначально она установлена в null.

const selectBtn = document.querySelector(".select");
const writeBtn = document.querySelector(".write");
const fileText = document.querySelector("#file-text");

let writableStream = null;

Далее, создадим асинхронную функцию под названием selectFile(), которую мы вызовем при нажатии кнопки выбора. Она использует метод Window.showSaveFilePicker() для отображения диалога выбора файла у пользователя и создания файлового обработчика выбранного файла. Для этого обработчика мы вызываем метод createWritable() для создания потока записи для записи текста в выбранный файл. Если вызов завершается ошибкой, мы записываем ошибку в консоль.

Мы передаём createWritable() объект параметров, содержащий следующие параметры:

• keepExistingData: true: Если выбранный файл уже существует, то содержимое файла копируется во временный файл перед началом записи.
• mode: "exclusive": Указывает, что только один писатель может быть открыт для файлового обработчика одновременно. Если другой пользователь загрузит пример и попытается выбрать файл, он получит сообщение об ошибке.

Наконец, мы активируем поле ввода и кнопку «Записать текст», так как они нужны для следующего шага, и деактивируем кнопку «Выбрать файл» (на данный момент это не требуется).

async function selectFile() {
  // Create a new handle
  const handle = await window.showSaveFilePicker();

  // Create a FileSystemWritableFileStream to write to
  try {
    writableStream = await handle.createWritable({
      keepExistingData: true,
      mode: "exclusive",
    });
  } catch (e) {
    if (e.name === "NoModificationAllowedError") {
      console.log(
        `You can't access that file right now; someone else is trying to modify it. Try again later.`,
      );
    } else {
      console.log(e.message);
    }
  }

  // Enable text field and write button, disable select button
  fileText.disabled = false;
  writeBtn.disabled = false;
  selectBtn.disabled = true;
}

Наша следующая функция, writeFile(), записывает текст, введённый в поле ввода, в выбранный файл с помощью FileSystemWritableFileStream.write(), затем очищает поле ввода. Затем мы закрываем поток записи с помощью WritableStream.close() и сбрасываем демонстрацию, чтобы её можно было запустить снова — состояния элементов управления возвращаются в исходное состояние, и переменная writableStream устанавливается обратно в null.

async function writeFile() {
  // Write text to our file and empty out the text field
  await writableStream.write(fileText.value);
  fileText.value = "";

  // Close the file and write the contents to disk.
  await writableStream.close();

  // Disable text field and write button, enable select button
  fileText.disabled = true;
  writeBtn.disabled = true;
  selectBtn.disabled = false;

  // Set writableStream back to null
  writableStream = null;
}

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

selectBtn.addEventListener("click", selectFile);
writeBtn.addEventListener("click", writeFile);

• API системы файлов
• API доступа к файловой системе: упрощение доступа к локальным файлам