blob: e51f8f9f200c557dea544db2fb3ba13053e3bb3d (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
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="https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md#opensearch-11-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>
|
