---
title: Navigator.registerProtocolHandler()
slug: Web/API/Navigator/registerProtocolHandler
tags:
  - API
  - Navigator
  - URL protocols
  - URL schemes
  - registerProtocolHandler
  - 自定义 URL 协议
  - 自定义 URL 方案
translation_of: Web/API/Navigator/registerProtocolHandler
---
<div>{{APIRef("HTML DOM")}}{{securecontext_header}}</div>

<p><strong>{{domxref("Navigator")}}</strong> 的方法 <code><strong>registerProtocolHandler()</strong></code> 让 web 站点为自身注册用于打开或处理特定 URL 方案（又名协议）的能力。</p>

<p>举个例子，此API允许Web邮件站点打开 <code>mailto:</code> URL，或让  <abbr title="Voice over Internet Protocol, also called IP telephony">VoIP</abbr>  站点打开 <code>tel:</code> URL。</p>

<h2 id="语法">语法</h2>

<pre class="notranslate">navigator.registerProtocolHandler(<var>scheme</var>, <var>url</var>, <var>title</var>);
</pre>

<div class="blockIndicator note">
<p><strong>Note:</strong> 最近更新为 <code>navigator.registerProtocolHandler(<var>scheme</var>, <var>url</var>)</code>, 但目前没有浏览器支持该版本。</p>
</div>

<h3 id="参数">参数</h3>

<dl>
 <dt><code><var>scheme</var></code></dt>
 <dd>一个包含站点希望处理的协议的字符串。例如，你可以通过传入 <code>"sms"</code> 来注册处理SMS文本信息链接。</dd>
</dl>

<dl>
 <dt><code>url</code></dt>
 <dd>处理器的URL，string类型。这个字符串应该包含一个"%s"的占位符，其会被将要受理的文档的 <a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent">escaped</a> 链接所替换。这个链接（译者按：指将要受理的文档的 escaped 链接，也就是替换占位符的字符串）可能是一个真实的URL，或者是一个电话号码，邮件地址之类的。</dd>
 <dd>
 <div class="note">这个处理器的 URL 必须以 <code>http</code> 或者 <code>https</code> 协议标记作为开头，最好是 <code>https</code> ，以满足一些浏览器出于安全考虑的要求。</div>
 </dd>
 <dt><code>title {{Obsolete_Inline}}</code></dt>
 <dd>一个用户可理解的处理器标题。标题会展示给用户，例如弹出对话框“允许这个站点处理[scheme]链接吗？”或者在浏览器设置中列出注册的处理器时。</dd>
 <dd>
 <div class="blockIndicator note">
 <p><strong>Note:</strong> 出于欺骗的考虑，标题已从规范中删除，但当前所有的浏览器仍要求使用该标题。 建议始终设置标题，因为支持更新规范的浏览器很可能会向后兼容，并且仍接受标题（但不使用它）。</p>
 </div>
 </dd>
 <dd></dd>
</dl>

<h3 id="异常">异常</h3>

<ul>
 <li>指定了一个非法的协议标记，例如一个浏览器自身的标记（<code>https:</code>, <code>about:</code> 等）。</li>
 <li>处理器URL的 <a href="/zh-CN/docs/Glossary/Origin">origin</a> 与调用这个API的页面的 origin不匹配。</li>
 <li>浏览器要求这个函数由安全的上下文调用。</li>
 <li>浏览器要求处理器的URL使用 HTTPS 协议。</li>
</ul>

<dl>
 <dt><code>SecurityError</code></dt>
 <dd>用户代理阻止了处理器的注册。这可能是由于：</dd>
 <dt><code>SyntaxError</code></dt>
 <dd>在指定的协议处理地址的字符串中缺失了 <code>%s</code> 占位符.</dd>
</dl>

<h2 id="允许的协议标记">允许的协议标记</h2>

<p>出于安全考虑，<code>registerProtocolHandler()</code> 严格限制了允许注册的协议标记。以 <code>web+</code> 作为前缀的方式可以注册一个自定义的标记协议，至少要有5个字符的长度(包括 <code>web+</code> 前缀)，而且只能使用小写的ASCII字母作为名称。例如 <code>web+burger</code> ，如下面的<a href="#示例">示例</a>所示。</p>

<p>除此之外，还可以使用下文所列的白名单中的协议标记:</p>

<div class="threecolumns">
<ul>
 <li><code>bitcoin</code></li>
 <li><code>geo</code></li>
 <li><code>im</code></li>
 <li><code>irc</code></li>
 <li><code>ircs</code></li>
 <li><code>magnet</code></li>
 <li><code>mailto</code></li>
 <li><code>mms</code></li>
 <li><code>news</code></li>
 <li><code>nntp</code></li>
 <li><code>openpgp4fpr</code></li>
 <li><code>sip</code></li>
 <li><code>sms</code></li>
 <li><code>smsto</code></li>
 <li><code>ssh</code></li>
 <li><code>tel</code></li>
 <li><code>urn</code></li>
 <li><code>webcal</code></li>
 <li><code>wtai</code></li>
 <li><code>xmpp</code></li>
</ul>
</div>

<h2 id="示例">示例</h2>

<p>如果您的网站是 <code>https://www.google.com/</code>，则可以为其注册一个协议处理程序来处理 <code>web+burger:</code>链接，如下所示：</p>

<pre class="brush: js notranslate">navigator.registerProtocolHandler("web+burger",
                                  "https://www.google.com/?uri=%s",
                                  "Burger handler");
</pre>

<p>这将创建一个处理程序，该处理程序允许使用 <code>web+burger: </code>链接将用户发送到您的网站，并将访问的 Burger URL插入<code>%s</code>占位符。</p>

<p>该脚本必须从与处理程序URL相同的源运行（因此， <code>https://www.google.com/ </code>上的任何页面），并且处理程序URL必须为 <code>http </code>或 <code>https</code>。</p>

<p>将通知用户您的代码要求注册协议处理程序，以便他们可以决定是否允许它。有关 <code>https://www.google.com/ </code>上的示例，请参见以下屏幕截图：</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/9683/protocolregister.png"></p>

<div class="note">
<p>"<a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a>" 展示了如何从跨平台组件对象模块(XPCOM)中做到这一切.</p>
</div>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('HTML WHATWG', 'webappapis.html#dom-navigator-registerprotocolhandler', 'registerProtocolHandler()')}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("api.Navigator.registerProtocolHandler")}}</p>

<h2 id="参见">参见</h2>

<ul>
 <li><a href="/en-US/docs/Web-based_protocol_handlers">Web-based protocol handlers</a></li>
 <li><a href="http://blog.mozilla.com/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/">RegisterProtocolHandler Enhancing the Federated Web</a> at Mozilla Webdev</li>
 <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#whitelisted-scheme">Web Application APIs - Custom scheme and content handlers - Whitelisted schemes</a></li>
 <li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#Getting_most_recent_window">Register a webmail service as mailto handler</a> shows how to do <code>registerProtocolHandler</code> from XPCOM scope.</li>
 <li><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWebContentHandlerRegistrar#registerProtocolHandler">XPCOM Interface Reference &gt; nsIWebContentHandlerRegistrar &gt; registerContentHandler</a> - This shows how to use this function XPCOM scope</li>
</ul>