Navigator: registerProtocolHandler() Methode

Limited availability

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

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die Navigator Methode registerProtocolHandler() ermöglicht es Webseiten, ihre Fähigkeit zu registrieren, bestimmte URL-Schemata (auch bekannt als Protokolle) zu öffnen oder zu bearbeiten.

Diese API ermöglicht es beispielsweise Webmail-Seiten, mailto: URLs zu öffnen, oder VoIP-Seiten, tel: URLs zu öffnen.

Um einen Protokoll-Handler zu registrieren, ruft eine Webseite registerProtocolHandler() auf und übergibt das zu registrierende Protokoll und eine URL-Vorlage.

Wenn der Benutzer auf einen Link klickt, der das registrierte Protokoll verwendet, fügt der Browser den href des aktivierten Links in die URL-Vorlage ein, die bei der Handler-Registrierung bereitgestellt wurde, und navigiert die aktuelle Seite zur resultierenden URL.

Der Browser kann den Benutzer bitten zu bestätigen, dass die Seite berechtigt werden soll, das Protokoll zu bearbeiten, entweder wenn das Protokoll registriert wird oder wenn der Benutzer den Link aktiviert.

Syntax

js
registerProtocolHandler(scheme, url)

Parameter

scheme

Ein String, der das Schema für das Protokoll enthält, das die Seite handhaben möchte.

Dies kann ein benutzerdefiniertes Schema sein, in diesem Fall gilt für den Namen des Schemas:

  • Beginnt mit web+
  • Enthält mindestens einen Buchstaben nach dem web+ Präfix
  • Enthält nur Kleinbuchstaben des ASCII.

Andernfalls muss das Schema eines der folgenden sein:

  • 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

Ein String, der die URL des Handlers enthält. Diese URL muss %s als Platzhalter enthalten, der durch die escapte URL ersetzt wird, die bearbeitet werden soll.

Die Handler-URL muss das https Schema verwenden und muss aus dem gleichen Ursprung stammen wie die Webseite, die versucht, den Handler zu registrieren.

Rückgabewert

Keiner (undefined).

Ausnahmen

SecurityError DOMException

Die Registrierung wurde vom User Agent blockiert. Dies kann passieren, wenn:

  • Das registrierte Schema (Protokoll) ungültig ist, wie ein Schema, das der Browser selbst handhabt (https:, about:, etc.)
  • Der Ursprung der Handler-URL nicht mit dem Ursprung der Seite übereinstimmt, die diese API aufruft.
  • Das Schema der Handler-URL nicht https ist.
SyntaxError DOMException

Der %s Platzhalter fehlt in der Handler-URL.

Beispiele

Registrierung eines Handlers für das mailto-Protokoll

Es ist relativ häufig, dass Webseiten Links zu Ressourcen unter Verwendung von nicht-https Protokollen setzen. Ein Beispiel ist das mailto: Protokoll. Webseitenautoren können einen mailto Link verwenden, um Benutzern eine praktische Möglichkeit zu bieten, direkt von der Webseite aus eine E-Mail zu senden:

html
<a href="mailto:webmaster@example.com">Web Master</a>

Wird der Link aktiviert, sollte der Browser die Standard-Desktopanwendung für das Bearbeiten von E-Mails starten. Sie können dies als einen desktopbasierten Protokoll-Handler ansehen.

Webbasierte Protokoll-Handler erlauben es webbasierten Anwendungen ebenfalls, sich am Prozess zu beteiligen. Eine E-Mail-Web-App bei mail.example.org kann mit folgendem Code registriert werden, um mailto Links zu bearbeiten:

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

Anschließend wird der Browser (nachdem möglicherweise der Browser um Bestätigung gebeten wurde) zu https://mail.example.org/?to=mailto:webmaster@example.com navigieren, wenn der Benutzer auf einen mailto Link auf einer beliebigen Webseite klickt. Diese Seite könnte den URL-Parameter parsen, um die Adresse zu extrahieren und diese verwenden, um eine E-Mail zu initialisieren.

Registrierung eines Handlers für ein benutzerdefiniertes Protokoll

In diesem Beispiel registriert eine Seite einen Handler für das web+burger Protokoll mit folgendem Code:

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

Anschließend besucht der Benutzer eine Seite mit einem Link wie diesem:

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

Wenn der Benutzer auf den web+burger Link klickt, wird der Browser (nachdem möglicherweise der Benutzer um Bestätigung gebeten wurde) zu https://burgers.example.org/?burger=web+burger:cheeseburger navigieren.

Spezifikationen

Specification
HTML
# custom-handlers

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
registerProtocolHandler
scheme parameter supports bitcoin
scheme parameter supports cabal
ExperimentalNon-standard
scheme parameter supports dat
ExperimentalNon-standard
scheme parameter supports did
ExperimentalNon-standard
scheme parameter supports dweb
ExperimentalNon-standard
scheme parameter supports ethereum
ExperimentalNon-standard
scheme parameter supports ftp
Experimental
scheme parameter supports ftps
Experimental
scheme parameter supports geo
scheme parameter supports hyper
ExperimentalNon-standard
scheme parameter supports im
scheme parameter supports ipfs
ExperimentalNon-standard
scheme parameter supports ipns
ExperimentalNon-standard
scheme parameter supports irc
scheme parameter supports ircs
scheme parameter supports magnet
scheme parameter supports mailto
scheme parameter supports matrix
scheme parameter supports mms
scheme parameter supports news
scheme parameter supports nntp
scheme parameter supports openpgp4fpr
scheme parameter supports sftp
Experimental
scheme parameter supports sip
scheme parameter supports sms
scheme parameter supports smsto
scheme parameter supports ssb
ExperimentalNon-standard
scheme parameter supports ssh
scheme parameter supports tel
scheme parameter supports urn
scheme parameter supports webcal
scheme parameter supports wtai
scheme parameter supports xmpp
Secure context required

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.