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 自定義搜尋