该页面翻译自 Google Chrome Extensions 与 Google Chrome Apps。除非特别说明,该页面的内容遵循 Creative Commons Attribution 3.0 License,代码示例遵循 BSD License。
清单文件版本 1 在 Chrome 18 中弃用,对它的支持将根据清单文件版本 1 支持计划逐渐减少。从版本 1 到版本 2 的更改分为两大类:API 更改和安全性更改。
该文档提供了将您的 Chrome 扩展程序从清单文件版本 1 迁移到版本 2 所需要做的事情清单,并提供有关这些改变会带来什么以及为什么作出这些改变的更多详细摘要。
browser_actions
属性或 chrome.browserActions
API 吗?browser_action
属性替换 browser_actions
。
chrome.browserAction
替换
chrome.browserActions
。
default_icon
替换 icons
属性。default_title
替换 name
属性。default_popup
替换 popup
属性(并且现在它必须为字符串)。
page_actions
属性或者 chrome.pageActions
API吗?
page_action
替换 page_actions
。chrome.pageAction
替换 chrome.pageActions
。default_icon
替换 icons
属性。default_title
替换 name
属性。default_popup
替换 popup
属性(并且现在它必须为字符串)。
chrome.self
属性吗?chrome.extension
。Port.tab
属性吗?Port.sender
chrome.extension.getTabContentses()
或 chrome.extension.getExtensionTabs()
API 吗?chrome.extension.getViews( { "type" : "tab" } )
background_page
属性替换为 background
属性。
scripts
或 page
属性,包含页面的代码。
persistent
属性,并将它设置为 false
,将您的后台网页转换为事件页面。
addEventListener()
。
eval()
、new Function()
、innerHTML
、setTimeout()
或者通过其他方式传递动态求值的
JavaScript 代码字符串吗?
JSON.parse()
。
postMessage()
与受沙箱保护的页面通信。
清单文件版本 2 引入了对浏览器按钮与页面按钮 API 的一些更改,并将少量旧的 API 用新的来代替。
浏览器按钮 API 引入了某些名称上的更改:
browser_actions
与 chrome.browserActions
属性已替换为它们的单数形式 browser_action
与
chrome.browserAction
。
browser_actions
属性下,有 icons
、name
和 popup
属性,它们已替换为:
default_icon
,用于浏览器按钮的图标。default_name
,用于您将鼠标悬停在图标上时出现在工具提示中的文字。default_popup
,用于表示浏览器按钮用户界面的HTML网页(并且必须为字符串,不能是对象)。类似于浏览器按钮的更改,页面按钮 API 也有变化:
page_actions
与 chrome.pageActions
属性已替换为它们的单数形式 page_action
与
chrome.pageAction
。
page_actions
属性下,有 icons
、name
和 popup
属性,它们已替换为:
default_icon
,用于页面按钮的图标。default_name
,用于您将鼠标悬停在图标上时出现在工具提示中的文字。default_popup
用于表示页面按钮用户界面的 HTML 网页(并且必须为字符串,不能是对象)。一些扩展程序 API 已经移除,并用对应的新 API 替换:
background_page
属性已替换为 background。chrome.self
属性已移除,请使用 chrome.extension
。Port.tab
属性已替换为 Port.sender
。chrome.extension.getTabContentses()
和
chrome.extension.getExtensionTabs()
API 已替换为 chrome.extension.getViews( { "type" : "tab" } )
。清单文件版本 1 到版本 2 的转换伴随着一系列安全性相关的更改。许多这些更改来源于 Chrome 浏览器对内容安全策略的采用,您应该了解这一策略的更多信息来理解它带来的影响。
由于内容安全策略的使用,您不能继续使用 HTML 内容中内嵌的 <script> 标签,它们必须移动至外部的 JS 文件中去。此外,内嵌的事件处理器也不支持。例如,假设您的扩展程序中有如下代码:
<html> <head> <script> function myFunc() { ... } </script> </head> </html>
这一代码在运行时会产生错误。要修复它,请将 <script>
标签的内容移至外部文件,并使用 src='文件路径.js'
属性引用它们。
类似地,常见的内嵌事件处理器尽管是许多 Web 开发者为了方便而使用的特性,但它们不会执行。例如,考虑如下常见情况:
<body onload="initialize()"> <button onclick="handleClick()" id="button1">
它们不能在清单文件版本 2 的扩展程序中工作。请移除内嵌的事件处理器,将它们放在您的外部
JS 文件中,并使用 addEventListener()
为它们注册事件处理器。例如,在您的 JavaScript 代码中使用:
window.addEventListener("load", initialize); ... document.getElementById("button1").addEventListener("click",handleClick);
这样将您的扩展程序的行为与用户界面标记分离的做法要整洁得多。
在某些情况下,您的扩展程序可能会嵌入可以在外部使用或者来自外部来源的内容:
网页中的扩展程序内容:
如果您的扩展程序插入网页中的内容脚本嵌入资源(例如图片、脚本、CSS 样式等),您需要使用
web_accessible_resources
属性将这些资源加入白名单,这样外部网页才能使用它们:
{ ... "web_accessible_resources": [ "images/image1.png", "script/myscript.js" ], ... }
嵌入外部内容:
内容安全策略仅允许从您的扩展程序包中加载本地脚本与对象,以免外部攻击者向您的扩展程序引入未知代码。然而,有时候您需要加载外部托管的资源,例如
jQuery 或 Google Analytics(分析)代码。有两种方式可以实现:
{ ..., "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", ... }
也许在新的清单文件版本 2
架构中最大的变化之一就是扩展程序不能继续使用动态脚本求值技术,例如
eval
或 new Function()
或者将 JavaScript
代码字符串传递给会使用 eval()
的函数,例如
setTimeout()
。此外,已知某些常用的 JavaScript 库,例如
Google Maps 以及一些模板库,会使用这些技术。
Chrome 浏览器为页面提供了沙箱,以便在它们自己的来源中运行,拒绝访问
chrome.* API。为了在新的内容安全策略下使用 eval()
及类似技术:
postMessage()
使用消息传递和沙箱中的页面通信。
有关如何做这些的更多详情,请参见受沙箱保护的 eval 文档。
清单文件版本 2 带来的更改是为了引导开发人员建立更安全、架构更健壮的扩展程序和应用。要查看清单文件版本 1 至版本 2 的完整更改列表,请参见清单文件版本文档。有关使用沙箱隔离不安全代码的更多信息,请阅读受沙箱保护的 eval 文章。您可以访问我们与扩展程序相关的教程以及 HTML5Rocks 上一个很棒的简介(英文)了解有关内容安全策略的更多内容。