diff options
Diffstat (limited to 'files/zh-tw/archive/b2g_os/add-ons/index.html')
| -rw-r--r-- | files/zh-tw/archive/b2g_os/add-ons/index.html | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/files/zh-tw/archive/b2g_os/add-ons/index.html b/files/zh-tw/archive/b2g_os/add-ons/index.html new file mode 100644 index 0000000000..13f42518cd --- /dev/null +++ b/files/zh-tw/archive/b2g_os/add-ons/index.html @@ -0,0 +1,282 @@ +--- +title: Firefox OS 附加元件 +slug: Archive/B2G_OS/Add-ons +translation_of: Archive/B2G_OS/Add-ons +--- +<div class="warning"> +<p><strong>重要</strong>: 僅 Firefox OS 2.5+ 支援附加元件功能。</p> +</div> + +<p class="summary">「附加元件」的概念在 Web 瀏覽器的世界中眾人皆知，而我們也將這個概念帶進 Firefox OS。Firefox OS 的附加元件可以僅僅作用於單一 App 上，也可以指定作用於多個、甚至所有 App 上。本文帶您一步步撰寫自己的 Firefox OS 附加元件，同時提供一些秘訣及其他應該了解的資訊。</p> + +<div class="note"> +<p><strong>附註</strong>：本文僅重點概略翻譯。</p> +</div> + +<div class="note"> +<p><strong>附註</strong>：Firefox OS 附加元件採用 WebExtensions 擴充模式。此模式大部份源自於 Chrome/Blink 擴充套件機制，讓附加元件在開發時能擁有許多互通性與功能上的優勢。詳情可見持續編寫中的 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions">WebExtensions 文件集</a>。</p> +</div> + +<h2 id="開發附加元件">開發附加元件</h2> + +<p>Firefox OS 附加元件其實也是個內含 JavaScript / CSS / 其他必備檔案的 App，但不是拿來獨立運作，而是在描述檔中增加特別的說明來定義要在哪些 App 中使用這個附加元件。When apps are launched on a Firefox OS device that has an add-on installed, the add-on is injected into any app that matches the pattern specifed in the filter.</p> + +<p>Firefox OS add-ons use the same syntax and structure for their code as the new school of Firefox add-ons developed using the <a href="https://wiki.mozilla.org/WebExtensions">WebExtensions API</a>, which is itself based on the <a href="https://developer.chrome.com/extensions">Chrome extensions</a> model.</p> + +<h3 id="簡單範例">簡單範例</h3> + +<p>以下我們以一個簡單的例子說明 Firefox OS 附加元件的程式基礎。這個附加元件會在 system app 放上一塊看板，使用者可以點擊關閉。</p> + +<p><img alt="firefox os screenshot showing add-on banner" src="https://mdn.mozillademos.org/files/11445/add-on-screenshot.png" style="display: block; height: 445px; margin: 0px auto; width: 250px;"></p> + +<p>這個附加元件很簡單，但用來作為入門倒是相當足夠了。你可以在 <a href="https://github.com/mdn/simple-addon">GitHub 上下載範例程式</a>，而後用 WebIDE 裝到你的 Firefox OS 裝置上（參考 {{anch("Testing your add-on using WebIDE")}} 一節）。往後你也可以透過 <a href="https://marketplace.firefox.com/">Firefox Marketplace</a> 來發表自己的附加元件。</p> + +<p>Be aware that Firefox OS add-ons can do a lot more than what we've got listed here. The <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> documentation will have more information added as time goes on.</p> + +<h2 id="解析_Firefox_OS_add-on">解析 Firefox OS add-on</h2> + +<p>In this section we'll walkthrough the contents of the sample add-on repo, explaining each piece of content. 目錄結構看起來像這樣：</p> + +<ul class="directory-tree"> + <li>simple-addon/ + <ul> + <li>manifest.json</li> + <li>update.webapp</li> + <li>css/ + <ul> + <li>style.css</li> + </ul> + </li> + <li>js/ + <ul> + <li>index.js</li> + </ul> + </li> + <li>icons/ + <ul> + <li>128.png</li> + </ul> + </li> + <li>extension.zip</li> + </ul> + </li> +</ul> + +<h3 id="manifest.json">manifest.json</h3> + +<p>你應該發現了：在這個範例附加元件目錄中，有兩種類似的描述檔。第一個<code>「manifest.json</code>」的結構類似 Chrome 擴充套件，與 CSS、JavaScript 及其他檔案一起放在 {{anch("extensions.zip")}} 當中。It can contain a large variety of instructions (see <a href="https://developer.chrome.com/extensions/manifest">Chrome Manifest File Format</a>), but for now we're just going to concentrate on a simple subset:</p> + +<pre class="brush: json language-json"><code class="language-json"><span class="punctuation token">{</span> + <span class="key token">"manifest_version":</span> <span class="number token">1</span><span class="punctuation token">,</span> + <span class="key token">"name":</span> <span class="string token">"Add-on banner"</span><span class="punctuation token">,</span> + <span class="key token">"description":</span> <span class="string token">"Firefox OS add-on example"</span><span class="punctuation token">,</span> + <span class="key token">"version":</span> <span class="string token">"1.0"</span><span class="punctuation token">,</span> + <span class="key token">"author":</span> <span class="string token">"Chris Mills"</span><span class="punctuation token">,</span> + <span class="key token">"content_scripts":</span> <span class="punctuation token">[</span><span class="punctuation token">{</span> + <span class="key token">"matches":</span> <span class="punctuation token">[</span><span class="string token">"app://system.gaiamobile.org/index.html"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + <span class="key token">"css":</span> <span class="punctuation token">[</span><span class="string token">"css/style.css"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + <span class="key token">"js":</span> <span class="punctuation token">[</span><span class="string token">"js/index.js"</span><span class="punctuation token">]</span> + <span class="punctuation token">}</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + <span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"128":</span> <span class="string token">"/icons/128.png"</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span></code></pre> + +<p>Most of these fields are pretty self-explanatory, but we'll cover the last few.</p> + +<p>首先以 <code>content_scripts</code> 指定要植入 app 的檔案 — 你可以看到這邊以 <code>css</code> 及 <code>js</code> 兩欄分別指定 CSS 樣式檔及 JavaScript 程式檔。<code>matches</code> 欄位則是用以指定該把檔案放入哪些 app 裡，這個欄位的內容形式很多元（參考 <a href="https://developer.chrome.com/extensions/match_patterns">Chrome Match Patterns</a>），但我們先簡單指定為 <code>app://system.gaiamobile.org/index.html</code>，讓附加元件僅影響 system app。若想影響所有 app，可以將此欄位寫為 <code>app://*/* </code>。</p> + +<div class="note"> +<p><strong>Note</strong>: You can reference multiple scripts and stylesheets by simply including multiple items in the arrays, for example <code>"css": ["css/style.css", "css/more.css"]</code>.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: Firefox OS does not currently support the Chrome <all_urls> keyword.</p> +</div> + +<p>At the bottom of the manifest we've included the <code>icons</code> field; see the next section for more info on this.</p> + +<h3 id="update.webapp">update.webapp</h3> + +<p><code>update.webapp</code> 則是 <a href="https://developer.mozilla.org/en-US/Apps/Build/Manifest">Firefox OS 式的描述檔</a>，基本上就是跟打包 app 時用的描述檔格式相同。（參考 <a href="https://developer.mozilla.org/en-US/Marketplace/Options/Self_publishing#Self-publishing_packaged_apps">Self-publishing packaged apps</a>。）</p> + +<p>Our <code>update.webapp</code> file looks like so:</p> + +<pre class="brush: json language-json"><code class="language-json"><span class="punctuation token">{</span> + <span class="key token">"name" :</span> <span class="string token">"Add-on banner"</span><span class="punctuation token">,</span> + <span class="key token">"description":</span> <span class="string token">"Firefox OS add-on example"</span><span class="punctuation token">,</span> + <span class="key token">"developer":</span> <span class="punctuation token">{</span> <span class="key token">"name":</span> <span class="string token">"Chris Mills"</span> <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"package_path":</span> <span class="string token">"extension.zip"</span><span class="punctuation token">,</span> + <span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"128":</span> <span class="string token">"/icons/128.png"</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span></code></pre> + +<p>Again, most of this is fairly self-explanatory.</p> + +<p>這邊最重要的欄位該是 <code>package_path</code>，用以指定內含附加元件程式的包裝檔位置。</p> + +<p>You'll notice that the <code>icons</code> field is included here, the same as it is in {{anch("manifest.json")}} — <code>update.webapp</code> is the only place you <em>need</em> to have the icons information at the moment, but we'd recommend you include it in both places for now, just in case things change. The <code>icons</code> field points to the add-on icon so it can be used inside the Gaia Settings app, and the Firefox Marketplace when it starts to host add-ons.</p> + +<h3 id="指定圖示">指定圖示</h3> + +<p>你必須在描述檔中至少指定一個圖示，否則描述檔無效。詳情可參考 <a href="https://developer.mozilla.org/en-US/Apps/Build/Manifest#icons">Manifest 參考文件：圖示</a> 一節。</p> + +<h3 id="CSS">CSS</h3> + +<p>There is nothing special about the CSS included in the example. The only thing to bear in mind is that you should make sure your add-on classnames and selectors do not conflict with any of the existing CSS in the app(s) it is applied to.</p> + +<p>For example, we wrapped our example banner in a {{htmlelement("div")}} with class <code>fxos-banner</code>. But you could even consider using some kind of unique code for your classname.</p> + +<h3 id="JavaScript">JavaScript</h3> + +<p>Again, the JavaScript file that powers the add-on doesn't have any special functionality inside it (see the <a href="https://github.com/mdn/simple-addon/blob/gh-pages/js/index.js">JavaScript source on Github</a>.) It is injected into the apps it is applied to along with any CSS specified in the {{anch("manifest.json")}} file.</p> + +<div class="note"> +<p><strong>Note</strong>: Add-on code is injected every time an app is launched and the match specified in manifest.json pattern matches that app. It is also injected whenever add-ons are enabled. When an add-on is injected into an app because the app is launching, all add-on files are injected into the app before anything in the app is initialized, including the DOM. It is up to the add-on developer to handle the different launch cases cases (immediate injection vs. injection on launch); there is more info on this below.</p> +</div> + +<p>Other main things to note are covered below.</p> + +<h4 id="The_window_object">The window object</h4> + +<p>Add-ons only share a proxied version of the content <code>window</code>. As a result, anything that is written to the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window">window</a> object from an add-on is unavailable to the app code. However, anything on the <code>window</code> object that is set by app code is available to add-ons. Similarly, the DOM is accessible as usual.</p> + +<h4 id="Injecting_code_at_the_correct_time">Injecting code at the correct time</h4> + +<p>You must be careful to properly handle cases where an add-on is injected into an app after the app has been loaded. Such a scenario can occur when an app is already running and an add-on that targets it is enabled.</p> + +<p>in such a case, a <a href="https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload">window.onload</a> handler won't work because the <a href="https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> event has already occured.</p> + +<p>There's no good solution to this problem right now. In the interim, we recommend to check whether or not the DOM has been loaded before setting a <code>DOMContentLoaded</code> callback. This pattern is used in the demo:</p> + +<pre class="brush: js language-js"><code class="language-js"><span class="comment token">// If injecting into an app that was already running at the time +</span><span class="comment token">// the app was enabled, simply initialize it. +</span><span class="keyword token">if</span> <span class="punctuation token">(</span>document<span class="punctuation token">.</span>documentElement<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="function token">initialize<span class="punctuation token">(</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> +<span class="comment token"> +// Otherwise, we need to wait for the DOM to be ready before +</span><span class="comment token">// starting initialization since add-ons are usually (always?) +</span><span class="comment token">// injected *before* `document.documentElement` is defined. +</span><span class="keyword token">else</span> <span class="punctuation token">{</span> + window<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'DOMContentLoaded'</span><span class="punctuation token">,</span> initialize<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">function</span> <span class="function token">initialize<span class="punctuation token">(</span></span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token"> // ... +</span><span class="punctuation token">}</span></code></pre> + +<h4 id="避免重複植入">避免重複植入</h4> + +<p>為避免附加元件的程式碼多次重複植入到同一 App 中，您必須檢查附加元件是否曾經植入過，例如這樣</p> + +<p>you should check whether your add-on is already present, like this:</p> + +<pre class="brush: js language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">initialize<span class="punctuation token">(</span></span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>document<span class="punctuation token">.</span><span class="function token">querySelector<span class="punctuation token">(</span></span><span class="string token">'.fxos-banner'</span><span class="punctuation token">)</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token"> // Already injected, abort. +</span> <span class="keyword token">return</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> <span class="keyword token">else</span> <span class="punctuation token">{</span> + <span class="keyword token">var</span> body <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">querySelector<span class="punctuation token">(</span></span><span class="string token">'body'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> fxosBanner <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">createElement<span class="punctuation token">(</span></span><span class="string token">'div'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + fxosBanner<span class="punctuation token">.</span>classList<span class="punctuation token">.</span><span class="function token">add<span class="punctuation token">(</span></span><span class="string token">'fxos-banner'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> bannerText <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">createElement<span class="punctuation token">(</span></span><span class="string token">'p'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">var</span> closeBtn <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">createElement<span class="punctuation token">(</span></span><span class="string token">'button'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + + fxosBanner<span class="punctuation token">.</span><span class="function token">appendChild<span class="punctuation token">(</span></span>bannerText<span class="punctuation token">)</span><span class="punctuation token">;</span> + fxosBanner<span class="punctuation token">.</span><span class="function token">appendChild<span class="punctuation token">(</span></span>closeBtn<span class="punctuation token">)</span><span class="punctuation token">;</span> + body<span class="punctuation token">.</span><span class="function token">appendChild<span class="punctuation token">(</span></span>fxosBanner<span class="punctuation token">)</span><span class="punctuation token">;</span> + + closeBtn<span class="punctuation token">.</span>textContent <span class="operator token">=</span> <span class="string token">'X'</span><span class="punctuation token">;</span> + bannerText<span class="punctuation token">.</span>textContent <span class="operator token">=</span> <span class="string token">'Wow, you have an extension installed!'</span><span class="punctuation token">;</span> + + closeBtn<span class="punctuation token">.</span>onclick <span class="operator token">=</span> <span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + fxosBanner<span class="punctuation token">.</span>parentNode<span class="punctuation token">.</span><span class="function token">removeChild<span class="punctuation token">(</span></span>fxosBanner<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span></code></pre> + +<p>So here we are using <code>if (document.querySelector('.fxos-banner'))</code> to check whether the example banner already exists. If so, then we return out of the function. If not, then the <code>querySelector()</code> method returns <code>null</code>, and we run the code block that creates the banner.</p> + +<h4 id="App_management_functions_in_add-ons">App management functions in add-ons</h4> + +<p>All <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMApplicationsRegistry">Apps</a></code> and <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMApplicationsRegistry/mgmt">Mgmt</a></code> functions work on add-ons just like they do on apps. Be aware however that the latter are only available to add-ons when they are injected into a certified app that has the <code>webapps-manager</code> permission specified in the manifest.</p> + +<p>In addition to these functions, an <code><a href="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/Apps.webidl#141">onenabledstatechange</a></code> callback is exposed for add-ons being enabled and disabled. This event is fired for all add-ons, so you will have to check which add-on was enabled/disabled before performing initialization or cleanup.</p> + +<pre class="brush: js language-js"><code class="language-js">navigator<span class="punctuation token">.</span>mozApps<span class="punctuation token">.</span>mgmt<span class="punctuation token">.</span>onenabledstatechange <span class="operator token">=</span> <span class="keyword token">function</span><span class="punctuation token">(</span>event<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">var</span> app <span class="operator token">=</span> event<span class="punctuation token">.</span>application<span class="punctuation token">;</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>app<span class="punctuation token">.</span>manifestURL <span class="operator token">===</span> <span class="string token">'https://origin.of.manifest/manifest.webapp'</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">var</span> wasEnabled <span class="operator token">=</span> app<span class="punctuation token">.</span>enabled<span class="punctuation token">;</span> + <span class="comment token"> // do something with this information +</span> <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span></code></pre> + +<h3 id="extension.zip">extension.zip</h3> + +<div class="note"> +<p><strong>Note</strong>: The <code>extension.zip</code> file has been left in the demo repo mainly for illustrative purposes, so it is clear how the system works. You actually don't need to include the zip in your directory, as WebIDE will generate it for you when you install the add-on. The Firefox Marketplace is likely to do the same when it starts to list add-ons.</p> +</div> + +<p>The <code>extension.zip</code> archive contains the code for the extension, and is referenced in the {{anch("update.webapp")}} <code>package_path</code> field — This is how Gecko finds the code to be installed. Archived inside you'll find:</p> + +<ul class="directory-tree"> + <li>css/ + <ul> + <li>style.css</li> + </ul> + </li> + <li>js/ + <ul> + <li>index.js</li> + </ul> + </li> + <li>icons/ + <ul> + <li>128.png</li> + </ul> + </li> + <li>manifest.json</li> +</ul> + +<p>So the <code>manifest.json</code> file sits inside the archive, and serves to reference the files to be injected and specify which apps to affect.</p> + +<h3 id="Testing_your_add-on_using_WebIDE">Testing your add-on using WebIDE</h3> + +<p>Mozilla's WebIDE tool is available in Firefox desktop by default. To use it for installing add-ons on your phone, follow the steps listed below:</p> + +<ol> + <li>Make sure you have Firefox 43 or above installed (this was <a href="https://nightly.mozilla.org/">Nightly</a> at the time of writing), as add-ons are not supported in WebIDE below this version.</li> + <li>Open your browser and open the WebIDE tool (press the WebIDE button, or choose <em>Tools > Web Developer > WebIDE</em> from the menu.)</li> + <li>Make sure your phone has remote debugging enabled (<em>Settings App > Developer > Set the "Debugging via USB " selection to "ADB and DevTools".</em>)</li> + <li>Connect your phone to your computer via a USB cable. Make sure you don't have other phones connected at the same time.</li> + <li>In the WebIDE UI, press the <em>Select Runtime</em> option, and select your phone, which should be listed under <em>USB Devices</em>.</li> + <li>At this point, your phone should be showing an <em>Allow USB debugging connection?</em> prompt. Choose <em>Allow</em>.</li> + <li>Select the <em>Open App</em> option, then choose <em>Open Packaged App...</em></li> + <li>In the resulting file chooser, navigate to the directory that contains your <code>update.webapp</code> manifest file, and press <em>Open</em>.</li> + <li>Providing there are no warnings or errors reported, you can install your add-on on the device using the "Play" button in the center (<em>Install and Run</em>.)</li> + <li>To see the add-on in action, enable it by choosing <em>Settings app > Add-ons > Add-on example > toggle the checkbox at the top</em>.</li> +</ol> + +<h2 id="Add-on_settings">Add-on settings</h2> + +<p>You can control the add-ons on your phone by going to <em>Settings app > Add-ons</em>; in here you'll find a list of your installed add-ons, and you can tap each entry to see more information about each add-on.</p> + +<p style="width: 520px; margin: 0 auto;"><img alt="firefox os screenshot showing a list of installed add-ons in the settings app" src="https://mdn.mozillademos.org/files/11447/add-on-settings-screen.png" style="height: 445px; margin-right: 20px; width: 250px;"><img alt="information screen for an individual addon, with a list of apps this add-on affects, and controls to disable and delete the add-on" src="https://mdn.mozillademos.org/files/11449/individual-add-on-settings-page.png" style="height: 445px; width: 250px;"></p> + +<h3 id="Enablingdisabling_and_deleting_add-ons">Enabling/disabling and deleting add-ons</h3> + +<p>By default, add-ons will be enabled after installation when they are installed form the Firefox Marketplace. When installed via WebIDE however they will be disabled by default.</p> + +<p>You can manually enable/disable add-ons via the checkbox at the top of each individual add-on's page (found under <em>Settings app > Add-ons</em>), or programmatically using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMApplicationsManager/setEnabled">navigator.mozApps.mgmt.setEnabled()</a> function (see this <a href="https://github.com/fxos/directory/blob/master/app/js/controller/list_controller.js#L220-L223">setEnabled() usage example</a> on Github.)</p> + +<p>You can delete an add-on entirely by tapping the <em>Delete</em> button found on individual app pages.</p> + +<h3 id="Apps_affected_by_add-ons">Apps affected by add-ons</h3> + +<p>You'll also notice that in the page for each individual add-on there is a section that lists which apps are affected by that add-on. Currently this doesn't seem to work (it always lists <em>This add-on does not affect any installed apps</em>.) This should be fixed soon (see {{Bug(1196386)}} for progress.)</p> + +<h2 id="權限">權限</h2> + +<p>附加元件的權限繼承自其所植入的 App，在描述檔中想多要一點權限是行不通的，也無法以此方式增加其植入對象的權限。</p> |