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

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

Thomas Steiner

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

File Handling API のユースケースの例

この API を使用するサイトの例:

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

File Handling API の使用方法

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

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

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

ブラウザサポート

Browser Support

Source

特徴検出

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" です。ユーザーが複数のファイルを開き、ファイルハンドラが "launch_type" として "multiple-clients" でアノテーションされている場合、アプリの起動が複数回行われ、起動ごとに 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 つのクライアントで開き、最後の 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 ウィンドウ。 — オペレーティングシステムのエクスプローラでファイルをダブルクリックするか、右クリックします。

[Open with… Excalidraw] 項目がハイライト表示された状態でファイルを右クリックしたときに表示されるコンテキストメニュー。 — Excalidraw は `.excalidraw` ファイルのデフォルトのファイルハンドラです。

セキュリティ

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

権限、権限の永続性、ファイルハンドラの更新

ユーザーの信頼とユーザーのファイルの安全性を確保するため、File Handling API でファイルを開くとき、PWA がファイルを表示する前に権限のプロンプトが表示されます。この権限プロンプトは、ユーザーがファイルを開く PWA を選択した直後に表示されます。これにより、権限が PWA を使用してファイルを開くアクションと密接に結び付けられ、より理解しやすく関連性の高いものになります。

この権限は、ユーザーがサイトのファイル処理を [許可] または [ブロック] をクリックするか、プロンプトを 3 回無視するまで毎回表示されます（3 回無視すると、Chromium はこの権限を禁止してブロックします）。選択した設定は、PWA を閉じて再度開いても保持されます。

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

ファイル関連の課題

ウェブサイトがファイルにアクセスできるようにすることで、攻撃ベクトルが大幅に増加します。これらについては、File System Access API に関する記事で説明しています。File Handling API が File System Access API よりもセキュリティ関連で優れている点は、ウェブアプリケーションによって表示されるファイル選択ツールではなく、オペレーティングシステムの組み込み UI を通じて特定のファイルへのアクセスを許可できることです。

ユーザーがファイルを開くことで、ウェブアプリケーションに誤ってアクセス権を付与してしまうリスクは残ります。ただし、一般的には、ファイルを開くと、そのファイルを開いたアプリケーションがそのファイルを読み取ったり操作したりできるようになると考えられています。したがって、ユーザーがインストール済みのアプリでファイルを開くことを明示的に選択した場合（「...で開く」コンテキストメニューなど）、そのアプリに対する信頼の十分なシグナルと見なすことができます。

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

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

ユーザーコントロール

仕様では、ファイルを処理できるすべてのサイトをファイルハンドラとして登録すべきではないと規定されています。代わりに、ファイル処理の登録はインストール後に制限されるべきであり、特にサイトがデフォルトのハンドラになる場合は、ユーザーの明示的な確認なしに行われるべきではありません。ユーザーがすでにデフォルトのハンドラを登録している可能性が高い .json などの既存の拡張機能をハイジャックするのではなく、サイトは独自の拡張機能の作成を検討する必要があります。

透明性

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

フィードバック

Chrome チームは、ファイル処理 API の使用感について皆様のご意見をお待ちしています。

API 設計について教えてください

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

対応する GitHub リポジトリで仕様に関する問題を提出するか、既存の問題にご意見を追加してください。

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

Chrome の実装にバグが見つかりましたか？それとも、実装が仕様と異なるのでしょうか？

new.crbug.com でバグを報告します。できるだけ多くの詳細情報と、再現するための簡単な手順を記載し、[Components] ボックスに UI>Browser>WebAppInstalls>FileHandling と入力してください。

API のサポートを表示する

File Handling API を使用する予定はありますか？公開サポートは、Chrome チームが機能の優先順位を決定するのに役立ち、他のブラウザベンダーにサポートの重要性を示すことができます。

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

謝辞

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