Web Components のアクセシブルなファイルアップロードウィジェット
カスタム要素内のネイティブボタンとファイル入力でファイルをひとつ選択し、その File オブジェクトをアプリケーションに渡します。このファイルアップロードウィジェットはスタイルを Shadow DOM 内に保持し、10 MiB のサイズ制限を検証して、ステータス領域に選択結果を表示します。アップロードはホストアプリケーションが処理します。このサンプルはネットワークリクエストを行いません。
ファイルアップロードウィジェットに Web Components を使う理由は?
UI フレームワークを共有せずに複数のアプリケーションで同じ選択コントロールを使う場合は、カスタム要素を選びます。Shadow DOM で内部のスタイルを分離し、DOM イベントでホストに小さなインターフェースを提供できます。ひとつのフォームでスタイル付きの入力が必要なだけなら、ネイティブのファイル入力のほうがシンプルです。
Web Components の構造の準備
Custom Elements と Shadow DOM に対応したブラウザー、テキストエディター、ローカルのテストファイルが必要です。このプレーン HTML のデモには、パッケージマネージャー、サーバー、ビルド工程は不要です。キーボードとファイル選択ダイアログの動作は、Linux 上の Chromium 145 でテストしました。公開前に、利用者が使うブラウザーと支援技術の組み合わせでテストしてください。
エディターで新しいディレクトリを作成します。以下のコンポーネント全体を、その中に file-upload-widget.js として保存してください。
class FileUploadWidget extends HTMLElement {
static observedAttributes = ['disabled'];
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.render();
this.addEventListeners();
this.ready = true;
}
connectedCallback() {
this.syncDisabled();
}
attributeChangedCallback() {
this.syncDisabled();
}
syncDisabled() {
const disabled = this.hasAttribute('disabled');
this.shadowRoot.querySelector('button').disabled = disabled;
this.shadowRoot.querySelector('input').disabled = disabled;
}
render() {
this.shadowRoot.innerHTML = `
<style>
:host {
display: block;
border: 2px dashed var(--border-color, #ccc);
padding: 20px;
text-align: center;
color-scheme: light dark;
background-color: Canvas;
color: CanvasText;
}
:host([hidden]) { display: none; }
button:focus-visible {
outline: 2px solid Highlight;
outline-offset: 4px;
}
button:disabled {
cursor: not-allowed;
opacity: 0.6;
}
button {
max-width: 100%;
white-space: normal;
padding: 12px;
}
.file-info {
margin-top: 10px;
font-size: 0.9em;
overflow-wrap: anywhere;
}
</style>
<input type="file" id="fileInput" hidden />
<button type="button" aria-describedby="fileHint">Choose a file</button>
<p id="fileHint">Maximum file size: 10 MiB.</p>
<p class="file-info" id="fileInfo" role="status" aria-atomic="true"></p>
`;
}
addEventListeners() {
const fileInput = this.shadowRoot.querySelector('#fileInput');
const fileInfo = this.shadowRoot.querySelector('#fileInfo');
this.shadowRoot.querySelector('button').addEventListener('click', () => fileInput.click());
fileInput.addEventListener('change', () => {
if (this.hasAttribute('disabled')) {
fileInput.value = '';
return;
}
const file = fileInput.files[0];
if (file) {
if (file.size > 10 * 1024 * 1024) {
fileInfo.textContent = 'File too large (max 10 MiB). Please select another file.';
fileInput.value = ''; // Clear the invalid selection
return;
}
fileInfo.textContent = `Selected file: ${file.name}`;
this.dispatchEvent(new CustomEvent('file-selected', {
detail: { file },
bubbles: true,
composed: true
}));
fileInput.value = ''; // Allow the same file to be selected again.
} else {
fileInfo.textContent = '';
}
});
}
}
customElements.define('file-upload-widget', FileUploadWidget);
コンストラクターはシャドウツリーを構築し、リスナーを一度だけ登録します。接続コールバックは無効状態の同期だけを行うため、同じ要素を削除して再接続しても、リスナーを追加せずにフィードバックを保持します。監視対象の属性は、後からの変更にも対応します。MDN のカスタム要素のライフサイクルのドキュメントを参照してください。
次のページを同じディレクトリに index.html として保存します。
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Web component file selection</title>
<script src="file-upload-widget.js" defer></script>
<script src="demo.js" defer></script>
</head>
<body>
<main>
<h1>Select one file</h1>
<p id="basic-picker">
<label for="basic-file">Choose a file</label>
<input type="file" id="basic-file" name="file" />
</p>
<file-upload-widget id="picker" hidden></file-upload-widget>
<p id="received">No file received by the host.</p>
<noscript><p>The basic input selects a file; this demo does not upload it.</p></noscript>
</main>
</body>
</html>
受信側のコードを demo.js として保存します。
const widget = document.querySelector('#picker');
const basicPicker = document.querySelector('#basic-picker');
const received = document.querySelector('#received');
widget.addEventListener('file-selected', (event) => {
const { file } = event.detail;
window.selectedFile = file;
received.textContent = `Host received: ${file.name} (${file.size} bytes).`;
});
// Keep the basic input available if the component failed to load or initialize.
if (widget.ready === true) {
basicPicker.hidden = true;
widget.hidden = false;
}
ブラウザーで index.html を開きます。Tab キーで Choose a file に移動し、Enter キーまたは Space キーでネイティブの選択ダイアログを開いてください。10 MiB 以下のファイルを選択します。ウィジェットには
Selected file: に続いてファイル名が表示され、ホストには Host received: に続いて名前とバイト数が表示されます。window.selectedFile は、ホストで使用する実際の File を保持します。
キーボードナビゲーションとフォーカス管理の実装
ネイティブボタンは Enter キーと Space キーに対応するため、独自の keydown ハンドラーやボタンロールは不要です。クリックすると、ユーザーアクティベーション中に非表示の入力が開きます。可視のフォーカス枠を維持し、ファイルの選択後やダイアログのキャンセル後に、フォーカスがボタンに戻ることを確認してください。WAI のボタンパターンで、期待されるキーボード動作を説明しています。
disabled ブール属性を file-upload-widget に追加すると、両方のネイティブコントロールが無効になります。再度有効にするには属性を削除してください。disabled="false" でも属性が存在するため、要素は無効のままです。アプリケーションが現在フォーカスされているコントロールを無効化または削除する場合は、ホスト内に残っている適切なコントロールにフォーカスを移してください。ノードを再接続するだけでは、失われたフォーカスは復元されません。
スクリーンリーダー対応のための ARIA 属性の追加
ボタンの可視テキストがアクセシブルな名前になります。aria-describedby="fileHint" は、同じシャドウルート内のサイズ制限の説明を関連付けます。別に設けた、初期状態では空の
role="status" 領域は、polite なライブリージョンのセマンティクスを持ちます。aria-atomic="true" は、更新後のメッセージ全体の通知を要求します。テキストを更新しても、フォーカスはステータスに移動しません。
これらのセマンティクスは支援技術に対応するものですが、可視のフィードバックやアクセシビリティツリーがあっても、音声通知が行われる証明にはなりません。テストした Linux の Orca 46.1/Chromium 145 の組み合わせでは、ネイティブの選択ダイアログから戻った後、選択結果の自動読み上げが行われない場合がありました。同じファイルを再選択した場合もテキストが同一になるため、スクリーンリーダーが再度読み上げないことがあります。フィードバックを可視のまま維持し、対象の組み合わせで以下のスクリーンリーダーテストを行ってください。
ファイル選択と検証の処理
change リスナーは、選択された File を読み取り、その名前を HTML ではなくテキストとして書き込み、受け入れた選択に対して
file-selected イベントをひとつ発行します。event.detail.file はファイルそのものであり、パスや再構築されたコピーではありません。イベントはバブリングし、composed でもあるため、別のシャドウルートの外にあるホストも受信できます。
制限は 10 × 1,024 × 1,024 バイトです。空のファイルと、制限以下のファイルを受け入れます。これを超えるファイルでは File too large (max 10 MiB). Please select another file. を表示し、選択イベントは発行しません。ホストが保持する前のファイルは変更しません。受け入れ、拒否、または無効状態での選択の無視の後には入力をクリアするため、再度有効にしてから同じファイルを選ぶと、イベントが再び発生する場合があります。選択ダイアログをキャンセルしても、新しい選択は発生しません。
クライアント側の検証はフィードバックを提供するためのものです。アップロードサーバー側でも独立してサイズと内容を検証し、認可とストレージクォータを適用する必要があります。このコンポーネントには、ドラッグ&ドロップ、アップロードの進行状況、フォーム送信の機能はありません。入力をクリアするため、このコンポーネントを囲むフォームも選択されたファイルを自動送信しません。ホストのアップロードコードで、イベントの File を使用してください。
CSS カスタムプロパティによるスタイルのカスタマイズ
コンポーネントの枠線には var(--border-color, #ccc) を使用しています。上書きするには、style 要素を
index.html の head 内に配置し、次のルールを記述します。シャドウツリー内をセレクターで指定せずに、コンポーネントに適用できます。
file-upload-widget {
--border-color: #007bff;
}
デモでは、color-scheme: light dark でシステムのキャンバス、テキスト、フォーカスの色を使用します。スタイルを追加する際は、独自のテーマのコントラストとフォーカスインジケーターを確認してください。長いファイル名は折り返されるため、コントロールがコンテナーの幅を超えることはありません。
プログレッシブエンハンスメントとフォールバックの戦略
初期 HTML ではラベル付きのネイティブ入力を表示し、拡張ウィジェットを非表示にします。コンストラクターが完了し、受信スクリプトの準備ができて初めて、demo.js が両者を切り替えます。JavaScript が無効な場合、どちらかのスクリプトのダウンロードに失敗した場合、またはコンポーネントの初期化に失敗した場合も、基本の入力を引き続き使用できます。これは noscript だけのフォールバックよりも広い範囲に対応します。
基本の入力はファイルを選択するだけで、サイズ検証、ホストイベントのハンドラー、アップロード先のエンドポイントはありません。JavaScript なしで送信する必要があるフォームでは、このネイティブ入力を実際の multipart フォームとサーバーに接続してください。代替手段で同じ処理を実行できるようになるまでは、この入力を非表示にしないでください。
スクリーンリーダーによるアクセシビリティのテスト
Windows の NVDA や JAWS、macOS の VoiceOver、Linux の Orca など、サポート対象のブラウザーとスクリーンリーダーの組み合わせでテストしてください。ここでの Linux 上の自動検証は、人によるスクリーンリーダーのユーザビリティ調査ではなく、あらゆる環境でのアクセシビリティを実証するものではありません。以下を確認してください。
- Tab キーで Choose a file に一度だけ移動し、フォーカスインジケーターが見えること
- Enter キーと Space キーで実際のファイル選択ダイアログが開き、選択後とキャンセル後にフォーカスがボタンに戻ること
- ボタンに名前、ボタンロール、サイズ制限の説明があること。説明の読み上げにスクリーンリーダーのヘルプコマンドが必要かどうかも含め、実際に読み上げられる内容の確認
- 新しいファイル名とサイズ超過のメッセージをスクリーンリーダーで読み取れること。繰り返し選択した場合も含め、フィードバックを手動で読む操作と自動通知を分けて確認
- コントロールの無効化と再有効化が機能すること。削除して再接続しても、イベントを重複させずにフィードバックを保持すること。フォーカス中のコントロールを削除する際は、ホスト側でフォーカスを復元すること
- JavaScript が無効な場合やコンポーネントのスクリプトが壊れている場合も、基本の入力でファイルを選択できること
フレームワークとの統合
アプリケーションをマウントする前に、ブラウザーで file-upload-widget.js を一度登録し、ホストで file-selected を受信して event.detail.file を読み取ります。サーバーレンダリングとアップロード通信はコンポーネントの外で処理してください。以下は既存のアプリへの統合ポイントであり、フレームワークごとの独立したプロジェクトの手順ではありません。
- React 19 のカスタム要素はプロパティとカスタムイベントハンドラーに対応しています。カスタムイベントをバインドする際は、イベント名のハイフンと大文字小文字を維持してください。または、ref 経由で DOM リスナーを登録し、ラッパーのアンマウント時に同じリスナーを削除してください。
- Vue では、
compilerOptions.isCustomElementを使い、Vue のビルド設定でこのタグをカスタム要素として指定します。app.config.compilerOptionsの設定は、ブラウザー内でのテンプレートコンパイルでのみ機能し、事前コンパイルされた単一ファイルコンポーネントでは機能しません。テンプレートのリスナーは DOM イベントを受信します。 - Angular の
CUSTOM_ELEMENTS_SCHEMAは、名前にハイフンを含むカスタム要素を許可します。利用側のスタンドアロンコンポーネントのschemasに追加するか、モジュールベースのアプリでは、宣言元 NgModule のschemasに追加してください。そのコンポーネントのテンプレートで DOM イベントをバインドし、アプリケーション内でイベントのFileを処理します。
ホストとアップロードサービスの接続
デモの受信ハンドラーをアプリケーションのアップロード処理に置き換え、アップロードの成功と失敗には、それぞれ専用のフィードバックを用意してください。ファイルの選択は、サーバーがそのファイルを受け入れた証拠にはなりません。Transloadit の /upload/handle Robot は、サーバー側でのファイル取り込みについての参考資料です。このローカルの選択デモに、そのまま差し込めるエンドポイントではありません。
