OpenSearch 描述格式

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

¥The OpenSearch description format can be used to describe the web interface of a search engine. This allows a website to describe a search engine for itself, so that a browser or other client application can use that search engine. OpenSearch is supported by (at least) Firefox, Edge, Safari, and Chrome. (See Reference Material for links to other browsers' documentation.)

Firefox 还支持 OpenSearch 标准中未包含的其他功能，例如搜索建议和 <SearchForm> 元素。本文重点介绍如何创建支持这些附加 Firefox 功能的 OpenSearch 兼容搜索插件。

¥Firefox also supports additional features not in the OpenSearch standard, such as search suggestions and the <SearchForm> element. This article focuses on creating OpenSearch-compatible search plugins that support these additional Firefox features.

OpenSearch 描述文件可以按照 自动发现搜索插件 中的描述进行广告。

¥OpenSearch description files can be advertised as described in Autodiscovery of search plugins.

警告：OpenSearch 插件无法再在 addons.mozilla.org (AMO) 上上传。搜索引擎功能必须使用 WebExtension API 和 manifest.json 文件中的 chrome 设置。

¥Warning: OpenSearch plugins can't be uploaded anymore on addons.mozilla.org (AMO). Search engine feature must use WebExtension API with chrome settings in manifest.json file.

OpenSearch 描述文件

¥OpenSearch description file

描述搜索引擎的 XML 文件遵循以下基本模板。[方括号] 中的部分应针对你正在编写的特定插件进行自定义。

¥The XML file that describes a search engine follows the basic template below. Sections in [square brackets] should be customized for the specific plugin you're writing.

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 或其他标记。

描述

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

InputEncoding

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

图片

搜索引擎图标的 URL。如果可能，请包含 image/x-icon 类型（例如 /favicon.ico）的 16×16 图片和 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（搜索插件存储在 profile 的 searchplugins/ 文件夹中）。完成此操作后，http: 和 https: URL 将转换为 data: URL。

注意：对于远程加载的图标（即从 https:// URL 而不是 data: URL），Firefox 将拒绝大于 10 KB 的图标。

¥Note: For icons loaded remotely (that is, from https:// URLs as opposed to data: URLs), Firefox will reject icons larger than 10 kilobytes.

Search suggestions from Google displayed in Firefox's search box

网址

描述用于搜索的一个或多个 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 格式的建议列表。

自动发现搜索插件

¥Autodiscovery of search plugins

带有搜索插件的网站可以为其做广告，以便 Firefox 用户可以轻松安装这些插件。

¥Websites with search plugins can advertise them so Firefox users can easily install the plugins.

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

¥To support autodiscovery, add a <link> element for each plugin to the <head> of your web page:

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

如下所述替换粗体项目：

¥Replace the bolded items as explained below:

searchTitle

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

插件网址

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

如果你的网站提供多个搜索插件，你可以支持所有这些插件的自动发现。例如：

¥If your site offers multiple search plugins, you can support autodiscovery for them all. For example:

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" />

这样，你的网站就可以提供按作者或标题搜索的插件。

¥This way, your site can offer plugins to search by author, or by title.

注意：在 Firefox 中，搜索框中的图标变化表示提供了搜索插件。（见图，绿色加号。）因此，如果用户的 UI 中未显示搜索框，他们将不会收到任何指示。一般来说，不同浏览器的行为有所不同。

¥Note: In Firefox, an icon change in the search box indicates there's a provided search plugin. (See image, the green plus sign.) Thus if a search box is not shown in the user's UI, they will receive no indication. In general, behavior varies among browsers.

支持 OpenSearch 插件自动更新

¥Supporting automatic updates for OpenSearch plugins

OpenSearch 插件可以自动更新。为了支持这一点，请包含一个额外的 Url 元素以及 type="application/opensearchdescription+xml" 和 rel="self"。template 属性应该是要自动更新到的 OpenSearch 文档的 URL。

¥OpenSearch plugins can automatically update. To support this, include an extra Url element with type="application/opensearchdescription+xml" and rel="self". The template attribute should be the URL of the OpenSearch document to automatically update to.

例如：

¥For example:

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

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

¥Note: At this time, addons.mozilla.org (AMO) doesn't support automatic updating of OpenSearch plugins. If you want to put your search plugin on AMO, remove the auto-updating feature before submitting it.

故障排除技巧

¥Troubleshooting Tips

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

¥If there is a mistake in your Search Plugin XML, you could run into errors when adding a discovered plugin. If the error message isn't be helpful, the following tips could help you find the problem.

  • 你的服务器应该使用 Content-Type: application/opensearchdescription+xml 来提供 OpenSearch 插件。
  • 确保你的搜索插件 XML 格式正确。你可以通过将文件直接加载到 Firefox 中进行检查。template URL 中的与号 (&) 必须转义为 &amp;，并且标签必须以尾部斜杠或匹配的结束标签结束。
  • xmlns 属性很重要 - 如果没有它，你可能会收到错误消息 "Firefox 无法下载搜索插件"。
  • 你必须包含 text/html URL — 仅包含 Atom 或 RSS URL 类型（有效，但 Firefox 不支持）的搜索插件也会生成 "无法下载搜索插件" 错误。
  • 远程获取的图标不得大于 10KB（参见 火狐错误 361923）。

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

¥In addition, the search plugin service provides a logging mechanism that may be useful to plugin developers. Use about:config to set the pref 'browser.search.log' to true. Then, logging information will appear in Firefox's Browser Console(Tools ➤ Browser Tools ➤ Browser Console) when search plugins are added.

参考资料

¥Reference Material