1. Web
  2. XML
  3. 指南
  4. OpenSearch 描述格式

OpenSearch 描述格式

OpenSearch 描述格式 可用于描述搜索引擎的 Web 界面。这允许网站为其自身描述一个搜索引擎，以便浏览器或其他客户端应用程序可以使用该搜索引擎。OpenSearch 由（至少）Firefox、Edge、Safari 和 Chrome 支持。（有关其他浏览器文档的链接，请参阅 参考资料。）

Firefox 还支持 OpenSearch 标准中没有的附加功能，例如搜索建议。本文重点介绍创建支持这些附加 Firefox 功能的 OpenSearch 兼容搜索引擎。

概述

浏览器中的地址栏具有双重用途：您可以输入 URL 直接访问网站，也可以输入搜索词来查询搜索引擎。搜索引擎会返回一个结果列表，您可以直接浏览，也可以打开搜索引擎的完整结果页面。

默认情况下，浏览器可以连接到一些流行的搜索引擎，例如 Google、Bing 或 Yandex。OpenSearch 协议允许网站定义自己的搜索引擎，使用户可以直接从浏览器地址栏搜索这些网站。例如，MDN 网站有一个全站搜索引擎。如果 MDN 将自己注册为搜索引擎，用户就可以直接从地址栏搜索 MDN。

浏览器通过请求 URL 来查询搜索引擎。网站定义了要请求的 URL 模板，浏览器会在指定的占位符中填入用户的搜索词。例如，如果搜索引擎 URL 是 https://example.com/search?q={searchTerms}，那么当用户在地址栏中键入“foo”时，浏览器将请求 https://example.com/search?q=foo。然后，搜索引擎会生成一个响应——搜索结果列表或完整的搜索结果页面。

网站通过在其 HTML 中链接到 XML 描述文件来定义其搜索引擎。当用户首次访问网站时，浏览器会检测到此描述文件并注册搜索引擎。然后，浏览器将使用注册的搜索引擎来处理来自地址栏的搜索。

注意： Chrome 默认将网站搜索引擎注册为“非活动”状态。用户必须在搜索引擎设置中手动激活每个网站。

OpenSearch 描述文件

描述搜索引擎的 XML 文件遵循以下基本模板。[方括号] 中的部分应根据您的特定引擎进行自定义。

xml
<OpenSearchDescription
  xmlns="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:moz="http://www.mozilla.org/2006/browser/search/">
  <ShortName>[SNK]</ShortName>
  <Description>[Search engine full name and summary]</Description>
  <InputEncoding>[UTF-8]</InputEncoding>
  <Image width="16" height="16" type="image/x-icon">[https://example.com/favicon.ico]</Image>
  <Url type="text/html" template="[searchURL]"/>
  <Url type="application/x-suggestions+json" template="[suggestionURL]"/>
</OpenSearchDescription>
ShortName

搜索引擎的简称。它必须是最多 16 个字符的纯文本，不含 HTML 或其他标记。

描述

搜索引擎的简要描述。它必须是最多 1024 个字符的纯文本，不含 HTML 或其他标记。

InputEncoding

向搜索引擎提交输入时要使用的字符编码。

图像

搜索引擎图标的 URL。如果可能，请包含一个 16×16 的 image/x-icon 类型图像（例如 /favicon.ico）和一个 64×64 的 image/jpeg 或 image/png 类型图像。

URL 也可以使用data: URL 方案。（您可以在 The data: URL kitchen 中从图标文件生成 data: URL。）

xml
<Image height="16" width="16" type="image/x-icon">https://example.com/favicon.ico</Image>
  <!-- or -->
<Image height="16" width="16">data:image/x-icon;base64,AAABAAEAEBAAA…DAAA=</Image>

Firefox 将图标缓存为 base64 data: URL（搜索插件存储在配置文件的 searchplugins/ 文件夹中）。http: 和 https: URL 在执行此操作时会被转换为 data: URL。

注意：对于远程加载的图标（即来自 https:// URL 而非 data: URL），Firefox 将拒绝大于10 千字节的图标。

Search suggestions from Google displayed in Firefox's search box

Url

描述用于搜索的 URL。template 属性指示搜索查询的基本 URL。

Firefox 支持三种 URL 类型

  • type="text/html" 指定实际搜索查询的 URL。
  • type="application/x-suggestions+json" 指定用于获取搜索建议的 URL。在 Firefox 63 及更高版本中，type="application/json" 被接受作为此项的别名。
  • type="application/x-moz-keywordsearch" 指定在地址栏中输入关键字搜索时使用的 URL。这仅在 Firefox 中受支持。

对于这些 URL 类型，您可以使用 {searchTerms} 来替换用户在搜索栏或地址栏中输入的搜索词。其他支持的动态搜索参数可在 OpenSearch 1.1 parameters 中找到。

对于搜索建议，application/x-suggestions+json URL 模板用于以 JSON 格式获取建议列表。

链接到 OpenSearch 描述文件

要支持自动发现，请为您的网页 <head> 中的每个搜索引擎添加一个 <link> 元素

html
<link
  rel="search"
  type="application/opensearchdescription+xml"
  title="[searchTitle]"
  href="[descriptionURL]" />

根据下面的说明替换[方括号]中的项目

searchTitle

要执行的搜索名称，例如“搜索 MDC”或“Yahoo! 搜索”。这必须与您的插件文件的 <ShortName> 匹配。

descriptionURL

XML 描述文件的 URL，以便浏览器可以下载它。

如果您的网站提供多个搜索引擎，您可以为它们全部支持自动发现。例如

html
<link
  rel="search"
  type="application/opensearchdescription+xml"
  title="MySite: By Author"
  href="http://example.com/mysiteauthor.xml" />

<link
  rel="search"
  type="application/opensearchdescription+xml"
  title="MySite: By Title"
  href="http://example.com/mysitetitle.xml" />

这样，您的网站就可以提供两个搜索引擎：一个按作者搜索，另一个按标题搜索。

注意：在 Firefox 中，搜索框中的图标更改表示提供了搜索插件。（请参阅图像，绿色加号。）因此，如果用户界面中未显示搜索框，他们将不会收到任何指示。通常，不同浏览器的行为会有所不同。

支持 OpenSearch 描述的自动更新

OpenSearch 描述文件可以自动更新。要支持此功能，请包含一个额外的 Url 元素，其 type 为 "application/opensearchdescription+xml" 且 rel 为 "self"。template 属性应为要自动更新到的 OpenSearch 文档的 URL。

例如

xml
<Url
  type="application/opensearchdescription+xml"
  rel="self"
  template="https://example.com/mysearchdescription.xml" />

故障排除技巧

如果您的 XML 描述文件有错误，在添加搜索引擎时可能会遇到错误。如果错误消息没有帮助，请使用以下技巧来排查问题

  • 检查您的服务器是否使用 Content-Type: application/opensearchdescription+xml 提供 OpenSearch 描述。
  • 确保您的 XML 描述文件格式正确。您可以通过直接在浏览器中加载该文件来检查。template URL 中的 Ampersand（&）必须转义为 &amp;，并且标签必须用斜杠结尾或使用匹配的结束标签。
  • 请确保包含 xmlns 属性——没有它，您可能会收到“Firefox 无法下载搜索插件”之类的错误消息。
  • 您必须包含一个 text/html URL — 仅包含 Atom 或 RSS URL 类型的搜索引擎（这是有效的，但 Firefox 不支持）也会生成“无法下载搜索插件”的错误。
  • 远程获取的图标不得大于 10KB（请参阅 Firefox bug 361923）。
  • 如前所述，浏览器可能默认不激活网站搜索快捷方式。检查浏览器的设置并确保搜索引擎已激活。

此外，搜索插件服务提供了一个可能对插件开发者有用的日志记录机制。使用 about:config 将偏好设置 browser.search.log 设置为 true。然后，当添加搜索插件时，日志信息将出现在 Firefox 的浏览器控制台（工具 ➤ 浏览器工具 ➤ 浏览器控制台）中。

参考资料

帮助改进 MDN

了解如何贡献

此页面最后修改于 ，由 MDN 贡献者 修改。

在 GitHub 上查看此页面 • 报告此内容的错误