OpenSearch 描述格式

**OpenSearch 描述格式** 可用于描述搜索引擎的 Web 接口。这允许网站为自身描述一个搜索引擎，以便浏览器或其他客户端应用程序可以使用该搜索引擎。OpenSearch 至少受 Firefox、Edge、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>[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]"/>
  <moz:SearchForm>[https://example.com/search]</moz:SearchForm>
</OpenSearchDescription>

ShortName

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

Description

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

InputEncoding

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

Image

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

URL 也可以使用 data: URL 方案。（您可以在 data: URL 工具中从图标文件生成 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 或 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="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 插件可以自动更新。要支持此功能，请包含一个带有 type="application/opensearchdescription+xml" 和 rel="self" 的额外 Url 元素。template 属性应为要自动更新到的 OpenSearch 文档的 URL。

例如

xml

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

注意：目前，addons.mozilla.org (AMO) 不支持 OpenSearch 插件的自动更新。如果您想将您的搜索插件放到 AMO 上，请在提交前删除自动更新功能。

故障排除技巧

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

您的服务器应使用 Content-Type: application/opensearchdescription+xml 提供 OpenSearch 插件。
确保您的搜索插件 XML 格式良好。您可以通过直接在 Firefox 中加载文件来检查。template URL 中的与号 (&) 必须转义为 &，并且标签必须用尾部斜杠或匹配的结束标签关闭。
xmlns 属性非常重要——没有它，您可能会收到“Firefox 无法下载搜索插件”的错误消息。
您必须包含一个 text/html URL——仅包含 Atom 或 RSS URL 类型（这有效，但 Firefox 不支持）的搜索插件也会生成“无法下载搜索插件”错误。
远程获取的网站图标大小不得超过 10KB（参见 Firefox 错误 361923）。

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

参考材料

OpenSearch 文档
Safari 8.0 发行说明：快速网站搜索
Microsoft Edge 开发指南：搜索提供程序发现
Chromium 项目：标签页搜索
imdb.com 有一个可用的 osd.xml
Ready2Search - 创建 OpenSearch 插件。通过 Ready2Search 自定义搜索