diff options
Diffstat (limited to 'files/zh-tw/web/opensearch/index.html')
| -rw-r--r-- | files/zh-tw/web/opensearch/index.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/files/zh-tw/web/opensearch/index.html b/files/zh-tw/web/opensearch/index.html new file mode 100644 index 0000000000..36fe253620 --- /dev/null +++ b/files/zh-tw/web/opensearch/index.html @@ -0,0 +1,179 @@ +--- +title: 製作 OpenSearch 搜尋模組 +slug: Web/OpenSearch +tags: + - 待翻譯 + - 搜尋模組 +translation_of: Web/OpenSearch +--- +<div>{{AddonSidebar}}</div> + +<p><a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document">OpenSearch 描述語法</a>敘述了搜尋引擎，以便網站用戶透過瀏覽器或其他用戶端程式使用之。OpenSearch 支援最新版的 Firefox、Internet Explorer、Safari、Chrome.</p> + +<p>Firefox 還支援搜尋建議與 <code><SearchForm></code> 元素……等 OpenSearch 標準內尚未包含的功能。這篇文章會聚焦在如何撰寫可支援 Firefox 特殊功能、且和 OpenSearch 格式相容的搜尋套件。</p> + +<p>OpenSearch 描述檔能由網站<a href="#.E8.87.AA.E5.8B.95.E6.B8.AC.E7.9F.A5.E6.90.9C.E5.B0.8B.E6.A8.A1.E7.B5.84">自動提示安裝</a>，或是藉<a href="/zh-tw/%e5%be%9e%e7%b6%b2%e9%a0%81%e5%ae%89%e8%a3%9d%e6%90%9c%e5%b0%8b%e6%a8%a1%e7%b5%84">從網頁安裝搜尋模組</a>中描述的方式安裝。</p> + +<h2 id="OpenSearch_描述檔">OpenSearch 描述檔</h2> + +<p>這個描述搜尋引擎的 XML 檔其實很簡單，參考下面的基本樣板，以斜體標示的部分則依需求修改即可。</p> + +<pre class="brush: xml"><OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" + xmlns:moz="http://www.mozilla.org/2006/browser/search/"> + <ShortName><mark><strong>SNK</strong></mark></ShortName> + <Description><mark><strong>Search engine full name and summary</strong></mark></Description> + <InputEncoding><mark><strong>UTF-8</strong></mark></InputEncoding> + <Image width="16" height="16" type="image/x-icon"><mark><strong>data:image/x-icon;base64,AAABAAEAEBAAA ...</strong></mark></Image> + <Url type="text/html" template="<mark><strong>searchURL</strong></mark>"> + <Param name="<mark><strong>key name</strong></mark>" value="{searchTerms}"/> + ... + <Param name="<mark><strong>key name</strong></mark>" value="<mark><strong>parameter value</strong></mark>"/> + </Url> + <Url type="application/x-suggestions+json" template="<mark><strong>suggestionURL</strong></mark>"/> + <moz:SearchForm><mark><strong>http://example.com/search</strong></mark></moz:SearchForm> +</OpenSearchDescription></pre> + +<dl> + <dt>ShortName</dt> + <dd>搜尋引擎簡稱</dd> + <dd><strong>Restrictions:</strong> The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup.</dd> +</dl> + +<dl> + <dt>Description</dt> + <dd>搜尋引擎的簡要描述</dd> + <dd><strong>Restrictions:</strong> The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup.</dd> +</dl> + +<dl> + <dt>InputEncoding</dt> + <dd>搜尋引擎資料輸入時的編碼方式，例如說：<code><InputEncoding>UTF-8</InputEncoding></code>。</dd> +</dl> + +<dl> + <dt>Image</dt> + <dd> + <p>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 <code>image/jpeg</code> or <code>image/png</code>. The URI may also use the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/data_URIs"><code>data:</code> URI scheme</a>. You can generate a <code>data:</code> URI from an icon file at <a class="external" href="http://software.hixie.ch/utilities/cgi/data/data">The <code>data:</code> URI kitchen</a>.</p> + + <pre class="brush: 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> +</pre> + + <p>Firefox caches the icon as a <a href="https://en.wikipedia.org/wiki/Base64">base64</a> <code>data:</code> URI (search plug-ins are stored in the profile's "searchplugins" folder). <code>http:</code> URIs are changed to <code>data:</code> URIs when this is done.</p> + + <div class="note"><strong>Note:</strong> For icons loaded remotely (i.e. from <code>https://</code> URIs as opposed to <code>data:</code> URIs), Firefox will reject icons larger than 10 kilobytes in size.</div> + + <p><img alt="Search suggestions from Google displayed in Firefox's search box" class="internal" src="/@api/deki/files/358/=SearchSuggestionSample.png"></p> + </dd> +</dl> + +<dl> + <dt><strong>Url</strong></dt> + <dd>描述搜尋用的 URL。以 <code>template</code> 屬性指定其搜尋 URL。</dd> + <dd>Firefox 支援以下型態的 URL： + <ul> + <li><code>type="text/html"</code>，即是搜尋用的 URL。</li> + <li><code>type="application/x-suggestions+json"</code>，用以取回「搜尋建議」的 URL。</li> + </ul> + + <ul> + <li><code>type="application/x-moz-keywordsearch"</code> specifies the URL used when a keyword search is entered in the location bar. This is supported only in Firefox.</li> + </ul> + + <ul> + </ul> + + <p>這些型態的 URL 都可以使用 <code>{searchTerms}</code> 字串來決定要關鍵字於 URL 中的位置，其他可用的參數請參考<a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#OpenSearch_1.1_parameters">OpenSearch 1.1 參數規格</a>。</p> + + <p>在支援「搜尋建議」的模組中，搜尋的 URL 應可取回一組以 JSON 格式編寫的數據，提供這類服務的詳細方法請見<a href="/zh-tw/%e8%ae%93%e6%90%9c%e5%b0%8b%e6%a8%a1%e7%b5%84%e6%94%af%e6%8f%b4%e6%90%9c%e5%b0%8b%e5%bb%ba%e8%ad%b0">讓搜尋模組支援搜尋建議</a>。</p> + </dd> +</dl> + +<p><img alt="Image:SearchSuggestionSample.png"></p> + +<dl> + <dt>Param</dt> + <dd>隨搜尋要求一併送出的參數，每組皆有參數名稱及其值。指定參數時可放入 <code>{searchTerms}</code> 字串來取得使用者輸入的搜尋關鍵字。</dd> +</dl> + +<dl> + <dt>moz:SearchForm</dt> + <dd>搜尋網站的網址，提供 Firefox 使用者不搜尋、直接連到搜尋網站的方法。</dd> + <dd> + <div class="note"><strong>註：</strong> 由於此元素非 OpenSearch 標準規格而是 Firefox 獨有，故加上「<code>moz:</code>」名稱空間，已確保不支援的用戶端能直接跳過此元素。</div> + </dd> +</dl> + +<h2 id="自動測知搜尋模組">自動測知搜尋模組</h2> + +<p>提供搜尋模組的網站能以「自動測知」的方式，讓 Firefox 使用者輕易安裝搜尋模組，增加使用率。</p> + +<p>只要在網頁的 <code><head></code> 區段內加上下一行就可以支援自動測知功能：</p> + +<pre class="brush: html"><link rel="search" + type="application/opensearchdescription+xml" + title="<mark><strong>searchTitle</strong></mark>" + href="<mark><strong>pluginURL</strong></mark>"> +</pre> + +<p>如上所示地修改上面的<strong>粗體字</strong> :</p> + +<dl> + <dt><strong>searchTitle</strong></dt> + <dd>這是搜尋引擎的名稱，例如「Search MDC」或「雅虎搜尋」等。這個名稱應該與引擎名稱一樣。</dd> +</dl> + +<dl> + <dt><strong>pluginURL</strong></dt> + <dd>瀏覽器可以下載的搜尋引擎 XML 檔案位置。</dd> +</dl> + +<p>如果網站擁有多種搜尋模組，也可以讓它們全部支援自動測知。例如：</p> + +<pre class="brush: 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"> +</pre> + +<p>這樣，網站就能提供以作者或以標題，作為搜尋獨立實體的模組。</p> + +<h2 id="讓_OpenSearch_套件自動更新">讓 OpenSearch 套件自動更新</h2> + +<p>只要在 <code>Url</code> 元素添加額外的 + <code>application/opensearchdescription+xml</code> type 屬性，OpenSearch 套件就可以自動更新。<code>rel</code> 屬性需要是 <code>self</code>、要自動更新的 template 則需要是屬於 OpenSearch 文件的 URL。</p> + +<p>例如說：</p> + +<pre class="brush: xml"><Url type="application/opensearchdescription+xml" + rel="self" + template="http://example.com/mysearchdescription.xml" /> +</pre> + +<div class="note"><strong>註：</strong>目前的<a class="external" href="http://addons.mozilla.org">addons.mozilla.org</a>（AMO）不支援自動更新 OpenSearch 套件。如果要把搜尋套件放到 AMO，請不要用上自動更新的功能。</div> + +<h2 id="除錯技巧">除錯技巧</h2> + +<p>如果搜尋套件 XML 發生錯誤，you could run into errors when adding a discovered plugin。如果錯誤訊息沒有用，以下技巧能幫忙找出問題。</p> + +<ul> + <li>供應伺服器 OpenSearch 套件服務的伺服器必須使用 <code>Content-Type: application/opensearchdescription+xml</code>。</li> + <li>確認搜尋套件 XML 的格式正確。你可以直接用 Firefox 載入該檔案。template URL 的 & 符號需要像 <code>&amp;</code> 這樣跳脫，標籤也要用正斜線或 end tag 關閉。</li> + <li><code>xmlns</code> 屬性很重要，少了它就會出現「Firefox could not download the search plugin」的錯誤訊息。</li> + <li>你<strong>必須</strong>包含 <code>text/html</code> URL：搜尋套件只包含 Atom 或 <a href="/zh-TW/RSS">RSS</a> URL 類型（雖然它有效，但 Firefox 不支援）都可能發生「could not download the search plugin」錯誤。</li> + <li>遠端擷取的小圖標（favicon）不能大於 10KB(請參見 {{ Bug(361923) }}）。</li> +</ul> + +<p>In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use <code>about:config</code> to set the pref '<code>browser.search.log</code>' to <code>true</code>. Logging information will appear in Firefox's <a href="/zh-TW/Error_Console">Error Console</a> (Tools 〉 Error Console) when search plugins are added.</p> + +<h2 id="參考">參考</h2> + +<ul> + <li><a class="external" href="http://opensearch.org/">OpenSearch Documentation</a>, <a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0">OpenSearch Documentation about the Url and Param element</a></li> + <li>imdb.com has a <a class="external" href="http://i.media-imdb.com/images/SFccbe1e4d909ef8b8077201c3c5aac349/imdbsearch.xml">working osd.xml</a></li> + <li><a class="external" href="http://en.wikipedia.org/wiki/Data:_URI_scheme"><code>data:</code> URI scheme</a></li> + <li><a class="external" href="http://www.7is7.com/software/firefox/opensearch.html">OpenSearch Plugin Generator</a></li> + <li><a class="external" href="http://ready.to/search/en">Ready2Search</a> - create OpenSearch plugins. <a class="external" href="http://ready.to/search/make/en_make_plugin.htm">Customized Search through Ready2Search</a></li> +</ul> |