FileSystemSyncAccessHandle: write() メソッド
Baseline
広く利用可能
この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2023年3月以降、すべてのブラウザーで利用可能です。
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
メモ: この機能は専用ウェブワーカー内でのみ利用可能です。
write() は FileSystemSyncAccessHandle インターフェイスのメソッドで、指定したバッファーの内容をハンドルに対応するファイルに書き込みます。オフセットを指定することもできます。
エンドユーザーには見えないオリジンプライベートファイルシステム内のファイルは、ユーザーに見えるファイルシステム内のファイルに対する操作と同じセキュリティチェックの対象になりません。そのため、FileSystemSyncAccessHandle.write() による書き込みはパフォーマンスが大幅に向上します。このような特性により、SQLite(英語) データベースの変更など、大規模なファイル更新に適しています。
構文
write(buffer, options)
引数
buffer-
ファイルに書き込むバッファーを表す
ArrayBufferまたは(DataViewなどの)ArrayBufferViewです。 options省略可-
以下のプロパティを含むオプションオブジェクトです。
at-
バッファーを書き込むファイルの先頭からのバイト単位のオフセットを表す数値です。
返値
ファイルに書き込まれたバイト数を表す数値です。
例外
InvalidStateErrorDOMException-
対応するアクセスハンドルがすでに閉じられている場合、またはファイルのバイナリーデータの変更が完全に失敗した場合に発生します。
QuotaExceededError-
書き込みによるデータ容量の増加がブラウザーのストレージ制限を超える場合に発生します。
TypeError-
基盤となるファイルシステムが、指定されたファイルオフセットからの書き込みに対応していない場合に発生します。
例
以下の非同期のイベントハンドラー関数は、ウェブワーカーの中にあります。メインスレッドからメッセージを受信すると、以下の動作をします。
- 同期式ファイルアクセスハンドルを作成します。
- ファイルのサイズを取得し、格納用の
ArrayBufferを作成します。 - ファイルの内容をバッファーに読み込みます。
- メッセージをエンコードし、ファイルの終端に書き込みます。
- 変更をディスクに書き込み、アクセスハンドルを閉じます。
onmessage = async (e) => {
// メインスクリプトからの処理対象のメッセージを取得する
const message = e.data;
// 下書きファイルのハンドルを取得する
const root = await navigator.storage.getDirectory();
const draftHandle = await root.getFileHandle("draft.txt", { create: true });
// 同期式のアクセスハンドルを取得する
const accessHandle = await draftHandle.createSyncAccessHandle();
// ファイルのサイズを取得する
const fileSize = accessHandle.getSize();
// ファイルの内容をバッファーに読み込む
const buffer = new DataView(new ArrayBuffer(fileSize));
const readBuffer = accessHandle.read(buffer, { at: 0 });
// メッセージをファイルの終端に書き込む
const encoder = new TextEncoder();
const encodedMessage = encoder.encode(message);
const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });
// 変更をディスクに書き込む
accessHandle.flush();
// 完了したら、常に FileSystemSyncAccessHandle を閉じる
accessHandle.close();
};
メモ:
仕様書の以前のバージョンでは、close()、flush()、getSize()、truncate() は誤って非同期メソッドとして規定されていました。一部のブラウザーの古いバージョンでは、これらのメソッドがそのように実装されています。しかし、これらのメソッドに対応する現行のブラウザーでは、すべて同期メソッドとして実装されています。
仕様書
| 仕様書 |
|---|
| File System> # api-filesystemsyncaccesshandle-write> |