File System Access API による永続的なファイル操作
ネイティブのファイルハンドルを IndexedDB に保存すると、再訪時にローカルファイルを選び直さずに開けます。この読み取り専用デモには、ページ、起動処理、ボタン、権限の再取得処理が含まれます。ファイルはローカルで読み取ります。アップロードを再開するには、別途、アップロード状態の保存と、対応するサーバープロトコルが必要です。
ブラウザーの対応状況とプログレッシブエンハンスメント
永続化を使う場合は、showOpenFilePicker を公開するデスクトップブラウザーを使います。このデモは Linux 上の Chromium 145.0.7632.6 で、ファイル入力のフォールバックは
Firefox 146.0.1 でテストしました。対象ブラウザーについては、ピッカーの互換性表を確認してください。IndexedDB やオリジンプライベートファイルシステム(OPFS)に対応していても、ユーザーのディスク上のファイルを選択できるとは限りません。
フォールバックでは、選択した File を今回のアクセス中だけ読み取ります。ネイティブハンドルの永続化や、再読み込み後にファイルを再度開く操作はできません。ページにはこの違いが表示され、再度開くボタンは無効になります。
ローカルデモのセットアップ
最新のパッチを適用した Node.js 24 または 26 の LTS リリースを使います。以下のコマンドは、2026年11月6日に Node.js 24.22.2 と 26.13.0、Corepack 0.34.5 を使って検証しました。Corepack がない場合は、Corepack のインストール手順に従って別途インストールしてください。この例では Yarn 4.12.0 と Vite 8.3.2 にバージョンを固定します。Vite はブラウザー用の TypeScript をコンパイルします。アップロードの受信処理やサーバー側のファイルアクセスはありません。
Bash で、プロジェクトを作成する前に前提条件を確認します。サブシェルを使うため、ターミナルの作業ディレクトリは元のままです。同じ名前がすでに存在する場合は別の名前を選び、そのフォルダーを上書きしないでください。
(
node --version && corepack --version &&
mkdir file-handle-demo &&
cd file-handle-demo &&
touch yarn.lock
)
新しい file-handle-demo フォルダーでターミナルを開き、以下の四つのファイルをそこに保存します。ローカルの yarn.lock により、既存のワークスペース内でも独立した Yarn プロジェクトになります。フォルダー作成後にセットアップが停止した場合は、そのフォルダーを残し、空のロックファイルをその中に作成してから続けてください。置き換えるのはこの新しいデモのファイルだけにし、既存アプリの設定は置き換えないでください。
次の内容を package.json として保存します。
{
"name": "file-handle-demo",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"build": "vite build",
"start": "vite preview --host 127.0.0.1 --port 4173 --strictPort"
},
"dependencies": {
"idb-keyval": "6.3.0"
},
"devDependencies": {
"vite": "8.3.2"
}
}
次の内容を .yarnrc.yml として保存し、ローカルにインストールした node_modules を使います。ignorePath は、親プロジェクトの yarnPath による上書きで、Corepack が選んだ Yarn のバージョンが置き換わるのを防ぎます。
nodeLinker: node-modules
ignorePath: true
次の内容を index.html として保存します。すべてのファイル操作コントロールは、初期化が完了するまで無効です。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Persistent file demo</title>
<style>
:root { color-scheme: light dark; font: 18px system-ui; }
main { max-width: 44rem; margin: 2rem auto; padding: 1rem; }
button, input { font: inherit; margin: .5rem 0; }
pre { white-space: pre-wrap; overflow-wrap: anywhere; }
</style>
</head>
<body>
<main>
<h1>Persistent file demo</h1>
<button id="choose" disabled>Choose file</button>
<button id="reopen" disabled>Reopen saved file</button>
<button id="forget" disabled>Forget saved file</button>
<p id="fallback" hidden>
<label for="file">Select file for this visit</label>
<input id="file" type="file" disabled />
</p>
<p id="status" role="status">Loading saved handle…</p>
<pre id="result" aria-label="File read result"></pre>
</main>
<script type="module" src="/main.ts"></script>
</body>
</html>
以下の二つの TypeScript ブロックを、順番どおりに
main.ts に保存します。型宣言はネイティブピッカーと権限メソッドを TypeScript に伝えるためのものです。機能の検出は引き続き実行時に行います。
import { del, get, set } from 'idb-keyval'
type NativeFileHandle = FileSystemFileHandle & {
requestPermission(options: { mode: 'read' }): Promise<PermissionState>
}
declare global {
interface Window {
showOpenFilePicker?: (options: { multiple: false }) => Promise<NativeFileHandle[]>
}
}
function element<T extends HTMLElement>(id: string, kind: new () => T): T {
const value = document.getElementById(id)
if (!(value instanceof kind)) throw new Error(`Missing control: ${id}`)
return value
}
const choose = element('choose', HTMLButtonElement)
const reopen = element('reopen', HTMLButtonElement)
const forget = element('forget', HTMLButtonElement)
const input = element('file', HTMLInputElement)
const status = element('status', HTMLParagraphElement)
const result = element('result', HTMLPreElement)
const native = typeof window.showOpenFilePicker === 'function'
const key = 'selected-upload-file'
let savedHandle: NativeFileHandle | null = null
let ready = false
let busy = false
function controls(): void {
choose.hidden = !native
element('fallback', HTMLParagraphElement).hidden = native
choose.disabled = !ready || busy
input.disabled = !ready || busy
reopen.disabled = !ready || busy || !native || savedHandle === null
forget.disabled = !ready || busy || savedHandle === null
}
function failure(error: unknown): void {
const name = error instanceof Error ? error.name : ''
const messages: Record<string, string> = {
AbortError: 'Selection canceled. Previous saved file kept.',
NotAllowedError: 'Access not granted. Allow access or choose the file again.',
SecurityError: 'Use a secure page and click a file control to request access.',
NotFoundError: 'File unavailable. It may have moved or been deleted. Choose it again.',
}
status.textContent = messages[name] ?? 'Operation failed. Check storage access and try again.'
}
async function operation(work: () => Promise<void>): Promise<void> {
if (!ready || busy) return
busy = true
result.textContent = ''
status.textContent = 'Reading…'
controls()
try {
await work()
} catch (error) {
failure(error)
} finally {
busy = false
controls()
}
}
async function handleLargeFile(
fileHandle: Pick<FileSystemFileHandle, 'getFile'>,
consumeChunk: (chunk: Uint8Array) => Promise<void>,
): Promise<number> {
const file = await fileHandle.getFile()
const reader = file.stream().getReader()
let totalSize = 0
try {
while (true) {
const { done, value } = await reader.read()
if (done) break
await consumeChunk(value)
totalSize += value.length
}
return totalSize
} catch (error) {
await reader.cancel(error).catch(() => {})
throw error
} finally {
reader.releaseLock()
}
}
async function readFile(handle: Pick<FileSystemFileHandle, 'getFile'>): Promise<string> {
let prefix: number[] = []
const bytes = await handleLargeFile(handle, async (chunk) => {
const remaining = 16 - prefix.length
if (remaining > 0) prefix = prefix.concat(Array.from(chunk.subarray(0, remaining)))
})
const hex = prefix.map((byte) => byte.toString(16).padStart(2, '0')).join(' ')
return `${bytes} bytes read. First 16 bytes (hex): ${hex || '(empty file)'}`
}
再度開くハンドラーは、起動時に読み込んだハンドルを使い、クリック処理中に即座に
requestPermission を呼び出します。権限を要求する前に IndexedDB を待つことはありません。保存したハンドルは権限より長く存続する場合があるため、許可されていない応答では読み取りを停止します。
choose.addEventListener('click', () => {
void operation(async () => {
const picker = window.showOpenFilePicker
if (!picker) throw new Error('Native picker unavailable')
const [handle] = await picker.call(window, { multiple: false })
if (!handle) throw new Error('No file selected')
const summary = await readFile(handle)
status.textContent = 'Saving handle…'
await set(key, handle)
savedHandle = handle
result.textContent = summary
status.textContent = `Read ${handle.name}. Handle saved; reload and reopen it.`
})
})
reopen.addEventListener('click', () => {
void operation(async () => {
if (savedHandle === null) throw new Error('No saved handle')
const permission = await savedHandle.requestPermission({ mode: 'read' })
if (permission !== 'granted') {
throw new DOMException('Access not granted', 'NotAllowedError')
}
const summary = await readFile(savedHandle)
result.textContent = summary
status.textContent = `Reopened ${savedHandle.name}.`
})
})
forget.addEventListener('click', () => {
void operation(async () => {
await del(key)
savedHandle = null
status.textContent = 'Saved handle forgotten. Choose a file to start again.'
})
})
input.addEventListener('click', () => { input.value = '' })
input.addEventListener('cancel', () => {
result.textContent = ''
status.textContent = 'Selection canceled. Select a file when ready.'
})
input.addEventListener('change', () => {
const file = input.files?.[0]
if (!file) return
void operation(async () => {
const summary = await readFile({ getFile: async () => file })
result.textContent = summary
status.textContent = `Read ${file.name} for this visit. Select it again after reload.`
})
})
async function initialize(): Promise<void> {
try {
if (native) savedHandle = (await get<NativeFileHandle>(key)) ?? null
status.textContent = native
? savedHandle === null ? 'Choose a file to start.' : 'Saved handle loaded. Click Reopen saved file.'
: 'Native reopen unavailable. Select a file for this visit.'
} catch {
status.textContent = 'Saved handle could not be loaded. Choose a file to retry storage.'
} finally {
ready = true
controls()
}
}
void initialize()
そのフォルダーでインストールとビルドを実行し、プレビューを起動します。&& で連結したコマンドは、インストールまたはビルドが失敗すると停止します。インストールが失敗した場合は、報告された問題を修正してこのコマンドを再実行してください。ソースファイルと既存のロックファイルは残します。フォアグラウンドのサーバーは Ctrl+C で停止します。
corepack yarn install && corepack yarn build && corepack yarn start
この演習では、終始同じブラウザープロファイルで http://127.0.0.1:4173/ を開きます。ポートを厳密に固定する設定により、オリジンを黙って変更せず、競合を報告します。競合するサービスを停止するか、package.json で別のポートを選んで再ビルドしてください。新しいオリジンでは、保存済みハンドルも別管理になります。
ファイルを再度開く操作とアクセス権限の再取得
テスト用の hello.txt を作成し、末尾に改行を付けず、内容を正確に hello とします。Choose file をクリックし、システムの選択画面でそのファイルを選びます。結果には 5 bytes read. First 16 bytes (hex): 68 65 6c 6c 6f と表示されるはずです。ページを再読み込みし、Reopen saved file をクリックします。ブラウザーに求められた場合は読み取りを許可します。読み取りが完了した後にのみ、ステータスが
Reopened hello.txt. になります。
ブラウザーの外でテスト用ファイルを編集し、再度開いて現在の内容を読み取ります。ハンドルはファイルを識別するもので、元のバイト列を固定するものではありません。ブラウザーを閉じて再起動すると、再び許可が必要になる場合があります。サイトのストレージを消去すると、保存したハンドルは削除されます。Chrome の永続的な権限のオプションがあっても、このデモで永続的なアクセス権限が必須になるわけではありません。
権限の再取得を試すには、ブラウザーを閉じて再起動し、再度開くボタンをクリックして、読み取り権限の要求を拒否します。再読み込みの前に、ブラウザーのサイト設定でファイルへのアクセス権限を削除することもできます。要求を拒否するか閉じると、読み取りは成功しません。テストした Chromium バージョンでは、拒否した読み取り要求が
prompt を返し、denied を返さない場合があります。この例では、どちらの場合も処理を停止します。ページは前の結果を消去し、Access not granted. Allow access or choose the file again. と表示します。後でクリックした際にアクセスを許可するか、ファイルを選び直してください。保存したハンドルで、その選択を回避することはできません。
テスト用ファイルを移動または削除すると、ハンドルが無効になる場合があります。その状態で再度開くと、File unavailable. It may have moved or been deleted. Choose it again. と表示されます。選択画面をキャンセルすると、前の保存済みハンドルは保持されますが、表示中の読み取り結果は消去されます。Forget saved file は、ディスク上のファイルを削除も変更もせず、IndexedDB のエントリを削除します。各操作中はファイル操作コントロールを無効に保ち、連続クリックによる読み取りの重複実行やステータスの上書きを防ぎます。
セキュリティ上の考慮事項
ネイティブピッカーにはセキュアコンテキストとユーザー操作が必要です。ループバック URL はローカルで機能しますが、デプロイしたアプリを配信する際は HTTPS を使ってください。スキーム、ホスト、ポートのいずれかが異なれば別のオリジンになるため、このアプリの IndexedDB エントリを再利用するには、まったく同じ URL に戻ります。
IndexedDB はネイティブハンドルを保存できます。保存には構造化クローンを使います。JSON と localStorage では、ハンドルの機能を保持できません。このデモは読み取り権限のみを要求し、選択したファイルへの書き込みは一切行いません。保存したハンドルはバックアップではなく、以前開始したアップロードとファイルが今も一致する証拠でもありません。転送を再開する前に、同じファイルであることを検証してください。
大容量ファイルの処理
このデモは各ストリームチャンクを処理してから次を要求し、16 バイトのプレビューだけを保持します。ファイル全体の Blob を組み立てたり、処理に arrayBuffer() を使ったりしません。これで上限が定まるのはデモが保持するプレビューであり、ブラウザー内部のバッファリングやプロセス全体のメモリではありません。空のファイルも、0 バイトの読み取り成功として扱います。アップロード側の処理では、consumeChunk 内で実際のチャンクの受領確認を待ってください。ハンドルだけでは、再試行や再開の動作は提供されません。
ディレクトリ走査とドラッグ&ドロップによる選択には、それぞれ専用のエントリーポイントと権限処理が必要です。これらは、単一ファイルを再度開くこの例の対象外です。それらの経路を追加する際も、起動時、処理中、失敗時の動作は維持してください。再度開いたファイルを転送する場合、tus は再開可能なアップロードプロトコルを提供します。アップロードの状態は、ローカルハンドルとは別に永続化してください。
