path: root/files/zh-tw/mozilla/chrome_registration/index.html

---
title: Chrome registration
slug: Mozilla/Chrome_Registration
translation_of: Mozilla/Chrome_Registration
---
<h2 id="What_is_Chrome.3F" name="What_is_Chrome.3F">馬桶裡有個 chrome?</h2>

<p><a href="/en/Chrome" title="en/Chrome">Chrome</a> 是一拖拉庫在文件 window 範圍之外 AP 視窗的 UI 元件。 管它 Toolbars 、 menu bars、progress bars 還是 window title bars 基本上都是 chrome 的一部份。</p>

<div class="note">
<p>Mozilla 會尋找並讀取主題佈景和附加元件根目錄<code>的 chrome.manifest</code> 檔。</p>
</div>

<div class="note">
<p>古早的 Gecko 1.9.2 (及更古早版本)，Mozilla 是從 AP 讀取<code>chrome/*.manifest</code> 檔。 從 Gecko 2.0 {{ geckoRelease("2.0") }} 開始，就只剩根目錄的 <code>chrome.manifest</code> 還有再用；若要增加更多的內容，就在其中利用 <a href="/en/Chrome_Registration#manifest" title="en/Chrome Registration#manifest"><code>manifest</code></a> 指令來擴充。</p>
</div>

<h2 id="Chrome_Providers" name="Chrome_Providers">Chrome providers</h2>

<p>基於某種 window type (例如針對 browser window) 提供 chrome 者稱為 chrome provider。所有的 provider 同心協力針對特定的 window 提供整套的 chrome，從工具列上的圖案到文字或內容描述檔，以及 window 本身的外觀。</p>

<p>以下是三種基本的 chrome provider ：</p>

<dl>
 <dt>Content</dt>
 <dd>視窗描述主要是來自於 content provider，格式可以是任何一種 Mozilla 看得懂的類型。通常會是個  XUL file，因為它本來就是專門設計來描述 window 和 dialog 的。用來定義 UI 的 JavaScript 檔也會跟在這包，多數的 XBL binding files 也是。</dd>
 <dt>Locale</dt>
 <dd>多語系的應用程式會將語系資訊交給 locale providers。醬子譯者就可以翻譯並插進一個另外的 chrome package 而不去更動其它的程式。Java-style properties 檔和 DTD 檔是兩種主要的多語系檔案類型。</dd>
 <dt>Skin</dt>
 <dd>Skin provider 就負責 chrome 整套外觀的描述檔，通常是 CSS 和圖形。</dd>
</dl>

<div class="note">
<p><strong>註:</strong> 從 skin packages 載入的 scripts (包括 <a href="/en/XBL" title="en/XBL">XBL </a>裡的) 並不會執行喔。</p>
</div>

<h2 id="The_Chrome_Registry" name="The_Chrome_Registry">Chrome 登錄 (chrome registry)</h2>

<p>Gecko runtime 會保持一份稱為 chrome registry 的記錄，用來對登錄 chrome package 名稱和實際檔案路徑。</p>

<p>Chrome registry 可以設定並且會保存；且有賴於 xpinstall 和 extension manager，這樣 user 就可以很多套 chrome provider 然後選擇喜歡的語系和外觀。</p>

<p>XULRunner application、主題布景或附加元件要讓 chrome registry 知道有這麼一個 chrome，那就要在自己的根目錄下放一個 純文字格式的 manifest，也就是 `chrome.manifest`。</p>

<p>這個純文字的 manifests 是簡單的逐行格式，會被一行一行地解析。 chrome registry 看懂一行就處理一行，看不懂就跳過；當然，有問題的會 log 在 console 中。</p>

<pre>locale packagename localename path/to/files
skin packagename skinname path/to/files
</pre>

<p></p><div class="warning">Firefox 2 、 Thunderbird 2 和 SeaMonkey 1.1 無法辨識大小寫夾雜的 <code>packagename</code> 。 要是把範例中的 <code>packagename </code>改成 <strong>C</strong>amel<strong>C</strong>ase<strong>P</strong>ackage 就會跑出類似 "No chrome registered for chrome://<strong>c</strong>amel<strong>c</strong>ase<strong>p</strong>ackage/path/to/files" 的訊息。 Firefox 3 、 Thunderbird 3 還有 SeaMonkey 2 已經支援這個功能。Bug resolved 於 Mozilla 1.9; see {{bug(132183)}}.</div><p></p>

<h2 id="Manifest_Instructions" name="Manifest_Instructions">Manifest 指令</h2>

<h3 id="comments" name="comments">comments</h3>

<p>如果一行的開頭是 '#' 那這整行就變成註解。</p>

<pre class="eval"># this line is a comment - you can put whatever you want here
</pre>

<h3 id="manifest" name="manifest">manifest</h3>

<p>{{ gecko_minversion_inline("2.0b4") }}</p>

<pre>manifest <em>subdirectory/foo.manifest [flags]</em>
</pre>

<p>這行會載入另一份 manifest 檔。這在拆分元件、chrome 登錄項或是各平台相依登錄資料時尤其有用。</p>

<h3 id="binary-component">binary-component</h3>

<p>{{ gecko_minversion_inline("2.0b2") }}</p>

<pre>binary-component <em>components/mycomponent.dll [flags]</em>
</pre>

<p>叫 Mozilla 登錄並應用 binary component，由於 binary components 為 ABI-specific，應與 abi flag 並用。 <a href="/en/XPCOM/XPCOM_changes_in_Gecko_2.0" title="en/XPCOM/XPCOM changes in Gecko 2.0">在 Firefox 4 之前 </a>，components 資料夾裡的檔案會自動被登錄。</p>

<h3 id="interfaces">interfaces</h3>

<p>{{ gecko_minversion_inline("2.0b2") }}</p>

<pre>interfaces <em>component/mycomponent.xpt [flags]</em>
</pre>

<p>叫 Mozilla 從經由 XPIDL 產生的 typelib 檔載入 interface 資訊。<a href="/en/XPCOM/XPCOM_changes_in_Gecko_2.0" title="en/XPCOM/XPCOM changes in Gecko 2.0">在 Firefox 4 之前</a>，components 資料夾裡的檔案會自動被登錄。</p>

<h3 id="component">component</h3>

<p>{{ gecko_minversion_inline("2.0b2") }}</p>

<pre>component <em>{00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags]</em>
</pre>

<p>告訴 Mozilla 一個由 XPCOM 元件以 JavaScript (或是其它可接受的 scripting language) 實作之元件的 CID。ClassID {0000 ...} 一定要和該元件所實現的 ClassID 相同。可利用程式或線上 UUID 產生器產生唯一的 ClassID。</p>

<h3 id="contract">contract</h3>

<p>{{ gecko_minversion_inline("2.0b2") }}</p>

<pre>contract <em>@foobar/mycontract;1 <em>{00000000-0000-0000-0000-000000000000} [flags]</em></em>
</pre>

<p>將特定實作的 contract ID (一個語意化字串) 對應到 ClassID。通常 contract ID 就和它頂頭所列的 component entry 一組。<br>
  </p>

<h3 id="content" name="content" style="min-height: 0;">category</h3>

<p>{{ gecko_minversion_inline("2.0b2") }}</p>

<pre>category <em>category entry-name value [flags]</em>
</pre>

<p>登錄在 <a href="/en/XPCOM_Interface_Reference/nsICategoryManager" title="en/XPCOM Interface Reference/nsICategoryManager">category manager</a> ，至於項目的格式和用意就要看它是哪個 category 了。</p>

<h3 id="content" name="content" style="min-height: 0;">content</h3>

<p>下面這行登錄一個 content package ：</p>

<pre>content <em>packagename</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>

<p>這會將 package 登錄在一個像 <code>`chrome://<em>packagename</em>/content/..` </code>的位置，也就是之後它被存取的位置。這個 URI 可以是絕對位置或是相對於 manifest file 的位置，但要注意結尾的 '/' 不可省略。</p>

<h3 id="locale" name="locale">locale</h3>

<p>下面這行登錄一個 locale package ：</p>

<pre class="eval">locale <em>packagename</em> <em>localename</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>

<p>這會將 locale package 登錄在解析 `chrome://<em>packagename</em>/locale/..` 所用的位置。<em> localename</em> 通常直接用語系名稱像是 "zh" 或有時候用 語系-地區 像 "zh-TW"。如果同一 package 有多個語系 chrome registry 會根據使用者偏好中的設定值選擇最接近的語系。</p>

<h3 id="skin" name="skin">skin</h3>

<p>下面這行登錄一個 skin package ：</p>

<pre class="eval">skin <em>packagename</em> <em>skinname</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>

<p>這會將 skin package 登錄在 <a class="external" rel="freelink">chrome://packagename/skin/</a>.. ，<em> skinname</em> is 是用來識別所安裝 skin 的一個非透明化字串。同樣地，若同一 package 登記了多個 skin ， chrome registry 會根據使用者偏好中的設定值選擇最合適的。</p>

<h3 id="style" name="style">style</h3>

<p>Style overlay (套用在chrome page上的自訂 CSS) 以下列語法登錄：</p>

<pre class="eval">style chrome://<em>URI-to-style</em> chrome://<em>stylesheet-URI</em> <em>[flags]</em>
</pre>

<div class="note">注意： 只有位於 chrome URI 的 stylesheet 可以這樣用。</div>

<h3 id="override" name="override">override</h3>

<p>chrome 登錄 manifest 允許 override 指令以便讓某些 extension 或其它嵌入物件可以改寫 XULRunner 或 AP 預設的 chrome file 設定。</p>

<pre class="eval">override chrome://<em>package</em>/<em>type</em>/<em>original-uri.whatever</em> <em>new-resolved-URI</em> <em>[flags]</em>
</pre>

<p>注意：override 路徑不會遞迴 (所以將 <a class="external" rel="freelink">chrome://foo/content/bar/</a> override 為 <a class="external" rel="freelink">file:///home/john/blah/</a> 之後，其行為通常不會是預期的那樣)。而且 override 之後路徑是相對於被重寫掉的路徑而不是用來重寫的路徑 (從 CSS 的角度來說，這搞不好是個偏門也搞不好使人抓狂) 。</p>

<div class="note">
<p>在 Gecko 1.8.1.5 (Firefox 2.0.0.5) 和較早的版本中有個 <em>new-resolved-URI</em> 參數 只能用絕對路徑而不能用相對路徑的 bug。詳見： {{ Bug(323455) }}.</p>
</div>

<h3 id="resource" name="resource">resource</h3>

<p>{{ Fx_minversion_inline("3") }}</p>

<p>在 extension 和 AP 中使用<a href="/en/Components.utils.import" title="en/Components.utils.import"> Components.utils.import</a> 來載入 <a href="/en/JavaScript_code_modules/Using" title="en/Using_JavaScript_code_modules">JavaScript code modules</a> 時，建立 resource protocol 別名 (aliases) 有時是必須的。請使用 <code>resource</code> 指令來建立別名：</p>

<pre class="eval">resource <em>aliasname</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>

<p>這會將目的路徑對映到 <code>resource://&lt;aliasname&gt;<span style="font-family: Verdana,Tahoma,sans-serif;">/</span></code>.. 。</p>

<div class="note">
<p><span class="short_text" id="result_box" lang="zh-TW"><span>並</span><span>沒有安全性</span><span>限制防止</span><span>網頁內容</span><span> include 以 resource: 開頭</span><span>的 URI</span><span>，故</span><span>請留意此處所開啟的能見度</span><span>。</span></span></p>
</div>

<h2 id="Manifest_Flags" name="Manifest_Flags">Manifest 旗號</h2>

<p>Manifest 指令行允許多個以空白分隔的旗號附加於行尾。這些旗號將會設定 package 中 chrome 的特殊屬性，或限制這些指令行本身於什麼條件下作用。</p>

<h3 id="application" name="application">application</h3>

<p>Extension 可以安裝於多個應用程式，而有些 chrome registration 可能只需作用於特定的應用程式。以下旗號</p>

<pre class="eval">application=<em>app-ID</em>
</pre>

<p>代表這個指令只應在 extension 安裝於符合 <em>app-ID </em>的應用程式時作用。同一行可以指定多個應用程式，此時只要其中一項符合即會作用。</p>

<p>以下示範如何為多個應用程是分別指定 overlay ：</p>

<pre>overlay chrome://browser/content/browser.xul chrome://myaddon/content/ffOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
overlay chrome://messenger/content/mailWindowOverlay.xul chrome://myaddon/content/tbOverlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6}
overlay chrome://songbird/content/xul/layoutBaseOverlay.xul chrome://myaddon/content/sbOverlay.xul application=songbird@songbirdnest.com
</pre>

<h3 id="appversion" name="appversion">appversion</h3>

<p>Extension 可以安裝於同一應用程式的多個不同版本，而有些 chrome registration 可能只需作用於特定的版本。以下旗號</p>

<pre class="eval">appversion=<em>version</em>
appversion&lt;<em>version</em>
appversion&lt;=<em>version</em>
appversion&gt;<em>version</em>
appversion&gt;=<em>version</em>
</pre>

<p>代表這個指令只應在 extension 安裝於符合特定版本的應用程式時作用。同一行可以指定多個 <code>appversion</code> ，此時只要其中一項符合即會作用。版本字串應遵循 <a href="/en/Toolkit_version_format" title="en/Toolkit_version_format">Toolkit version format</a> 。</p>

<div class="note">
<p>Gecko 在 1.8.0.13 之前以及版本 1.8.1.5 有一個 bug ， 就是本字串必須超過一個字元(也就是最少兩個) 才能使用 &lt; 、 &gt; 及 =，否則會在 console 中收到<code> appversion</code> flag was not recognized 的錯誤訊息。參見： {{ Bug(380398) }} 。</p>
</div>

<h3 id="platformversion" name="platformversion">platformversion</h3>

<p>{{ gecko_minversion_inline("8.0") }} 當附加元件尤其是 binary components支援一種以上的應用程式時，若能指定所相容的 Gecko 版本將為其帶來更多的方便性。若某些 chrome registration 只作用於定特定 Gecko 版本，以下旗號</p>

<pre class="eval">platformversion=<em>version</em>
platformversion&lt;<em>version</em>
platformversion&lt;=<em>version</em>
platformversion&gt;<em>version</em>
platformversion&gt;=<em>version</em>
</pre>

<p>代表這個指令只應在 extension 安裝於符合特定 Gecko 版本的應用程式時作用。同一行可以指定多個 <code>platformversion</code>，此時只要其中一項符合即會作用。</p>

<h3 id="contentaccessible" name="contentaccessible">contentaccessible</h3>

<p>{{ Fx_minversion_inline("3") }} Chrome resources 已不能被非信任來源內容中的 &lt;img&gt;、&lt;script&gt; 及其他包含或添加的 elements 所參照。 這個限制不僅適用於非信任來源中所定義的 elements ， 同時也適用於受信任的附加元件中所定義的 elements。若參照需要明確地被允許，請將 <code>contentaccessible</code> 旗號設定為 <code>yes</code> 來達到如舊版 Firefox 中的行為。 <span class="comment">See {{ bug("4369")}}</span></p>

<p><code>contentaccessible</code> 只能用於 content package ，言下之意，它不會被 locale 或 skin registration 所識別。好在於 content package 所對應到的 locale 和 skin packages 對 content 而言是可見的。</p>

<p>注意：由於舊版的 Firefox 根本看不懂 <code>contentaccessible</code> flag ， 若要讓附加元件同時支援 Firefox 3 及古董版的話就得來個倒退嚕，您倒是看看：</p>

<pre>content packagename chrome/path/
content packagename chrome/path/ contentaccessible=yes
</pre>

<h3 id="os" name="os">os</h3>

<p>{{ Fx_minversion_inline("3") }} Extensions (or themes) may offer different features depending on the operating system on which Firefox is running. The value is compared to the value of <a href="/en/OS_TARGET" title="en/OS_TARGET">OS_TARGET</a> for the platform.</p>

<pre class="eval">os=WINNT
os=Darwin
</pre>

<p>See <a href="/en/OS_TARGET" title="en/OS_TARGET">OS_TARGET</a> for a more complete list of os names. The os name is case insensitive.</p>

<h3 id="osversion" name="osversion">osversion</h3>

<p>{{ Fx_minversion_inline("3") }} An extension or theme may need to operate differently depending on which version of an operating system is running. For example, a theme may wish to adopt a different look on Mac OS X 10.5 than 10.4:</p>

<pre class="eval">osversion&gt;=10.5
</pre>

<h3 id="platform_.28Platform-specific_packages.29" name="platform_.28Platform-specific_packages.29">abi</h3>

<p>{{ Fx_minversion_inline("4") }} If a component is only compatible with a particular ABI, it can specify which ABI/OS by using this directive. The value is taken from the <a href="/en/XPCOM_Interface_Reference/nsIXULRuntime" title="https://developer.mozilla.org/en/nsIXULRuntime">nsIXULRuntime</a> OS and XPCOMABI values (concatenated with an underscore). For example:</p>

<pre>binary-component component/myLib.dll abi=WINNT_<code>x86-MSVC
</code>binary-component component/myLib.so abi=Linux_<code>x86-gcc3 </code>
</pre>

<p>See <a href="/en/XPCOM_ABI" title="en/XPCOM ABI">XPCOM ABI</a> for more details.</p>

<h3 id="platform_.28Platform-specific_packages.29" name="platform_.28Platform-specific_packages.29">platform (Platform-specific packages)</h3>

<p>Some packages are marked with a special flag indicating that they are platform specific. Some parts of content, skin, and locales may be different based on the platform being run. These packages contain three different sets of files, for Windows and OS/2, Macintosh, and Unix-like platforms. For example, the order of the "OK" and "Cancel" buttons in a dialog is different, as well as the names of some items.</p>

<p>The "platform" modifier is only parsed for content registration; it is not recognized for locale or skin registration. However, it applies to content, locale, and skin parts of the package, when specified.</p>

<p>To indicate that a package is platform-specific, add the "platform" modifier to the "content" line after the path, for example:</p>

<pre class="eval">content global-platform jar:toolkit.jar!/toolkit/content/global-platform/ platform
</pre>

<p>Once that is specified in your manifest you then ensure that under the directory global-platform are subdirectories <code>win</code> (Windows/OS2), <code>mac</code> (OS9/OSX), or <code>unix</code> (Everything Else). Anything residing outside of these subdirectories will be ignored.</p>

<h3 id="xpcnativewrappers" name="xpcnativewrappers">xpcnativewrappers</h3>

<p>Chrome packages can decide whether to use the <a href="/en/XPCNativeWrapper" title="en/XPCNativeWrapper">XPCNativeWrapper</a> security mechanism to automatically protect their code against malicious content that they might access. See <a href="/en/Safely_accessing_content_DOM_from_chrome" title="en/Safely_accessing_content_DOM_from_chrome">Safely accessing content DOM from chrome</a> for details.</p>

<p>This flag is enabled by default since Firefox 1.5. Disabling it manually was possible by specifying <code>xpcnativewrappers=no</code> until Firefox 4.</p>

<div class="geckoVersionNote">
<p>{{ gecko_callout_heading("2.0") }}</p>

<p>Support for this flag has been removed in Gecko 2.0 {{ geckoRelease("2.0") }}. You can no longer disable <code>XPCNativeWrapper</code>s. To update your add-on to work without this flag:</p>

<ul>
 <li>If your add-on depends upon XBL bindings attached to content objects (that is, it needs to be able to call functions or get and set properties created by the XBL binding), you'll need to use the object's <a href="/en/wrappedJSObject" title="en/wrappedJSObject"><code>wrappedJSObject</code></a> property to obtain a wrapped object.</li>
 <li>If you need to call functions or access properties defined by the content -- for example, if your add-on wants to add a button to the page that calls a JavaScript function defined by the page.</li>
</ul>
</div>

<p>The <code>xpcnativewrappers</code> flag applies only to content packages; it is not recognized for locale or skin registration.</p>

<h2 id="Example_Chrome_Manifest" name="Example_Chrome_Manifest">Example chrome manifest</h2>

<pre class="eval">content       necko                   jar:comm.jar!/content/necko/
locale        necko       en-US       jar:en-US.jar!/locale/en-US/necko/
content       xbl-marquee             jar:comm.jar!/content/xbl-marquee/
content       pipnss                  jar:pipnss.jar!/content/pipnss/
locale        pipnss      en-US       jar:en-US.jar!/locale/en-US/pipnss/
# Firefox-only
overlay <a class="external" rel="freelink">chrome://browser/content/pageInfo.xul</a>           <a class="external" rel="freelink">chrome://pippki/content/PageInfoOverlay.xul</a> application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
# SeaMonkey-only
overlay <a class="external" rel="freelink">chrome://navigator/content/pageInfo.xul</a>         <a class="external" rel="freelink">chrome://pippki/content/PageInfoOverlay.xul</a> application={92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}
overlay <a class="external" rel="freelink">chrome://communicator/content/pref/preftree.xul</a> <a class="external" rel="freelink">chrome://pippki/content/PrefOverlay.xul</a>
content       pippki                  jar:pippki.jar!/content/pippki/
locale        pippki      en-US       jar:en-US.jar!/locale/en-US/pippki/
content       global-platform         jar:toolkit.jar!/content/global-platform/ platform
skin          global      classic/1.0 jar:classic.jar!/skin/classic/global/
override <a class="external" rel="freelink">chrome://global/content/netError.xhtml</a> jar:embedder.jar!/global/content/netError.xhtml
content       inspector               jar:inspector.jar!/content/inspector/
</pre>

<h2 id="Instructions_supported_in_bootstrapped_add_ons" name="Instructions_supported_in_bootstrapped_add_ons">Instructions supported in bootstrapped add-ons</h2>

<p>The following instructions are supported in <a href="/en/Extensions/Bootstrapped_extensions" title="en/Extensions/Bootstrapped extensions">Bootstrapped extensions</a>:</p>

<ul>
 <li><code>manifest</code></li>
 <li><code>content</code></li>
 <li><code>locale</code></li>
 <li><code>skin</code></li>
 <li><code>override</code></li>
</ul>

<h2 id="Debugging_a_Chrome_Manifest_file" name="Debugging_a_Chrome_Manifest_file">Debugging a chrome manifest file</h2>

<p>The <a class="link-https" href="https://addons.mozilla.org/firefox/addon/chrome-list">Chrome List</a> extension (for Firefox 3.6 and older) shows all registered chrome. This is very helpful when trying to write a <code>chrome.manifest</code> file as you can inspect where the files are being mapped from (jar files, local directory, etc.)</p>

<h2 id="Old-style_contents.rdf_manifests" name="Old-style_contents.rdf_manifests">Old-style contents.rdf manifests</h2>

<p>Before the plaintext manifests were introduced (which happened in Firefox 1.5, Toolkit 1.8), RDF manifests named "contents.rdf" were used to register chrome. This format is deprecated; however, SeaMonkey versions before version 2 do not support the plaintext manifest format yet, so <code>contents.rdf</code> manifests are required for extensions that wish to maintain backwards compatibility with Firefox 1.0 or the suite.</p>

<p>{{ gecko_minversion_note("1.9.2", "The <code>contents.rdf</code> manifest format is no longer supported at all starting with Gecko 1.9.2; add-ons already installed using this format will continue to work but can no longer be installed. Be sure to remove your add-on and reinstall it to ensure that it installs correctly after updating it to use a plaintext manifest.") }}</p>

<h2 id="Official_References_for_Toolkit_API" name="Official_References_for_Toolkit_API">Official references for <a href="/en/Toolkit_API" title="en/Toolkit_API">Toolkit API</a></h2>

<p>{{ page("en-US/docs/Toolkit_API/Official_References") }}</p>

<p>{{ languages( { "fr": "fr/Enregistrement_chrome", "ja": "ja/Chrome_Registration", "pl": "pl/Rejestracja_Chrome" ,"zh-cn":"zh-cn/Chrome_Registration"} ) }}</p>