FileSystemSyncAccessHandle.write()
Baseline 2023
Newly available
Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
FileSystemSyncAccessHandle
インターフェイスの write()
メソッドは、指定のバッファーの内容をハンドルに対応するファイルに書き込みます。オフセットを指定することもできます。ArrayBuffer
の内容を直接操作することはできないことに注意してください。かわりに、バッファーを指定の形式で表す Int8Array
などの型付き配列オブジェクトの一つ、または DataView
オブジェクトを作成し、それを用いてバッファーの内容を読み書きします。
FileSystemSyncAccessHandle.write()
により行われる書き込みは in-place です。すなわち、変更は writer に書き込まれるのと同時に実際のファイルに書き込まれます。これは (FileSystemFileHandle.createWritable()
などの) File System Access API で利用可能な他の書き込みの仕組みでは成り立たず、変更は書き込みストリームが閉じられるまでディスクに書き込まれません。
構文
write(buffer, FileSystemReadWriteOptions)
引数
buffer
-
ファイルに書き込むバッファーを表す
ArrayBuffer
または (DataView
などの)ArrayBufferView
です。 FileSystemReadWriteOptions
省略可-
以下のプロパティを含むオプションオブジェクトです。
at
-
バッファーを書き込むファイルの先頭からのバイト単位のオフセットを表す数値です。
返値
ファイルに書き込まれたバイト数を表す数値で解決する Promise
を返します。
例外
InvalidStateError
DOMException
-
対応するアクセスハンドルが既に閉じられているとき投げられます。
例
以下の非同期のイベントハンドラー関数は、Web Worker の中にあります。メインスレッドからメッセージを受信すると、以下の動作をします。
- 同期式ファイルアクセスハンドルを作成します。
- ファイルのサイズを取得し、格納用の
ArrayBuffer
を作成します。 - ファイルの内容をバッファーに読み込みます。
- メッセージをエンコードし、ファイルの終端に書き込みます。
- 変更をディスクに書き込み、アクセスハンドルを閉じます。
onmessage = async (e) => {
// メインスクリプトからの処理対象のメッセージを取得する
const message = e.data;
// draft ファイルのハンドルを取得する
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()
は誤って非同期のメソッドとされていました。これは現在は変更されていますが、まだ非同期バージョンをサポートしているブラウザーもあります。
仕様書
Specification |
---|
File System Standard # api-filesystemsyncaccesshandle-write |
ブラウザーの互換性
BCD tables only load in the browser