Skip to main content

Visit Mozilla.org

chrome.manifest

From MDC


目录

[编辑] What is Chrome?

Chrome is the set of user interface elements of the application window that are outside of a window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome. 什么是chrome?(词典：铬, 铬合金.按工业来讲，也可以是镀铬，让镀件变得更亮丽，更耐用。chrome 是黑客的俚语（这里的黑客不是指进行非法勾当的人）。chrome 是从汽车工业的俚语来的，估计是给车子上光之类（抱歉我不懂机械）,在设计领域 chrome 的意思就是对系统功能没什么大的帮助，但是却能吸引用户的部分。Google工具栏将其翻译为“色彩增加、获得色彩”，我想跟不一样的眼睛的解释有些接近吧。[1])

按照字面翻译： chrome指的是应用程序窗口界面的所有UI元素(用户界面元素：典型的如工具条，菜单条，进度条，标题栏。)集合。通常他们都有一个URL或id来唯一标记,组合各种UI元素在一个XUL文件中就可以描述一个应用程序的窗口界面或其中的部分界面。(also see chromeURL：<profile folder>/localstore.rdf等中有比较完整的chromeURL,请在浏览器地址栏中粘贴这些URL回车后感性地认识一下这个chrome及其相关概念)

[编辑] Chrome Providers

A supplier of chrome for a given window type (e.g., for the browser window) is called a chrome provider. The providers work together to supply a complete set of chrome for a particular window, from the images on the toolbar buttons to the files that describe the text, contents and appearance of the window itself. chrome提供者：其责任是UI界面元素本身的描述(简单地组合他们可以描述一个应用程序的主窗口等界面)和事件响应的处理；UI界面元素中字符的各种语言版本的翻译处理；UI界面元素的式样处理(由CSS式样引擎处理)。

有三个基本的内容提供者类型:

[编辑] Content

主要的来自于内容提供者对窗口描述的源文件，它可以是任何Mozilla可显示的文件类型。通常是一个XUL file, since XUL is designed for describing the contents of windows and dialogs. javascript文件 that define the user interface are also contained within the content packages, as well as most XBL binding文件. 内容提供者：注意这里"内容"的含义(指UI界面元素本身的描述以及该元素的一些事件响应代码－由javascript代码提供)。内容文件大致两部分：xul描述UI界面元素文件＋js文件。

[编辑] Locale

Localizable applications keep all their localized information in locale providers. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. 两个主要的本地化文件类型是DTD files and java-style properties 文件. 本地化提供者：依据firefox_path/chrome/zh-CN(或en-US).jar 或在about:config中配置firefox具体语言版本，其中UI界面元素中的字符具体语言就是该提供者负责翻译。基本上提供多语言版本的程序处理UI界面上的字符的设计原理都比较类似：id标识后指向具体语言翻译描述文件(通常utf8格式)。

[编辑] Skin

A skin provider is responsible for providing a complete set of files that describe the visual appearance of the chrome. Typically a skin provider will provide CSS files and images. 皮肤提供者(类似wimnap等歌曲播放器一样，可以任意替换应用程序的外观－也就是皮肤skin。很多程序在设计时都提供这样的主题(类似os或字处理等中的表格主题的更换)接口。实际上skin皮肤 and theme主题是差不多的一个概念［至少表面上是这样的］):其责任是应用定义好的UI界面元素式样(例如dialog or button的字体大小，颜色，或背景图片等)描述文件*.css+*.jpg等,从而改变UI元素视觉外观。

[编辑] The Chrome Registry

gecko runtime维护了一个被称为chrome注册表的服务，它提供了chrome包名称到chrome包在磁盘的物理位置的映射.

这个chrome注册表示可以配置和持久化的, 因此用户可以安装不同的chrome providers, 选择合适的skin and locale. 这个市通过xpinstall和extension manager实现的.

为了告知chrome registry 可以访问的 chrome, 一个文本的manifest被使用: chrome.manifest。它在extension, 或者theme, 或者XULRunner application的chrome/*.manifest 根目录上.

The plaintext chrome manifests are a simple line-based format. Each line is parsed individually; 如果行是可以解析的，则chrome registry按照其要求进行配置，否则chrome registry会跳过这行(and prints a warning message in the runtime error console). 

locale packagename localename path/to/files
skin packagename skinname path/to/files

[编辑] Manifest Instructions

[编辑] Comments

注释行以'#'开头; any other characters on the line are ignored. 

# this line is a comment - you can put whatever you want here

[编辑] content

A content package is registered with the line 

content packagename uri/to/files/ [flags]

This will register a location to use when resolving the URI chrome://packagename/content/.... URI可以是绝对地址或者相对于chrome.manifest文件的位置. 注意，必须在最后加上'/'. cada:简单地先通过"工具|扩展"下载一个xpi扩展，查看该zip包中的manifest文件就明白了。另外在地址栏中按照如上格式键入xul文件回车看看效果。also see firefox本身的各种xul对应的UI元素：<profile folder>/localstore.rdf

[编辑] locale

A locale package is registered with the line 

locale packagename localename uri/to/files/ [flags]

This will register a locale package when resolving the URI chrome://packagename/locale/... . The localename is usually a plain language identifier "en" or a language-country identifier "en-US". If more than one locale is registered for a package, the chrome registry will select the best-fit locale using the user's preferences. cada:同上。(可能有些扩展没有locale定义)

[编辑] skin

A skin package is registered with the line 

skin packagename skinname uri/to/files/ [flags]

This will register a skin package when resolving the URI chrome://packagename/skin/... . The skinname is an opaque string identifying an installed skin. If more than one skin is registered for a package, the chrome registry will select the best-fit skin using the user's preferences. cada:同locale

[编辑] overlay

XUL overlays 注册方式如下: 

overlay chrome://URI-to-be-overlayed chrome://overlay-URI [flags]

cada:overlays技术：简单地可以对现有的如状态栏进行覆盖(overlay)修改，或在"工具"菜单下增加一些menuitem等,alike toolbars。

[编辑] style

Style overlays (custom CSS which will be applied to a chrome page) are registered with the following syntax: 

style chrome://URI-to-style chrome://stylesheet-URI [flags]

cada:这个通过"工具|主题"下载一个主题来看看其中的css style overlays。

[编辑] override

有时候扩展或者嵌入者希望覆盖一个应用或者XULRunner提供的chrome file. 为了达到这个目的, the chrome registration manifest allows for "override" instructions: 

override chrome://package/type/original-uri.whatever new-resolved-URI [flags]

【cada:注意区别override and overlay】

[编辑] Manifest Flags

Manifest 行可以带上多个，用空格分开的 flags 到行尾. 他们用来控制chrome的安装特性或者条件。

[编辑] application

Extensions 可以装到多个applications(cada标注：通常是指不同版本的mozilla应用程序)中. 你可以控制某行适用于特定的application. The flag 

application=app-ID

indicates that the instruction should only be applied if the extension is installed into the application identified by app-ID is running. 每一行可以包含多个application flags，只要其中一个满足就执行本行.

[编辑] appversion

扩展可以安装到应用的某些版本上。There may be chrome registration lines which only apply to a particular application version. The flag 

appversion=version
appversion<version
appversion<=version
appversion>version
appversion>=version

indicates that the instruction should only be applied if the extension is installed into the application version identified. Multiple appversion flags may be included on a single line, in which case the line is applied if any of the flags match. The version string must conform to the Toolkit version format.

[编辑] platform (Platform-specific packages)

平台相关包(xpi)规范:主要是不同平台上类似的UI元素有所差异(如布局顺序，名称不同) Some packages are marked with a special flag indicating that they are platform specific. Some parts of content, skin, locales may be different based on the platform being run. These packages contain three different sets of files, for windows/os2, macintosh, and unix-like platforms. For example, the order of the "OK" and "cancel" buttons on a dialog is different, as well as the name of some items.

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.

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

content global-platform jar:toolkit.jar!/toolkit/content/global-platform/ platform

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

[编辑] xpcnativewrappers

cada:安全保护机制 Chrome packages can decide whether to use the xpcnativewrappers security mechanism to protect their code against malicious content that they might access. See Safely accessing content DOM from chrome for details.

As of Firefox 1.5 alpha releases (Deer Park alphas), this flag is *off* by default, and must be explicitly enabled by specifying xpcnativewrappers=yes.

As of the first Firefox 1.5 beta release, this flag will be enabled by default, and extensions that need insecure access to the content objects will be required to specify xpcnativewrappers=no.

The xpcnativewrappers flag applies only to content packages: it is not recognized for locale or skin registration.

[编辑] Example Chrome Manifest 

content       necko                   jar:comm.jar!/content/necko/ xpcnativewrappers=yes
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 chrome://browser/content/pageInfo.xul           chrome://pippki/content/PageInfoOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
overlay chrome://communicator/content/pref/preftree.xul chrome://pippki/content/PrefOverlay.xul
overlay chrome://navigator/content/pageInfo.xul         chrome://pippki/content/PageInfoOverlay.xul application=seamonkey@applications.mozilla.org
content       pippki                  jar:pippki.jar!/content/pippki/ xpcnativewrappers=yes
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 chrome://global/content/netError.xhtml jar:embedder.jar!/global/content/netError.xhtml
content       inspector               jar:inspector.jar!/content/inspector/ xpcnativewrappers=no

[编辑] Old-style contents.rdf manifests

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, the Mozilla Suite (SeaMonkey) does not support the plaintext manifest format yet, so contents.rdf manifests are required for extensions that wish to maintain backwards compatibility with Firefox 1.0 or the suite.

[编辑] Official References for Toolkit API

取自"http://developer.mozilla.org/cn/docs/chrome.manifest"