製作 OpenSearch 搜尋模組
==================

OpenSearch 描述語法敘述了搜尋引擎，以便網站用戶透過瀏覽器或其他用戶端程式使用之。OpenSearch 支援最新版的 Firefox、Internet Explorer、Safari、Chrome.

Firefox 還支援搜尋建議與 `<SearchForm>` 元素……等 OpenSearch 標準內尚未包含的功能。這篇文章會聚焦在如何撰寫可支援 Firefox 特殊功能、且和 OpenSearch 格式相容的搜尋套件。

OpenSearch 描述檔能從網頁安裝搜尋模組中描述的方式安裝。

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">data:image/x-icon;base64,AAABAAEAEBAAA ...</Image>
  <Url type="text/html" template="searchURL">
    <Param name="key name" value="{searchTerms}"/>
    ...
    <Param name="key name" value="parameter value"/>
  </Url>
  <Url type="application/x-suggestions+json" template="suggestionURL"/>
  <moz:SearchForm>http://example.com/search</moz:SearchForm>
</OpenSearchDescription>
```


ShortName

搜尋引擎簡稱。**Restrictions:** The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup.

Description

搜尋引擎的簡要描述。**Restrictions:** The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup.

InputEncoding

搜尋引擎資料輸入時的編碼方式，例如說：`<InputEncoding>UTF-8</InputEncoding>`。

Image

URI to an icon representative of the search engine. When possible, search engines should offer a 16×16 image of type "image/x-icon" and a 64×64 image of type `image/jpeg` or `image/png`. The URI may also use the `data:` URI scheme (en-US). You can generate a `data:` URI from an icon file at The `data:` URI kitchen.


```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 caches the icon as a base64 `data:` URI (search plug-ins are stored in the profile's "searchplugins" folder). `http:` URIs are changed to `data:` URIs when this is done.

**備註：** For icons loaded remotely (i.e. from `https://` URIs as opposed to `data:` URIs), Firefox will reject icons larger than 10 kilobytes in size.

![Search suggestions from Google displayed in Firefox's search box](/zh-TW/docs/Web/OpenSearch/searchsuggestionsample.png)

**Url**

描述搜尋用的 URL。以 `template` 屬性指定其搜尋 URL。Firefox 支援以下型態的 URL：

* `type="text/html"`，即是搜尋用的 URL。
* `type="application/x-suggestions+json"`，用以取回「搜尋建議」的 URL。
* `type="application/x-moz-keywordsearch"` specifies the URL used when a keyword search is entered in the location bar. This is supported only in Firefox.

這些型態的 URL 都可以使用 `{searchTerms}` 字串來決定要關鍵字於 URL 中的位置，其他可用的參數請參考 OpenSearch 1.1 參數規格。

在支援「搜尋建議」的模組中，搜尋的 URL 應可取回一組以 JSON 格式編寫的數據，提供這類服務的詳細方法請見讓搜尋模組支援搜尋建議。

Param

隨搜尋要求一併送出的參數，每組皆有參數名稱及其值。指定參數時可放入 `{searchTerms}` 字串來取得使用者輸入的搜尋關鍵字。

moz:SearchForm

搜尋網站的網址，提供 Firefox 使用者不搜尋、直接連到搜尋網站的方法。

**備註：** 由於此元素非 OpenSearch 標準規格而是 Firefox 獨有，故加上「`moz:`」名稱空間，已確保不支援的用戶端能直接跳過此元素。

自動測知搜尋模組
--------

提供搜尋模組的網站能以「自動測知」的方式，讓 Firefox 使用者輕易安裝搜尋模組，增加使用率。

只要在網頁的 `<head>` 區段內加上下一行就可以支援自動測知功能：


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


如上所示地修改上面的**粗體字** :

**searchTitle**

這是搜尋引擎的名稱，例如「Search MDC」或「雅虎搜尋」等。這個名稱應該與引擎名稱一樣。

**pluginURL**

瀏覽器可以下載的搜尋引擎 XML 檔案位置。

如果網站擁有多種搜尋模組，也可以讓它們全部支援自動測知。例如：


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


這樣，網站就能提供以作者或以標題，作為搜尋獨立實體的模組。

讓 OpenSearch 套件自動更新
-------------------

 只要在 `Url` 元素添加額外的
 `application/opensearchdescription+xml` type 屬性，OpenSearch 套件就可以自動更新。`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 發生錯誤，you could run into errors when adding a discovered plugin。如果錯誤訊息沒有用，以下技巧能幫忙找出問題。

* 供應伺服器 OpenSearch 套件服務的伺服器必須使用 `Content-Type: application/opensearchdescription+xml`。
* 確認搜尋套件 XML 的格式正確。你可以直接用 Firefox 載入該檔案。template URL 的 & 符號需要像 `&amp;` 這樣跳脫，標籤也要用正斜線或 end tag 關閉。
* `xmlns` 屬性很重要，少了它就會出現「Firefox could not download the search plugin」的錯誤訊息。
* 你**必須**包含 `text/html` URL：搜尋套件只包含 Atom 或 RSS URL 類型（雖然它有效，但 Firefox 不支援）都可能發生「could not download the search plugin」錯誤。
* 遠端擷取的小圖標（favicon）不能大於 10KB（請參見 Firefox bug 361923）。

In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use `about:config` to set the pref '`browser.search.log`' to `true`. Logging information will appear in Firefox's Error Console (Tools 〉 Error Console) when search plugins are added.

參考
--

* OpenSearch Documentation, OpenSearch Documentation about the Url and Param element
* imdb.com has a working osd.xml
* `data:` URI scheme
* OpenSearch Plugin Generator
* Ready2Search - create OpenSearch plugins. Customized Search through Ready2Search