インストール済みのウェブ アプリケーションをファイル ハンドラとして指定する

アプリをオペレーティング システムにファイル ハンドラとして登録します。

ウェブアプリがファイルの読み取りと書き込みが可能になったので、次は、デベロッパーがアプリが作成して処理できるファイルのファイル ハンドラとして、これらのウェブアプリを宣言できるようにすることが理にかなっています。File Handling API を使用すると、まさにこのことができます。テキスト エディタ アプリをファイル ハンドラとして登録してインストールしたら、macOS で .txt ファイルを右クリックし、[情報] を選択して、このアプリで .txt ファイルを常にデフォルトとして開くように OS に指示できます。

この API を使用するサイトの例を次に示します。

  • テキスト エディタ、スプレッドシート アプリ、スライドショー作成ツールなどの Office アプリケーション。
  • グラフィック エディタと描画ツール。
  • ビデオゲームのレベル エディタ ツール。

File Handling API の使用方法

プログレッシブ エンハンスメント

File Handling API 自体はポリフィルできません。ただし、ウェブアプリでファイルを開く機能は、次の 2 つの方法で実現できます。

  • Web Share Target API を使用すると、デベロッパーは自分のアプリを共有ターゲットとして指定し、オペレーティング システムの共有シートからファイルを開くことができます。
  • File System Access API はファイルのドラッグ&ドロップと統合できるため、デベロッパーはすでに開いているアプリでドロップされたファイルを処理できます。

ブラウザ サポート

対応ブラウザ

  • Chrome: 102。
  • Edge: 102.
  • Firefox: サポートされていません。
  • Safari: サポートされていません。

ソース

特徴検出

File Handling API がサポートされているかどうかを確認するには、次のコマンドを使用します。

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
 
// The File Handling API is supported.
}

File Handling API の宣言型部分

最初のステップとして、ウェブアプリは処理できるファイルの種類をウェブアプリ マニフェストに宣言的に記述する必要があります。File Handling API は、ウェブアプリ マニフェストを拡張し、ファイル ハンドラの配列を受け入れる "file_handlers" という新しいプロパティを追加します。ファイル ハンドラは、次のプロパティを持つオブジェクトです。

  • アプリのスコープ内の URL を指す "action" プロパティ(値として)。
  • MIME タイプのオブジェクトをキーとして、ファイル拡張子のリストを値として持つ "accept" プロパティ。
  • ImageResource アイコンの配列を含む "icons" プロパティ。一部のオペレーティング システムでは、ファイル形式の関連付けによって、関連付けられたアプリケーション アイコンだけでなく、そのファイル形式をアプリケーションで使用する際に関連する特別なアイコンを表示できます。
  • 複数のファイルを 1 つのクライアントで開くか、複数のクライアントで開くかを定義する "launch_type" プロパティ。デフォルトは "single-client" です。ユーザーが複数のファイルを開き、ファイル ハンドラに "multiple-clients""launch_type" としてアノテーションされている場合、複数のアプリが起動されます。起動ごとに、LaunchParams.files 配列(下記を参照)に要素が 1 つだけ含まれます。

ウェブアプリ マニフェストの関連部分のみを示す次の例を見ると、より明確に理解できるでしょう。

{
 
"file_handlers": [
   
{
     
"action": "/open-csv",
     
"accept": {
       
"text/csv": [".csv"]
     
},
     
"icons": [
       
{
         
"src": "csv-icon.png",
         
"sizes": "256x256",
         
"type": "image/png"
       
}
     
],
     
"launch_type": "single-client"
   
},
   
{
     
"action": "/open-svg",
     
"accept": {
       
"image/svg+xml": ".svg"
     
},
     
"icons": [
       
{
         
"src": "svg-icon.png",
         
"sizes": "256x256",
         
"type": "image/png"
       
}
     
],
     
"launch_type": "single-client"
   
},
   
{
     
"action": "/open-graf",
     
"accept": {
       
"application/vnd.grafr.graph": [".grafr", ".graf"],
       
"application/vnd.alternative-graph-app.graph": ".graph"
     
},
     
"icons": [
       
{
         
"src": "graf-icon.png",
         
"sizes": "256x256",
         
"type": "image/png"
       
}
     
],
     
"launch_type": "multiple-clients"
   
}
 
]
}

これは、/open-csv のカンマ区切り値(.csv)ファイル、/open-svg のスケーラブル ベクター グラフィック(.svg)ファイル、/open-graf の拡張子が .grafr.graf.graph のいずれかである架空の Grafr ファイル形式を処理する仮想のアプリを対象としています。最初の 2 つは 1 つのクライアントで開き、複数のファイルが処理されている場合は最後のクライアントで開きます。

File Handling API の命令型部分

アプリは理論上、どのスコープ内 URL で処理できるかを宣言したので、実際には受信ファイルに対して命令的になんらかの処理を行う必要があります。ここで launchQueue の出番です。起動されたファイルにアクセスするには、サイトが window.launchQueue オブジェクトのコンシューマを指定する必要があります。起動は、指定されたコンシューマによって処理されるまでキューに追加されます。コンシューマは起動ごとに 1 回だけ呼び出されます。このようにして、コンシューマが指定されたタイミングに関係なく、すべての起動が処理されます。

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue
.setConsumer((launchParams) => {
   
// Nothing to do when the queue is empty.
   
if (!launchParams.files.length) {
     
return;
   
}
   
for (const fileHandle of launchParams.files) {
     
// Handle the file.
   
}
 
});
}

DevTools のサポート

このドキュメントの執筆時点では DevTools はサポートされていませんが、サポートを追加する機能リクエストを提出しました。

デモ

マンガ風の描画アプリである Excalidraw にファイル処理のサポートを追加しました。テストするには、まず Excalidraw をインストールする必要があります。このファイルでファイルを作成してファイル システム上のどこかに保存すると、ファイルをダブルクリックするか右クリックして開き、コンテキスト メニューで [Excalidraw] を選択します。ソースコードで実装を確認できます。

Excalidraw ファイルを含む macOS の Finder ウィンドウ。
オペレーティング システムのファイル エクスプローラで、ファイルをダブルクリックするか右クリックします。
Excalidraw の項目がハイライト表示された状態でファイルを右クリックすると表示されるコンテキスト メニュー。
Excalidraw は、.excalidraw ファイルのデフォルト ファイル ハンドラです。

セキュリティ

Chrome チームは、強力なウェブ プラットフォーム機能へのアクセスを制御するで定義されているコア プリンシプル(ユーザー制御、透明性、人間工学など)を使用して、File Handling API を設計して実装しました。

権限、権限の保持、ファイル ハンドラの更新

ユーザーの信頼とユーザーのファイルの安全を確保するため、File Handling API がファイルを開くときに、PWA がファイルを表示する前に権限プロンプトが表示されます。この権限プロンプトは、ユーザーが PWA を選択してファイルを開く直後に表示されるため、権限と PWA を使用してファイルを開く操作が密接に結びついており、よりわかりやすく関連性のあるものとなっています。

この権限は、ユーザーがサイトのファイル処理を許可またはブロックするようにクリックするか、プロンプトを 3 回無視するまで、毎回表示されます(その後、Chromium はこの権限を制限してブロックします)。選択した設定は、PWA の閉じた後、再び開いたときにも保持されます。

マニフェストの更新と "file_handlers" セクションの変更が検出されると、権限がリセットされます。

ウェブサイトにファイルへのアクセスを許可することで開かれる攻撃ベクトルは、大まかに次の 2 つに分類できます。これらの要件については、File System Access API に関する記事をご覧ください。File Handling API が File System Access API よりもセキュリティに関連する追加機能として提供する機能は、ウェブアプリによって表示されるファイル選択ツールではなく、オペレーティング システムの組み込み UI を介して特定のファイルへのアクセスを許可する機能です。

ただし、ファイルを開いたときに、意図せずにウェブ アプリケーションにそのファイルへのアクセス権を付与するリスクがあります。ただし、ファイルを開くと、そのファイルを開いたアプリがそのファイルを読み取ったり操作したりできることは一般的に理解されています。したがって、[アプリで開く] コンテキスト メニューなど、インストール済みアプリでファイルを開くことをユーザーが明示的に選択した場合は、アプリを信頼できることを示す十分なシグナルとみなすことができます。

デフォルト ハンドラの課題

ただし、特定のファイル形式に対応するアプリケーションがホストシステムにない場合は例外です。この場合、一部のホスト オペレーティング システムでは、ユーザーによる操作なしで、新しく登録されたハンドラがそのファイルタイプのデフォルト ハンドラに自動的に昇格されることがあります。つまり、ユーザーがそのタイプのファイルをダブルクリックすると、登録されたウェブアプリで自動的に開きます。このようなホスト オペレーティング システムでは、ユーザー エージェントがファイル形式のデフォルト ハンドラが存在しないことを判断した場合、ユーザーの同意なしにファイルの内容がウェブ アプリケーションに誤って送信されないように、明示的な権限プロンプトが必要になることがあります。

ユーザー コントロール

この仕様には、ブラウザがファイルを処理できるすべてのサイトをファイル ハンドラとして登録すべきではないと規定されています。代わりに、ファイル処理の登録はインストールの背後に設定し、特にサイトがデフォルトのハンドラになる場合は、ユーザーの明示的な確認なしに登録が行われないようにする必要があります。ユーザーがすでにデフォルト ハンドラを登録済みであると思われる .json のような既存の拡張機能を乗っ取るのではなく、サイトで独自の拡張機能を作成することを検討する必要があります。

透明性

どのオペレーティング システムでも、ユーザーは現在のファイルの関連付けを変更できます。これはブラウザの対象外です。

フィードバック

Chrome チームで File Handling API の使用経験についてお聞かせください。

API 設計について

API が想定どおりに動作しない点はありますか?または、アイデアを実装するために必要なメソッドやプロパティが不足している場合はどうすればよいですか?セキュリティ モデルに関する質問やコメントがある場合

  • 対応する GitHub リポジトリで仕様に関する問題を報告するか、既存の問題にコメントを追加します。

実装に関する問題を報告する

Chrome の実装にバグが見つかりましたか?または、実装が仕様と異なっていますか?

  • new.crbug.com でバグを報告します。できるだけ詳細な情報を含め、再現手順を簡潔に記述してください。[コンポーネント] ボックスに UI>Browser>WebAppInstalls>FileHandling を入力します。Glitch は、簡単な再現をすばやく共有するのに適しています。

API のサポートを表示する

File Handling API を使用する予定はありますか?一般公開されている機能へのサポートは、Chrome チームが機能の優先順位を決める際に役立ちます。また、他のブラウザ ベンダーに、その機能のサポートがどれほど重要であるかを示します。

  • WICG Discourse スレッドで、どのように使用する予定かをお知らせください。
  • ハッシュタグ #FileHandling を使用して @ChromiumDev にツイートを送信し、どこでどのように使用しているかをお知らせください。

関連情報

謝辞

File Handling API は、Eric WilligersJay HarrisRaymes Khoury によって指定されました。この記事は、Joe Medley によってレビューされました。