所有扩展(包括:可安装的WebApp,皮肤), 都有一个 JSON 格式的清单(manifest)文件,叫 manifest.json 包含所有重要的信息
下面的脚本演示了所有支持的字段,每个字段都有下述对应的说明。
// 必须 Required
“name”: “My Extension”,
“version”: “versionString”,
“manifest_version”: 2,
// 建议 Recommended
“description”: “A plain text description”,
“icons: { ... },
“default_locale”: “en”,
// 选一(或不用) Pick one (or none)
“browser_action”: {...},
“page_action”: {...},
“theme”: {...},
“app”: {...},
// 根据需要 Add any of these that you need
“background”: {...},
“chrome_url_overrides”: {...},
“content_scripts”: [...],
“content_security_policy”: “policyString”,
“file_browser_handlers”: [...],
“homepage_url”: “http://path/to/homepage”,
“incognito”: “spanning” or “split”,
“key”: “publicKey”,
“minimum_chrome_version”: “versionString”,
“nacl_modules”: [...],
“offline_enabled”: true,
“omnibox”: { “keyword”: “aString” },
“options_page”: “aFile.html”,
“permissions”: [...],
“plugins”: [...],
“requirements”: {...},
“update_url”: “http://path/to/updateInfo.xml”,
“web_accessible_resources”: [...]
}
逐一解说各个字段,如果需要完整的字段列表,可以看这个 链接 :Field summary 有整体的描述
可安装的webapp,包括打包过的app,需要这个字段来指定app需要使用的url。 最重要的是app的启动页面——当用户在点击app的图标后,浏览器将导航到的地方。
更详细的信息,请参考文档 hosted apps 和 packaged apps
指定这个扩展保的缺省字符串的子目录: _lcoales 。
具体见: 国际化
描述扩展的一段文字(不能是html或者其他格式,不能超过132个字符)。 这个描述必须对扩展的管理界面和 Chrome网上应用店 都合适。
可以指定本地相关的字符串,具体见: 国际化
扩展的主页 URL . 扩展的管理界面里面将有一个链接指向这个 URL 。 如果将扩展放在自己的网站上,这个 URL 就很有用了。 如果你通过了 Extensions Gallery 和 Chrome网上应用店 来分发扩展,缺省主页就是扩展所属的页面。
扩展,web app,和皮肤 需要至少一个图标来表示。 - 通常我们可以提供一个128x128的图标,用以在 `Chrome网上应用店`_展示 - 扩展需要一个48x48的图标,管理页面需要这个图标。 - 同时,还可以提供给一个16x16的图标作为扩页面的 `Favicon`_ ~ 网页图标 - 这个16x16的图标,还将显示在实验性的 扩展infobar 特性上。
图标要求是png格式,因为这是对透明支持最好的格式。 也可以用其他 WebKit 支持的格式,如BMP,GIF,ICON和JPEG。下面有个例子:
"icons": { "16": "icon16.png",
"48": "icon48.png",
"128": "icon128.png" },
Note
注意:请只使用文档说明的图标大小
如果使用 Chrome开发者信息中心 上传的扩展、app、皮肤, 需要上传附带的图片,包括至少一张扩展的缩略图。
更多信息请参考 : Chrome 应用店开发手册
可选值:”spanning”和”split”,指定当扩展在允许隐身模式下运行时如何响应。
扩展的缺省值是 “spanning” ,这意味着扩展将在一个共享的进程里面运行。 隐身标签页的事件和消息都会发送到这个共享进程,来源通过incognito标志来区分。
可安装的webapp的缺省值是 “split”,意思是隐身模式下的webapp都将运行在他们自己的隐身进程中。 如果app或扩展有背景页面,也将运行在隐身进程中。 隐身进程和普通进程一样,只是cookie保存在内存中而已。 每个进程只可看到和自己相关的事件和消息(比如,隐身进程只能看到隐身标签也更新)。 这些进程之间不能互相通信 。
根据经验:
指定这一扩展程序或应用程序提供的所有 Intent 处理程序的词典,词典中的每一个键指定这一扩展程序处理的动作谓语。 以下例子为动作谓语”http://webintents.org/share“指定两个处理程序。
{
"name": "测试",
"version": "1",
"intents": {
"http://webintents.org/share": [
{
"type": ["text/uri-list"],
"href": "/services/sharelink.html",
"title" : "Sample Link Sharing Intent",
"disposition" : "inline"
},
{
"type": ["image/*"],
"href": "/services/shareimage.html",
"title" : "Sample Image Sharing Intent",
"disposition" : "window"
}
]
}
}
“type” 的值为这一处理程序支持的 MIME 类型数组, “href” 指示处理该 Intent 的页面 `URL_ 。 对于托管应用程序,这些 `URL`_ 必须包含在允许的 URL 中。 对于扩展程序,所有 URL 必须在扩展程序中,并且认为相对于扩展程序根 URL 。
当用户执行这一处理程序的操作时 “title” 将在 Intent 选择器用户界面中显示。 “disposition” 可以为 `”inline” 或 “window” 。 使用 “window” 方式的 Intent 调用时将打开新标签页,而使用 “inline” 方式调用时会显示在 Intent 选择器中。
更多信息,请参考 Web Intents规范 <http://dvcs.w3.org/hg/web-intents/raw-file/tip/spec/Overview.html> 与 webintents.org <http://www.webintents.org/>
Web Intents可以注册为内容类型的查看器,如果要这么做,动作谓语必须为”http://webintents.org/view“,内容类型必须为白名单中的 MIME 类型。
加入白名单中的MIME类型:
- application/rss+xml
- application/atom+xml
在开发阶段,这个值可以作为扩展、app和皮肤的唯一标示来使用。
要获得合适的键值,首先从 .crx 文件安装扩展程序(可能需要上传您的扩展程序或手工打包)。 然后,在配置文件目录中,查看如下文件: Default/Extensions/<extensionId>/<versionString>/manifest.json 将会看到填在此处的键值。
设定本地客户端模块处理各种MIME类型的映射.
例如,下面代码片段中高亮部分, 为电子表格注册MIME类型,并指定本机OpenOffice的程序客户端作为内容处理模块
{
"name": "Native Client OpenOffice Spreadsheet Viewer",
"version": "0.1",
"description": "Open OpenOffice spreadsheets, right in your browser.",
"nacl_modules": [{
"path": "OpenOfficeViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
}]
}
“path” 的值是原生客户端清单文件(Native Client manifest, .nmf 为后綴的文件file) 在扩展中的路径.
更多 .nmf 的信息, 参考: Native Client Technical Overview
每一 MIME 类型可以与一个 .nmf`文件结合. 不过,一个 `.nmf 文件可处理多个 MIME 类型.
下面的例子显示了两个 .nmf 文件处理三个 MIME 类型的扩展。
{
"name": "Spreadsheet Viewer",
"version": "0.1",
"description": "Open OpenOffice and Excel spreadsheets, right in your browser.",
"nacl_modules": [{
"path": "OpenOfficeViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
},
{
"path": "OpenOfficeViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
},
{
"path": "ExcelViewer.nmf",
"mime_type": "application/excel"
}]
}
Note
注意
包含该扩展程序或应用程序需要使用的权限的数组。 每一个权限既可以是已知字符串列表中的某一个(例如 “geolocation”), 或者授予访问一个或多个主机权限的匹配表达式。
权限可以帮助我们在扩展程序或应用程序受到攻击时尽可能减小损失, 某些权限也会在安装前向用户显示,这些将在 权限警告 中详细描述。
如果某个扩展程序API需要清单文件中声明某个权限,它的文档会告诉我们如何去做。 例如, 标签页 页面会演示如何声明 “tabs” 权限。
如下是一个扩展程序清单文件的权限部分的例子:
"permissions": [
"tabs",
"bookmarks",
"http://www.blogger.com/",
"http://*.google.com/",
"unlimitedStorage"
],
下表列出了扩展程序或打包应用程序可以使用的权限。
Note
注意
托管应用程序可以使用 “background” 、 “clipboardRead” 、 “clipboardWrite” 、 “geolocation” 、 “notification” 和 “unlimitedStorage” 权限,但不能使用下表列出的其它任何权限。
权限 | 描述 |
---|---|
匹配表达式 | 指定主机权限。如果扩展程序需要与页面上运行的代码交互则必须指定该权限。许多扩展程序的能力,例如 跨站XMLHttpRequest 、以编程方式插入 内容脚本 以及 Cookie API 需要主机权限。有关语法上的细节,请参见 匹配表达式 |
“background” | |
“bookmarks” | 如果扩展程序使用 chrome.bookmarks 模块则必须指定该权限。 |
“chrome://favicon/” | 如果扩展程序使用chrome://favicon/url机制来显示页面的收藏夹图标则必须指定该权限。
|
“clipboardRead” | 如果扩展程序使用 `document.execCommand(‘paste’)`则必须指定该权限 |
“clipboardWrite” | 指定应用程序或扩展程序可以使用 document.execCommand(‘copy’) 或 document.execCommand(‘cut’) 。 托管 应用程序 必须 指定该权限,同时建议扩展程序和打包应用程序指定该权限。 |
“contentSettings” | 如果扩展程序使用 chrome.contentSettings 模块则必须指定该权限 |
“contextMenus” | 如果扩展程序使用 chrome.contextMenus 模块则必须指定该权限 |
“cookies” | 如果扩展程序使用 chrome.cookies 模块则必须指定该权限 |
“experimental” | 如果扩展程序使用 chrome.experimental.* APIs 模块则必须指定该权限 |
“fileBrowserHandler” | 如果扩展程序使用 chrome.fileBrowserHandler 模块则必须指定该权限 |
“geolocation” | 允许扩展程序使用提出的HTML5 地理位置API 而不用提示用户 |
“history” | 如果扩展程序使用 chrome.history 模块则必须指定该权限 |
“idle” | 如果扩展程序使用 chrome.idle 模块则必须指定该权限 |
“management” | 如果扩展程序使用 chrome.management 模块则必须指定该权限 |
“notifications” | 允许扩展程序使用提出的HTML5 通知API 而不需要调用方法请求权限(例如: checkPermission() )。有关更多信息请参见 桌面通知 |
“pageCapture” | 如果扩展程序使用 chrome.pageCapture 模块则必须指定该权限 |
“privacy” | 如果扩展程序使用 chrome.privacy 模块则必须指定该权限 |
“proxy” | 如果扩展程序使用 chrome.proxy 模块则必须指定该权限 |
“tabs” | 如果扩展程序使用 chrome.tabs 或 chrome.windows 模块则必须指定该权限 |
“tts” | 如果扩展程序使用 chrome.tts 模块则必须指定该权限 |
“ttsEngine” | 如果扩展程序使用 chrome.tts 模块则必须指定该权限 |
“unlimitedStorage” | 提供无限的存储空间,保存HTML5客户端数据,例如数据库以及本地存储文件。如果没有这一权限,扩展程序的本地存储将限制在5MB以内。
|
“webNavigation” | 如果扩展程序使用 chrome.webNavigation 模块则必须指定该权限 |
“webRequest” | 如果扩展程序使用 chrome.webRequest 模块则必须指定该权限 |
“webRequestBlocking” | 如果扩展程序使用 chrome.webRequest 模块则必须指定该权限 |
应用程序或扩展程序要求的技术。托管站点(例如 Chrome网上应用店 )可能会使用这一列表建议用户不要安装不能在他们的计算机上工作的应用程序或者扩展程序。
目前唯一支持的要求为”3D”,代表GPU硬件加速。对于这一要求,可以如下面的例子所示,列出应用程序要求的3D相关的功能:
"requirements": {
"3D": {
"features": ["css3d", "webgl"]
}
}
“css3d” 要求指的是 CSS 3D变换规范 <https://sites.google.com/>`_(英文), `”webgl” 要求指的是 WebGL API <https://sites.google.com/>`_(英文)。 有关Chrome浏览器对3D图形支持的更多信息,请参见有关 `WebGL和3D图形 的帮助文章。 对于更多不同要求的检查可能会在将来增加。
一至四个用点(半角英文句号)分开的整数,标识扩展程序的版本。这些整数应该符合这两条规则:范围在0-65535之间(包括0和65535),非零整数不能以0开头。例如99999和032都是无效的。 如下是一些有效的版本号的例子:
自动更新系统比较版本号来确定已安装的某个扩展程序是否需要更新。如果已发布的扩展程序比已安装的扩展程序有更新的版本字符串,该扩展程序将会自动更新。 比较将从最左边的整数开始。如果相等,比较右边的整数,以此类推。例如,1.2.0比1.1.9.9999新。 省略整数的等于零,例如1.1.9.9999比1.1新。 有关更多信息,请参见 自动更新
指定扩展程序包要求的清单文件格式的版本。 从Chrome 18开始,开发人员应该指定2(不加引号),使用本文档描述的格式:
"manifest_version": 2
从Chrome 18开始,认为清单文件版本1已弃用,版本2目前还不是必需的, 但在不远的将来某一时刻,将不再支持使用已弃用清单文件版本的扩展程序包。
还没有准备转换至Chrome 18中新的清单文件版本的扩展程序、应用程序以及主题背景既可以明确地指定版本1,也可以完全省略该属性。
清单文件格式版本1与版本2之间的改变在 manifest_version文档 中详细描述。
Warning
(#_#)
字符串数组,指定扩展程序包内可以在网页中使用的资源路径(相对于扩展程序包的根目录)。 例如,为了在example.com上建立自定义界面,而插入内容脚本的扩展程序可以将界面需要的所有资源 (图片、图标、样式表、脚本等等)加入白名单,如下所示:
{
...
"web_accessible_resources": [
"images/my-awesome-image1.png",
"images/my-amazing-icon1.png",
"style/double-rainbow.css",
"script/double-rainbow.js"
],
...
}
这些资源将可以通过 URL chrome-extension://[扩展程序包的标识符]/[路径] 使用, URL 可以通过 chrome.extension.getURL 方法产生。 加入白名单的资源将以合适的 CORS 头信息提供, 所以它们可以通过XHR之类的机制使用。
插入的内容脚本本身不需要加入白名单。
新: r140689
要在受沙箱保护的唯一来源中载入的页面路径(相对于扩展程序包根目录)列表,还可以指定可选的内容安全策略来一起使用。 在沙箱中意味着如下两点:
例如,如下代码指定两个扩展程序页面将在沙箱中载入,并指定了自定义的 CSP :
{
...
"sandbox": {
"pages": [
"page1.html",
"directory/page2.html"
]
// 内容安全策略是可选的。
"content_security_policy":
"sandbox allow-scripts; script-src https://www.google.com"
],
...
}
如果没有指定的话,默认的 content_security_policy 值为 sandbox allow-scripts allow-forms 。 可以指定自己的CSP值来更进一步限制沙箱,但是它必须包含sandbox指示符, 并且 不能 包含 allow-same-origin 记号 (有关可能的沙箱记号,请参考: 相应的HTML5规范 )。
Note
注意