FileSystemFileHandle: метод createSyncAccessHandle()

Метод createSyncAccessHandle() интерфейса FileSystemFileHandle возвращает Promise, который разрешается в объект FileSystemSyncAccessHandle, который может использоваться для синхронного чтения и записи в файл. Синхронная природа этого метода обеспечивает преимущества производительности, но он может использоваться только внутри посвящённых веб-воркеров для файлов в частной файловой системе происхождения.

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

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

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

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

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

"read-only"

Несколько объектов FileSystemSyncAccessHandle могут быть открыты одновременно для файла (например, при использовании одного приложения в нескольких вкладках), если все они открыты в режиме "read-only". После открытия к обработчикам можно применять методы чтения — read(), getSize() и close().

"readwrite"

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

"readwrite-unsafe"

Несколько объектов FileSystemSyncAccessHandle могут быть открыты одновременно для файла, если все они открыты в режиме "readwrite-unsafe". После открытия к обработчикам можно применять все доступные методы.

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

NotAllowedError DOMException

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

InvalidStateError DOMException

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

NotFoundError DOMException

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

NoModificationAllowedError DOMException

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

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

onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // …

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

Наш createSyncAccessHandle() тест режима предоставляет поле ввода <input>, чтобы вводить текст, и две кнопки — одну для записи введённого текста в конец файла в частной файловой системе происхождения, и одну для очистки файла, когда он заполняется слишком сильно.

Попробуйте запустить демонстрацию выше, с открытой консолью разработчика браузера, чтобы увидеть, что происходит. Если вы попробуете открыть демонстрацию в нескольких вкладках браузера, вы обнаружите, что несколько обработчиков могут быть открыты одновременно для записи в файл одновременно. Это происходит потому, что mode: "readwrite-unsafe" установлено в вызовах createSyncAccessHandle().

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

HTML

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

<ol>
  <li>
    <label for="file-text">Enter text to write to the file:</label>
    <input type="text" id="file-text" name="file-text" />
  </li>
  <li>
    Write your text to the file: <button class="write">Write text</button>
  </li>
  <li>
    Empty the file if it gets too full:
    <button class="empty">Empty file</button>
  </li>
</ol>

Основной JavaScript

Основной JavaScript-код в файле HTML показан ниже. Мы получаем ссылки на кнопку записи текста, кнопку очистки файла и поле ввода текста, а затем создаём новый веб-воркер, используя конструктор Worker(). Затем мы определяем две функции и устанавливаем их как обработчики событий на кнопках:

• writeToOPFS() выполняется при нажатии кнопки записи текста. Эта функция публикует введённое значение поля ввода в воркер внутри объекта, используя метод Worker.postMessage(), затем очищает поле ввода, готовое для следующего добавления. Обратите внимание, как переданный объект также содержит свойство command: "write" для указания того, что мы хотим вызвать действие записи с этим сообщением.
• emptyOPFS() выполняется при нажатии кнопки очистки файла. Это публикует объект, содержащий свойство command: "empty" в воркер, указывая, что файл должен быть очищен.

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

const opfsWorker = new Worker("worker.js");

function writeToOPFS() {
  opfsWorker.postMessage({
    command: "write",
    content: fileText.value,
  });
  console.log("Main script: Text posted to worker");
  fileText.value = "";
}

function emptyOPFS() {
  opfsWorker.postMessage({
    command: "empty",
  });
}

writeBtn.addEventListener("click", writeToOPFS);
emptyBtn.addEventListener("click", emptyOPFS);

JavaScript в воркере

Код JavaScript в воркере показан ниже.

Сначала мы выполняем функцию initOPFS(), которая получает ссылку на корень OPFS, используя StorageManager.getDirectory(), создаёт файл и возвращает его обработчик, используя FileSystemDirectoryHandle.getFileHandle(), а затем возвращает FileSystemSyncAccessHandle, используя createSyncAccessHandle(). Этот вызов включает свойство mode: "readwrite-unsafe", позволяя нескольким обработчикам одновременно получать доступ к одному и тому же файлу.

let accessHandle;

async function initOPFS() {
  const opfsRoot = await navigator.storage.getDirectory();
  const fileHandle = await opfsRoot.getFileHandle("file.txt", { create: true });
  accessHandle = await fileHandle.createSyncAccessHandle({
    mode: "readwrite-unsafe",
  });
}

initOPFS();

Внутри обработчика событий сообщения воркера мы сначала получаем размер файла, используя getSize(). Затем мы проверяем, содержит ли переданные данные свойство command со значением "empty". Если да, то мы очищаем файл, используя truncate() со значением 0, и обновляем размер файла, хранящийся в переменной size.

Если данные сообщения являются чем-то другим, мы:

• Создаём новые кодировщик TextEncoder и декодировщик TextDecoder для обработки кодирования и декодирования текстового содержимого позже.
• Кодируем данные сообщения и записываем результат в конец файла, используя write(), затем обновляем размер файла, хранящийся в переменной size.
• Создаём DataView для хранения содержимого файла и читаем содержимое в него, используя read().
• Декодируем содержимое DataView и выводим его в консоль.

onmessage = function (e) {
  console.log("Worker: Message received from main script");

  // Get the current size of the file
  let size = accessHandle.getSize();

  if (e.data.command === "empty") {
    // Truncate the file to 0 bytes
    accessHandle.truncate(0);

    // Get the current size of the file
    size = accessHandle.getSize();
  } else {
    const textEncoder = new TextEncoder();
    const textDecoder = new TextDecoder();

    // Encode content to write to the file
    const content = textEncoder.encode(e.data.content);
    // Write the content at the end of the file
    accessHandle.write(content, { at: size });

    // Get the current size of the file
    size = accessHandle.getSize();

    // Prepare a data view of the length of the file
    const dataView = new DataView(new ArrayBuffer(size));

    // Read the entire file into the data view
    accessHandle.read(dataView, { at: 0 });

    // Log the current file contents to the console
    console.log("File contents: " + textDecoder.decode(dataView));

    // Flush the changes
    accessHandle.flush();
  }

  // Log the size of the file to the console
  console.log("Size: " + size);
};

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