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 上檢視此頁面 • 報告此內容的錯誤
© . Content available under a Creative Commons license.