OpenSearch 描述格式

OpenSearch 描述格式可用于描述搜索引擎的 Web 接口。这允许网站描述一个它自己的搜索引擎，浏览器或者其他客户端应用可以使用这个搜索引擎。OpenSearch 至少受到 Firefox、Safari 和 Chrome 的支持。（参见参考资料以获取其他浏览器文档的链接。）

Firefox 还支持 OpenSearch 标准内尚未包含的额外特性（如搜索建议和 <SearchForm> 元素）。这篇文章会聚焦在如何创建支持 Firefox 的额外特性且和 OpenSearch 格式兼容的搜索插件。

OpenSearch 描述文件能自动发现搜索插件中描述的方式安装。

警告： OpenSearch 插件已经无法上传到 addons.mozilla.org（AMO）上了。搜索引擎特性必须使用 WebExtension API，且在 manifest.json 文件中使用 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>[搜索引擎的全名和总结]</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]"/>
  <moz:SearchForm>[https://example.com/search]</moz:SearchForm>
</OpenSearchDescription>
ShortName

搜索引擎简称。其必须是 16 个或更少字符的纯文本，没有 HTML 或其他标记。

Description

搜索引擎的简要描述。其必须是 1024 个或更少字符的纯文本，没有 HTML 或其他标记。

InputEncoding

在将输入提交给搜索引擎时使用的字符编码。

Image

搜索引擎图标的 URL。在可能的情况下，包含一个 16x16 的 image/x-icon 类型的图标（例如 /favicon.ico），以及一个 64x64 的 image/jpeg 或 image/png 类型的图标。

URL 也可以使用 data: URL 方案。（你可以在 data: URL kitchen 直接从图标文件生成 data: URL。）

xml
<Image height="16" width="16" type="image/x-icon">https://example.com/favicon.ico</Image>
<!-- 或 -->
<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 KB 的图标。

Firefox 搜索框中显示来自 Google 的搜索建议

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 参数中描述了其他受支持的搜索参数。

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

自动发现搜索插件

提供搜索插件的网站可以宣告它们，以便 Firefox 用户可以轻松安装这些插件。

要支持自动发现，请在你网页的 <head> 中为每个插件添加一个 <link> 元素：

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

如下所示地修改在 [方括号] 内的项目：

searchTitle

要执行的搜索的名称，例如“搜索 MDC”或“雅虎搜索”等。其必须匹配插件文件的 ShortName。

pluginURL

到 XML 搜索插件的 URL，以便浏览器可以下载插件。

如果网站拥有多种搜索插件，也可以让它们全部支持自动发现。例如：

html
<link
  rel="search"
  type="application/opensearchdescription+xml"
  title="我的网站：根据作者"
  href="http://example.com/mysiteauthor.xml" />

<link
  rel="search"
  type="application/opensearchdescription+xml"
  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="http://example.com/mysearchdescription.xml" />

备注： 目前，addons.mozilla.org（AMO）不支持 OpenSearch 插件的自动更新。如果要把搜索插件放到 AMO，请在提交前移除自动更新特性。

排错技巧

如果搜索插件 XML 存在错误，则在添加已发现的插件时可能会遇到错误。如果错误消息没有实际帮助，以下技巧能帮你找出问题。

  • 服务器必须使用 Content-Type: application/opensearchdescription+xml 提供 OpenSearch 插件。
  • 确保搜索插件 XML 的格式正确。你可以直接用 Firefox 加载该文件来进行检查。template URL 的 & 符号必须像 &amp; 这样转义，标签也要用正斜杠或匹配的闭标签关闭。
  • xmlns 属性很重要——少了它就会出现错误消息“Firefox 无法下载搜索插件”。
  • 你必须包含 text/html URL：搜索插件只包含 Atom 或 RSS URL 类型（虽然它有效，但 Firefox 不支持）都可能发生“无法下载搜索插件”错误。
  • 远程获取的图标（favicon）不能大于 10KB（参见 Firefox bug 361923）。

此外，搜索插件服务还提供了日志记录机制，这对插件开发者来说可能很有用。使用 about:config 将 browser.search.log 首选项设为 true。然后，在添加搜索插件之后，Firefox 的浏览器控制台（工具 ➤ 浏览器工具 ➤ 浏览器控制台）中就会出现日志信息。

参考资料