API файловой системы

API файловой системы — с расширениями, предоставляемыми через API доступа к файловой системе для доступа к файлам в файловой системе устройства — позволяет выполнять чтение, запись и управление файлами.

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

Большая часть взаимодействия с файлами и каталогами выполняется через обработчики. Родительский класс FileSystemHandle помогает определить два дочерних класса: FileSystemFileHandle и FileSystemDirectoryHandle, для файлов и каталогов соответственно.

Обработчики представляют собой файл или каталог на системе пользователя. Сначала вы можете получить к ним доступ, показав пользователю выбор файла или каталога с помощью таких методов, как window.showOpenFilePicker() и window.showDirectoryPicker(). После вызова этого метода, появляется окно выбора файла, и пользователь выбирает файл или каталог. После успешного выбора возвращается обработчик.

Вы также можете получить доступ к обработчикам файлов через:

• Метод DataTransferItem.getAsFileSystemHandle() интерфейса HTML Drag and Drop API.
• API обработки файлов.

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

Частная файловая система происхождения (OPFS) — это конечная точка хранения, предоставляемая в рамках API файловой системы, которая является частной для источника страницы и не отображается пользователю, как обычная файловая система. Она обеспечивает доступ к специальному типу файла, который оптимизирован для производительности и позволяет выполнять запись на месте.

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

• В случае асинхронных обработчиков используйте интерфейс FileSystemWritableFileStream. После того, как данные, которые вы хотите сохранить, будут в формате Blob, объекта String, строковой литералы или buffer, вы можете открыть поток и сохранить данные в файл. Это может быть существующий файл или новый файл.
• В случае синхронного FileSystemSyncAccessHandle записывайте изменения в файл, используя метод write(). Вы также можете (необязательно) вызвать flush(), если вам необходимо выполнить операцию сохранения изменений на диске в определенное время (иначе вы можете позволить операционной системе обработать это, когда сочтет нужным, что обычно должно быть достаточно в большинстве случаев).

FileSystemHandle

Объект, представляющий запись файла или каталога. Несколько обработчиков могут представлять одну и ту же запись. В основном вы не работаете с FileSystemHandle напрямую, а скорее с его дочерними интерфейсами FileSystemFileHandle и FileSystemDirectoryHandle.

FileSystemFileHandle

Предоставляет обработчик для записи в файловую систему.

FileSystemDirectoryHandle

Предоставляет обработчик для записи в каталог файловой системы.

FileSystemSyncAccessHandle

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

FileSystemWritableFileStream

Объект WritableStream с дополнительными удобными методами, работающий с одним файлом на диске.

Window.showDirectoryPicker()

Отображает окно выбора каталога, которое позволяет пользователю выбрать каталог.

Window.showOpenFilePicker()

Отображает окно выбора файла, которое позволяет пользователю выбрать один или несколько файлов.

Window.showSaveFilePicker()

Отображает окно сохранения файла, которое позволяет пользователю сохранить файл.

DataTransferItem.getAsFileSystemHandle()

Возвращает FileSystemFileHandle, если перетаскиваемый элемент — это файл, или FileSystemDirectoryHandle, если перетаскиваемый элемент — это каталог.

StorageManager.getDirectory()

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

Следующий код позволяет пользователю выбрать файл из окна выбора файла.

async function getFile() {
  // Open file picker and destructure the result the first handle
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  return file;
}

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

const pickerOpts = {
  types: [
    {
      description: "Images",
      accept: {
        "image/*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};

async function getTheFile() {
  // Open file picker and destructure the result the first handle
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // get file contents
  const fileData = await fileHandle.getFile();
}

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

const dirName = "directoryToGetName";

// assuming we have a directory handle: 'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });

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

async function returnPathDirectories(directoryHandle) {
  // Get a file handle by showing a file picker:
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // User cancelled, or otherwise failed to open a file.
    return;
  }

  // Check if handle exists inside our directory handle
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // Not inside directory handle
  } else {
    // relativePaths is an array of names, giving the relative path

    for (const name of relativePaths) {
      // log each entry
      console.log(name);
    }
  }
}

Следующая асинхронная функция открывает окно сохранения файла, которое возвращает FileSystemFileHandle после выбора файла. Затем создается поток для записи с помощью метода FileSystemFileHandle.createWritable().

Затем пользовательский Blob записывается в поток, который затем закрывается.

async function saveFile() {
  // create a new handle
  const newHandle = await window.showSaveFilePicker();

  // create a FileSystemWritableFileStream to write to
  const writableStream = await newHandle.createWritable();

  // write our file
  await writableStream.write(imgBlob);

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

Следующий пример показывает различные варианты параметров, которые можно передать в метод write().

// just pass in the data (no options)
writableStream.write(data);

// writes the data to the stream from the determined position
writableStream.write({ type: "write", position, data });

// updates the current file cursor offset to the position specified
writableStream.write({ type: "seek", position });

// resizes the file to be size bytes long
writableStream.write({ type: "truncate", size });

В этом примере синхронно считывается и записывается файл в исходную частную файловую систему.

Следующая асинхронная функция обработчика событий содержится внутри Web Worker. При получении сообщения с основного потока она:

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

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

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

  // Get size of the file.
  const fileSize = accessHandle.getSize();
  // Read file content to a buffer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Write the message to the end of the file.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persist changes to disk.
  accessHandle.flush();

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

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