Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Web/API/File_System_API 以下を更新・新規翻訳 #17229

Merged
merged 4 commits into from
Dec 5, 2023
Merged

Web/API/File_System_API 以下を更新・新規翻訳 #17229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b304be3
2023/10/26 時点の英語版に基づき更新
mfuji09 Dec 1, 2023
67279dc
2023/10/26 時点の英語版に基づき新規翻訳
mfuji09 Dec 1, 2023
150adab
ヘッダー部分の更新忘れを修正
mfuji09 Dec 1, 2023
77fc29c
Apply suggestions from code review
mfuji09 Dec 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 24 additions & 37 deletions files/ja/web/api/file_system_api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,54 @@
---
title: File System Access API
title: ファイルシステム API
slug: Web/API/File_System_API
l10n:
sourceCommit: 835d6632d59993861a0458510402787f8a2c3cb3
---

{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
{{securecontext_header}}{{DefaultAPISidebar("File System API")}}

File System Access API により、ファイルの読み込み、書き込み、管理ができます。
ファイルシステム API は - [ファイルシステムアクセス API](https://wicg.github.io/file-system-access/) を介して提供される拡張機能により - 端末のファイルシステム上のファイルにアクセスし、読み取り、書き込み、ファイル管理機能を使用することができます。

## 概念と使用法

この API を用いると、ユーザーのローカルデバイス上のファイルや、ユーザーがアクセス可能なネットワークファイルシステムを操作することができます。この API の基本機能として、ファイルの読み込み、ファイルの書き込み (保存)、ディレクトリー構造へのアクセスがあります。
この API を用いると、ユーザーのローカルデバイス上のファイルや、ユーザーがアクセス可能なネットワークファイルシステムを操作することができます。この API の基本機能として、ファイルの読み込み、ファイルの書き込み（保存）、ディレクトリー構造へのアクセスがあります。

ファイルやディレクトリーの操作のほとんどは、ハンドルを介して行います。親クラスの {{domxref('FileSystemHandle')}} の補助により {{domxref('FileSystemFileHandle')}} および {{domxref('FileSystemDirectoryHandle')}} の 2 個の子クラスが定義されており、それぞれファイルおよびディレクトリーの操作に用います。

ハンドルは、ユーザーのシステム上のファイルやディレクトリーを表します。まず、{{domxref('window.showOpenFilePicker()')}} や {{domxref('window.showDirectoryPicker()')}} などのメソッドを用いてユーザーにファイルピッカーまたはディレクトリーピッカーを表示し、ファイルやディレクトリーへのアクセス権を得ることができます。これらのメソッドが呼ばれると、ファイルピッカーが現れ、ユーザーがファイルまたはディレクトリーを選択します。この流れがうまくいくと、ハンドルが返されます。

以下の方法によりファイルハンドルへのアクセス権を得ることもできます。

- {{domxref('HTML Drag and Drop API', 'HTML Drag and Drop API', '', 'nocode')}} の {{domxref('DataTransferItem.getAsFileSystemHandle()')}} メソッド
- [File Handling API](https://developer.chrome.com/en/articles/file-handling/)
- {{domxref('HTML Drag and Drop API', 'HTML ドラッグ＆ドロップ API', '', 'nocode')}} の {{domxref('DataTransferItem.getAsFileSystemHandle()')}} メソッド
- [ファイルハンドリング API](https://developer.chrome.com/en/articles/file-handling/)

それぞれのハンドルが自身の機能を提供し、どっちを使っているかによって少し違いがあります。(詳細は、[インターフェイス](#%E3%82%A4%E3%83%B3%E3%82%BF%E3%83%BC%E3%83%95%E3%82%A7%E3%82%A4%E3%82%B9)の節を参照してください) ファイルのデータや、選択されたディレクトリーの情報 (子を含む) にアクセスできます。この API により、ウェブに欠けていた潜在的な機能への道が開きます。それでも、セキュリティは API の設計時に最大限考慮するべきことであり、ファイルやディレクトリーのデータへのアクセスはユーザーが特に許可しない限り禁止されています。
それぞれのハンドルが自身の機能を提供し、どっちを使っているかによって少し違いがあります（詳細は、[インターフェイス](#%E3%82%A4%E3%83%B3%E3%82%BF%E3%83%BC%E3%83%95%E3%82%A7%E3%82%A4%E3%82%B9)の節を参照してください）。ファイルのデータや、選択されたディレクトリーの情報（子を含む）にアクセスできます。この API により、ウェブに欠けていた潜在的な機能への道が開きます。それでも、セキュリティは API の設計時に最大限考慮するべきことであり、ファイルやディレクトリーのデータへのアクセスはユーザーが特に許可しない限り禁止されています（これは、ユーザーから見えない[オリジンプライベートファイルシステム](#オリジンプライベートファイルシステム)の場合とは異なります）。

> **メモ:** API の機能を使う際に投げられる可能性がある例外は、仕様書での定義に沿って関連するページに一覧が載っています。しかし、API と下層のオペレーティングシステムの相互作用により、状況はより複雑になります。[仕様書でエラーの対応関係を一覧にする](https://github.com/whatwg/fs/issues/57)ための提案がなされており、ここに有用な関連情報があります。
> **メモ:** API の機能を使う際に投げられる可能性がある例外は、仕様書での定義に沿って関連するページに一覧が載っています。しかし、 API と下層のオペレーティングシステムの相互作用により、状況はより複雑になります。[仕様書でエラーの対応関係を一覧にする](https://github.com/whatwg/fs/issues/57)ための提案がなされており、ここに有用な関連情報があります。

> **メモ:** {{domxref("FileSystemHandle")}} をベースとするオブジェクトは、{{domxref("IndexedDB API", "IndexedDB", "", "nocode")}} のデータベースのインスタンスにシリアライズしたり、{{domxref("window.postMessage", "postMessage()")}} を介して転送したりできます。

### オリジンプライベートファイルシステム

[オリジンプライベートファイルシステム (OPFS)](https://fs.spec.whatwg.org/#origin-private-file-system) は、ページのオリジン固有のストレージのエンドポイントであり、パフォーマンスに高度に最適化された特別な種類のファイルへのアクセスを選択可能です。例えば、ファイルの内容を in-place で排他的に書き換えることができます。
オリジンプライベートファイルシステム (OPFS) は、ページのオリジン固有のストレージのエンドポイントであり、パフォーマンスに高度に最適化された特別な種類のファイルへのアクセスを選択可能です。例えば、ファイルの内容をその場 (in-place) で排他的に書き換えることができます。

OPFS へのファイルの保存は、({{domxref("IndexedDB API", "IndexedDB API", "", "nocode")}} などの) ブラウザーが提供する他のページのオリジンに固有のデータを保存する仕組みに似ています。すなわち、OPFS 内のファイルは、ピッカーを用いて選択されたファイルとは以下の点で異なります。

- OPFS 内のファイルへのアクセスには、許可の要求は必要ありません。
- サイトのデータを消去すると、OPFS も消去されます。
- OPFS は、ブラウザーが使う容量の制限の対象になります。

OPFS 内のファイルは、以下の 3 ステップで操作できます。

1. (ワーカーやメインスレッドで [`navigator.storage.getDirectory()`](/ja/docs/Web/API/Navigator/storage) で得られる) {{domxref("StorageManager.getDirectory()")}} メソッドを呼び、ディレクトリーとその中身にアクセスするための {{domxref("FileSystemDirectoryHandle")}} オブジェクトへの参照を得ます。これは、OPFS のルートを表します。
2. {{domxref("FileSystemDirectoryHandle.getFileHandle()")}} メソッドを呼び、ディレクトリ内の特定のファイルのハンドルを表す {{domxref('FileSystemFileHandle')}} オブジェクトを得ます。
3. そのファイルハンドルで {{domxref('FileSystemFileHandle.createSyncAccessHandle', 'createSyncAccessHandle()')}} メソッドを呼び、ファイルの読み書きに利用できる {{domxref('FileSystemSyncAccessHandle')}} オブジェクトを得ます。これは、_同期式の_ 読み書き操作を行うための高効率なハンドルです。(他のハンドルの種類では非同期です) このクラスの同期式であるという性質は、([WebAssembly](/ja/docs/WebAssembly) などの) 非同期の操作が大きなオーバーヘッドに繋がる状況での使用を意図した、パフォーマンスの優位性をもたらします。なお、これはそれ用の [Web Workers](/ja/docs/Web/API/Web_Workers_API) 内でのみ使用可能です。

ブラウザーは通常 OPFS の内容をディスク上のどこかに保存して永続化することで実装しますが、これは内容にユーザーが簡単にアクセスできるようにすることを意図したものではありません。ブラウザーはファイルがあるように見せるかもしれない一方、データベースや他の任意のデータ構造に保存されているかも知れません。作成したファイルがハードディスク上のどこかに 1 対 1 対応で置かれていることを期待することはできません。

> **メモ:** {{domxref('FileSystemSyncAccessHandle.write()')}} による書き込みは in-place で行われます。すなわち、変更は writer に書き込まれると同時に実際の対応するファイルに書き込まれます。これは ({{domxref('FileSystemFileHandle.createWritable()')}} などの) この API で利用可能な書き込みのための他の仕組みでは成り立たず、書き込みストリームが閉じられるまで変更はディスクに書き込まれません。
使い方の説明は、[オリジンプライベートファイルシステム](/ja/docs/Web/API/File_System_API/Origin_private_file_system)を読んでください。

### ファイルの保存

「保存」の機能があります。

- 非同期ハンドルでは、{{domxref('FileSystemWritableFileStream')}} インターフェイスを使います。保存したいデータを {{domxref('Blob')}}、{{jsxref("String")}} オブエクト、文字列リテラル、{{jsxref('ArrayBuffer', 'buffer')}} のいずれかの形式にしたら、ストリームを開いてデータをファイルに保存できます。既存のファイルも新しいファイルも保存先にできます。
- 同期式の {{domxref('FileSystemSyncAccessHandle')}} では、{{domxref('FileSystemSyncAccessHandle.write', 'write()')}} メソッドを用いて変更をファイルに書き込みます。特定のタイミングで変更をディスクに書き込みたい場合は、{{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} を呼ぶことができます。(これを呼ばない場合、下層のオペレーティングシステムに任せて都合のいいときに処理させることができ、ほとんどの場合はこれでいいでしょう)
- 同期的に {{domxref('FileSystemSyncAccessHandle')}} では、{{domxref('FileSystemSyncAccessHandle.write', 'write()')}} メソッドを用いて変更をファイルに書き込みます。特定のタイミングで変更をディスクに書き込みたい場合は、{{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} を呼ぶことができます。(これを呼ばない場合、下層のオペレーティングシステムに任せて都合のいいときに処理させることができ、ほとんどの場合はこれでいいでしょう)

## インターフェイス

- {{domxref("FileSystemHandle")}}
- : **`FileSystemHandle`** インターフェイスは、エントリーを表すオブジェクトです。複数のハンドルが同じエントリーを表すことがあります。ほとんどの場面では、`FileSystemHandle` を直接扱うことはなく、子インターフェイスの {{domxref('FileSystemFileHandle')}} や {{domxref('FileSystemDirectoryHandle')}} を扱うことになるでしょう。
- : **`FileSystemHandle`** インターフェイスは、項目を表すオブジェクトです。複数のハンドルが同じ項目を表すことがあります。ほとんどの場面では、`FileSystemHandle` を直接扱うことはなく、子インターフェイスの {{domxref('FileSystemFileHandle')}} や {{domxref('FileSystemDirectoryHandle')}} を扱うことになるでしょう。
- {{domxref("FileSystemFileHandle")}}
- : ファイルシステムのエントリーを表すハンドルを提供します。
- : ファイルシステムの項目を表すハンドルを提供します。
- {{domxref("FileSystemDirectoryHandle")}}
- : ファイルシステムのディレクトリーを表すハンドルを提供します。
- {{domxref("FileSystemSyncAccessHandle")}}
- : ディスク上の単一のファイルを in-place で操作する、ファイルシステムのエントリーへの同期式のハンドルを提供します。このファイルの読み書きを同期式で行える性質は、[WebAssembly](/ja/docs/WebAssembly) などの非同期操作が大きなオーバーヘッドに繋がる場面における重要なメソッドで処理効率を高めることを可能にします。このクラスは、それ用の [Web Workers](/ja/docs/Web/API/Web_Workers_API) 内で[オリジンプライベートファイルシステム](#%E3%82%AA%E3%83%AA%E3%82%B8%E3%83%B3%E3%83%97%E3%83%A9%E3%82%A4%E3%83%99%E3%83%BC%E3%83%88%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0)内のファイルを扱う場合のみ使用可能です。
- : ディスク上の単一のファイルをその場 (in-place) で操作する、ファイルシステムの項目への同期的にハンドルを提供します。このファイルの読み書きを同期的に行える性質は、[WebAssembly](/ja/docs/WebAssembly) などの非同期操作が大きなオーバーヘッドに繋がる場面における重要なメソッドで処理効率を高めることを可能にします。このクラスは、それ用の[ウェブワーカー](/ja/docs/Web/API/Web_Workers_API)内で[オリジンプライベートファイルシステム](#オリジンプライベートファイルシステム)内のファイルを扱う場合のみ使用可能です。
- {{domxref("FileSystemWritableFileStream")}}
- : ディスク上の単一のファイルを操作する便利な関数が追加された {{domxref('WritableStream')}} です。

Expand Down Expand Up @@ -137,7 +123,7 @@ async function returnPathDirectories(directoryHandle) {
// relativePaths は、相対パスを表す名前の配列

for (const name of relativePaths) {
// 各エントリーを記録する
// 各項目を記録する
console.log(name);
}
}
Expand Down Expand Up @@ -182,13 +168,13 @@ writableStream.write({ type: "seek", position });
writableStream.write({ type: "truncate", size });
```

### OPFS 内のファイルを同期式で読み書きする
### OPFS 内のファイルを同期的に読み書きする

この例では、[オリジンプライベートファイルシステム](#%E3%82%AA%E3%83%AA%E3%82%B8%E3%83%B3%E3%83%97%E3%83%A9%E3%82%A4%E3%83%99%E3%83%BC%E3%83%88%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0) 内のファイルを同期式で読み書きします。
この例では、[オリジンプライベートファイルシステム](#オリジンプライベートファイルシステム)内のファイルを同期的に読み書きします。

以下の非同期のイベントハンドラー関数は、ウェブワーカー内にあります。メインスレッドからメッセージを受信した時、以下の処理をします。

- 同期式のファイルアクセスハンドルを生成する
- 同期的にファイルアクセスハンドルを生成する
- ファイルのサイズを取得し、格納するための {{jsxref("ArrayBuffer")}} を生成する
- ファイルの内容をバッファーに読み込む
- メッセージをエンコードし、ファイルの最後に書き込む
Expand All @@ -202,7 +188,7 @@ onmessage = async (e) => {
// OPFS 内の draft ファイルのハンドルを得る
const root = await navigator.storage.getDirectory();
const draftHandle = await root.getFileHandle("draft.txt", { create: true });
// 同期式のアクセスハンドルを得る
// 同期的にアクセスハンドルを得る
const accessHandle = await draftHandle.createSyncAccessHandle();

// ファイルのサイズを得る
Expand All @@ -224,7 +210,7 @@ onmessage = async (e) => {
};
```

> **メモ:** 仕様書の以前のバージョンでは、{{domxref("FileSystemSyncAccessHandle.close()", "close()")}}・{{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}・{{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}・{{domxref("FileSystemSyncAccessHandle.truncate()", "truncate()")}} は人間工学に反して非同期メソッドとされていました。これは現在では[変更されています](https://github.com/whatwg/fs/issues/7)が、まだ非同期バージョンをサポートしているブラウザーもあります。
> **メモ:** 仕様書の以前のバージョンでは、{{domxref("FileSystemSyncAccessHandle.close()", "close()")}}、{{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}、{{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}、{{domxref("FileSystemSyncAccessHandle.truncate()", "truncate()")}} は人間工学に反して非同期メソッドとされていました。これは現在では[変更されています](https://github.com/whatwg/fs/issues/7)が、まだ非同期バージョンをサポートしているブラウザーもあります。

## 仕様書

Expand All @@ -236,4 +222,5 @@ onmessage = async (e) => {

## 関連情報

- [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/)
- [The File System Access API: simplifying access to local files](https://developer.chrome.com/articles/file-system-access/) (web.dev)
- [The origin private file system](https://web.dev/articles/origin-private-file-system) (web.dev)
Loading