Navigator: registerProtocolHandler() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

Navigator の registerProtocolHandler() メソッドで、ウェブサイトが特定の URL スキーム（プロトコルとも呼ばれる）を開いたり処理したりする機能を登録することを可能にします。

例えば、この API はウェブメールサイトで mailto: の URL を開かせたり、 VoIP サイトで tel: の URL を開かせたりします。

プロトコルハンドラーを登録するには、ウェブサイトが registerProtocolHandler() を呼び出し、登録するプロトコルとテンプレート URL を渡します。

ユーザーが登録されたプロトコルを使用するリンクを起動すると、ブラウザーはハンドラー登録時に指定された URL テンプレートに起動したリンクの href を挿入し、現在のページを生成された URL に移動します。

ブラウザーは、プロトコルが登録されたとき、またはユーザーがリンクを起動したときに、ページがプロトコルを処理することを許可するかどうかを確認するようユーザーに要求することがあります。

構文

registerProtocolHandler(scheme, url)

引数

scheme

サイトが扱いたいプロトコルのスキームが入った文字列です。

次のようなスキーム名のカスタムスキームにすることができます。

web+ で始まる
web+ 接頭辞の後に 1 文字以上ある
小文字の ASCII 文字のみが含まれている

それ以外の場合はスキームは以下のいずれかでなければなりません。

bitcoin
ftp
ftps
geo
im
irc
ircs
magnet
mailto
matrix
mms
news
nntp
openpgp4fpr
sftp
sip
sms
smsto
ssh
tel
urn
webcal
wtai
xmpp

url

ハンドラーの URL を指定する文字列。この URL には %s を含める必要があり、これは取り扱う URL をエスケープしたもので置き換得られるプレイスホルダーとして扱われます。

ハンドラーの URL は https スキームを使用する必要があり、ハンドラーを登録しようとするウェブページと同じオリジンでなければなりません。

返値

なし (undefined)。

例外

SecurityError DOMException

ユーザーエージェントが登録をブロックしました。以下のような場合に起こる可能性があります。

ブラウザーが自身が処理するスキーム（https:, about:, など）であるなど、登録されているスキーム（プロトコル）が無効である場合。
ハンドラーの URL のオリジンが、本 API を呼び出すページのオリジンと一致しない場合。
ブラウザーが、この関数を安全なコンテキストから呼び出すことを要求している場合。
ブラウザーが、ハンドラーの URL が HTTPS であることを要求している場合。

SyntaxError DOMException

%s が指定されたハンドラー URL に含まれていない場合。

例

mailto プロトコルのハンドラーを登録する

ウェブページが、https 以外のプロトコルを使用してリソースにリンクすることはよくあります。例えば、mailto: プロトコルなどです。ウェブ制作者は、ユーザーがウェブページから直接電子メールを送信できる便利な方法を提供したい場合に、mailto リンクを使用することができます。

html

<a href="mailto:webmaster@example.com">ウェブマスター</a>

リンクが有効になると、ブラウザーが既定のデスクトップアプリケーションを起動してメールを処理します。この処理を、デスクトップベースのプロトコルハンドラーと考えることができます。

ウェブベースのプロトコルハンドラーを使用すると、ウェブベースのアプリケーションも処理に参加できます。例えば、mail.example.org のウェブメールアプリは、次のようなコードで mailto リンクを処理するように登録できます。

navigator.registerProtocolHandler("mailto", "https://mail.example.org/?to=%s");

この後、ユーザーが任意のウェブサイト上の mailto リンクをクリックすると、ブラウザーは(確認を依頼するメッセージを表示するなどして) https://mail.example.org/?to=mailto:webmaster@example.com に移動します。このページでは、URL の引数を解釈してアドレスを抽出し、それをメールの初期化に使用することができます。

カスタムプロトコルのハンドラーを登録する

この例では、ページが web+burger プロトコルのハンドラーを次のようなコードで登録します。

navigator.registerProtocolHandler(
  "web+burger",
  "https://burgers.example.org/?burger=%s",
);

その後、ユーザーはこのようなリンクが格納されたページにアクセスします。

html

<a href="web+burger:cheeseburger">cheeseburger</a>

ユーザーが web+burger リンクを起動すると、ブラウザーは（ユーザーに確認を要求した後） https://burgers.example.org/?burger=web+burger:cheeseburger に移動します。

仕様書

Specification
HTML Standard # custom-handlers

ブラウザーの互換性

BCD tables only load in the browser