はじめに

前回、 OPFS の API として、 File System Access API の概説を行ってきました。今回は、その中のディレクトリ操作に焦点を当てて、解説していきたいと思います。

OPFS のルートディレクトリ取得

OPFS のルートディレクトリの Handle は、StorageManager オブジェクトの getDirectory() メソッドを呼び出すことで取得できます。

StorageManager オブジェクトは、 navigator オブジェクトの読み取り専用の storage プロパティからアクセス可能です。

戻り値は、FileSystemDirectoryHandle オブジェクトとなります。

const root = await navigator.storage.getDirectory();

👉 これが、 OPFS のディレクトリの先頭になります。

FileSystemDirectoryHandle オブジェクト

FileSystemDirectoryHandle オブジェクト は、ディレクトリを操作するためのオブジェクトです。

OPFSでは、ディレクトリの作成・取得・削除・一覧取得などを担当します。

なお、FileSystemDirectoryHandle オブジェクト は FileSystemHandle オブジェクト を継承しています。

FileSystemHandle は、ファイルやディレクトリを表す Handle オブジェクトの共通の基底オブジェクトです。

そのため、

  • name
  • kind
  • isSameEntry()

など、FileSystemFileHandle オブジェクトと共通のプロパティやメソッドも利用できます。

name プロパティ

ディレクトリの名前を取得できます。

console.log(dirHandle.name);　// 例：images

※ ルートディレクトリには名前がないため、空文字列 ("") が返されます。

kind プロパティ

ディレクトリの種別を取得できます。常に、"directory" が返されます。

console.log(dirHandle.kind); // directory

getDirectoryHandle() メソッド

指定した名前のサブディレクトリの Handle を取得します。存在しない場合は作成も可能です。

const images =
  await root.getDirectoryHandle(
    "images",
    { create: true }
  );

■ パラメータ

  • ディレクトリ名
  • options オブジェクト

■ options オブジェクト

プロパティ 値 説明
create true 存在しない場合に作成
false 存在しない場合エラー

■ 戻り値

Promise オブジェクト

await 完了後、FileSystemDirectoryHandle オブジェクト

getFileHandle() メソッド

指定した名前のファイルの Handle を取得します。存在しない場合は作成も可能です。

const fileHandle =
  await dirHandle.getFileHandle(
    "image001.jpg",
    { create: true }
  );

■ パラメータ

  • ファイル名
  • options オブジェクト

■ options オブジェクト

プロパティ 値 説明
create true 存在しない場合に作成
false 存在しない場合エラー

■ 戻り値

Promise オブジェクト

await 完了後、FileSystemFileHandle オブジェクト

removeEntry() メソッド

配下のファイルまたはサブディレクトリを削除します。

// ファイルの削除
await dirHandle.removeEntry(
  "image001.jpg"
);

// サブディレクトリの削除
await dirHandle.removeEntry(
  "images",
  { recursive: true }
);

■ パラメータ

  • 名前
  • options オブジェクト

■ options オブジェクト

プロパティ 値 説明
recursive true 子要素も含めて削除
false 子要素が存在する場合エラー

■ 戻り値

Promise オブジェクト

await 完了後、undefined

entries() メソッド

配下のファイルやサブディレクトリの名前とHandleの一覧を取得します。

for await (const [name, handle] of dirHandle.entries()) {
  console.log(name, handle);
}

entries() は、Map の entries() と似たイメージで、

[name, handle]

のペアを順番に返します。

■ パラメータ

なし

■ 戻り値

非同期イテレーター( AsyncIterator )

keys() メソッド

配下のファイルやサブディレクトリの名前だけ取得します。

for await (const name of dirHandle.keys()) {
  console.log(name);
}

■ パラメータ

なし

■ 戻り値

非同期イテレーター( AsyncIterator )

values() メソッド

配下のファイルやサブディレクトリのHandleだけ取得します。

for await (const handle of dirHandle.values()) {
  console.log(handle.name);
}

■ パラメータ

なし

■ 戻り値

非同期イテレーター( AsyncIterator )

resolve() メソッド

現在のディレクトリを起点として、指定した Handle までの相対パスを取得します。

少しマニアックなAPIです。

const path =
  await root.resolve(fileHandle);

■ パラメータ

  • Handle オブジェクト
    • FileSystemDirectoryHandle
    • FileSystemFileHandle

■ options オブジェクト

なし

■ 戻り値

戻り値

Promise オブジェクト

await 完了後、パスの構成要素の配列

例：

ルート
 └─ images
       ├─ image001.jpg
       ├─ image002.jpg
       └─ image003.jpg

のディレクトリ構成において、

const root = await navigator.storage.getDirectory();
const dirHandle = await root.getDirectoryHandle(
    "images",
    { create: false }
);
const fileHandle =
  await dirHandle.getFileHandle(
    "image001.jpg",
    { create: false }
  );
const path = await root.resolve(fileHandle);

を実行すると path は、

["images", "image001.jpg"]

となります。

※ 対象が配下に存在しない場合は、 null が戻されます。

remove() メソッド

自身を削除します。

await dirHandle.remove();

ただし、ブラウザにより実装対応に差があるため、使用時は、確認が必要です。

👉 互換性が気になる場合は、 removeEntry() を使用する方が無難です。

まとめ

  • FileSystemDirectoryHandle オブジェクトは、ディレクトリを操作する中心的なオブジェクトである。
  • ディレクトリの取得や一覧取得を行い、ファイル操作の起点となる。
  • 次回は FileSystemFileHandle オブジェクトについて解説する。