資訊清單第 1 版已在 Chrome 18 版中淘汰,我們將根據資訊清單第 1 版支援時間表逐步停止支援這項功能。從第 1 版到第 2 版的變更分為兩大類:API 變更和安全性變更。
本文件提供檢查清單,協助您將 Chrome 擴充功能從資訊清單第 1 版遷移至第 2 版,並進一步摘要說明這些變更的意義和產生原因。
API 變更檢查清單
要使用
browser_actions
屬性還是chrome.browserActions
API?將
browser_actions
替換為單數browser_action
屬性。以
chrome.browserAction
取代chrome.browserActions
。將
icons
屬性替換為default_icon
。將
name
屬性替換為default_title
。將
popup
屬性替換為default_popup
(現在必須是字串)。要使用
page_actions
屬性還是chrome.pageActions
API?以
page_action
取代page_actions
。以
chrome.pageAction
取代chrome.pageActions
。將
icons
屬性替換為default_icon
。將
name
屬性替換為default_title
。將
popup
屬性替換為default_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
,以將背景頁面轉換為事件頁面
安全性變更檢查清單
您是否在 HTML 網頁使用內嵌指令碼區塊?
移除
<script>
標記內含的 JS 程式碼,並將程式碼放在外部 JS 檔案中。您是否使用內嵌事件處理常式 (例如講道)?
請從 HTML 程式碼中移除這些物件,再移到外部 JS 檔案中,並改用
addEventListener()
。您的擴充功能是否會在需要存取擴充功能套件所含資源 (例如圖片和指令碼) 的網頁中插入內容指令碼?
定義 web_accessible_resources 屬性並列出資源,並視需要列出這些資源的個別內容安全政策。
擴充功能是否嵌入外部網頁?
定義 sandbox 屬性。
程式碼或程式庫是否使用
eval()
、新的Function()
、innerHTML
、setTimeout()
,或以其他方式傳遞要動態評估的 JS 程式碼字串?如要將 JSON 程式碼剖析為物件,請使用
JSON.parse()
。使用支援 CSP 的程式庫,例如 AngularJS。
在資訊清單中建立沙箱項目,並在沙箱中執行受影響的程式碼,使用
postMessage()
與沙箱頁面通訊。您是否載入了 jQuery 或 Google Analytics (分析) 等外部程式碼?
建議您下載程式庫並在擴充功能中封裝,然後從本機套件載入程式庫。
在資訊清單的「content_security_policy」部分中將提供資源的 HTTPS 網域加入許可清單。
API 異動摘要
資訊清單第 2 版會針對瀏覽器動作和網頁動作 API 推出幾項變更,並以較新的 API 取代幾個舊的 API。
瀏覽器動作異動
瀏覽器動作 API 會採用下列命名方式異動:
browser_actions
和chrome.browserActions
屬性已替換為其單一對應項目browser_action
和chrome.browserAction
。在舊的
browser_actions
屬性下,有icons
、name
和popup
屬性。這些更改為:default_icon
代表瀏覽器動作標記圖示default_name
遊標懸停在徽章上時,工具提示中顯示的文字代表瀏覽器動作 UI 的 HTML 網頁
default_popup
(現在必須是字串,不能是物件)
網頁動作異動
與瀏覽器動作的變更類似,Page actions API 也已變更:
page_actions
和chrome.pageActions
屬性已替換為其單獨的page_action
和chrome.pageAction
。在舊的
page_actions
屬性下方,有icons
、name
和popup
屬性。這些異動已替換為:default_icon
網頁動作徽章圖示default_name
遊標懸停在徽章上時,工具提示中顯示的文字代表網頁動作 UI 的 HTML 網頁
default_popup
(現在必須是字串,不能是物件)
已移除並變更 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='path_to_file.js'
屬性參照這些檔案。
同樣地,內嵌事件處理常式是許多網頁開發人員經常使用的常見事件和便利功能,也不會執行。舉例來說,不妨思考以下常見的例項:
<body onload="initialize()">
<button onclick="handleClick()" id="button1">
且不適用於 Manifest V2 擴充功能。移除內嵌事件處理常式、將其放在外部 JS 檔案中,並使用 addEventListener()
為這些處理常式註冊事件處理常式。例如,在 JS 程式碼中使用:
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 (分析) 程式碼。您可以透過以下兩種方式進行設定:
- 在本機下載相關程式庫 (例如 jQuery),然後與您的擴充功能一起封裝。
您可以在資訊清單的「content_security_policy」區段中將 HTTPS 來源加入許可清單,以受限的方式放寬 CSP。如要加入 Google Analytics (分析) 這類程式庫,請按照下列步驟操作:
{ ..., "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", ... }
使用動態指令碼評估
新版資訊清單 v2 配置的最大變更或許是擴充功能無法再使用動態指令碼評估技術 (例如 eval()
或新的 Function()
),或是將 JS 程式碼字串傳遞至會導致使用 eval()
的函式,例如 setTimeout()
。此外,有些常用的 JavaScript 程式庫 (例如 Google 地圖和特定範本程式庫) 也知道使用這些技術。
Chrome 提供沙箱機制,讓網頁在獨立來源中執行,系統會拒絕 Chrome 的存取權。*
相互整合根據新版內容安全政策,使用 eval()
和類似功能:
- 在資訊清單檔案中建立沙箱項目。
- 在沙箱項目中,列出要在沙箱中執行的網頁。
- 使用透過
postMessage()
傳遞的訊息與沙箱頁面通訊。
如要進一步瞭解相關做法,請參閱「沙箱 Eval」說明文件。
其他資訊
資訊清單第 2 版的變更可以引導開發人員建構更安全、結構更穩固的擴充功能和應用程式。如要查看資訊清單第 1 版到第 2 版的完整變更清單,請參閱資訊清單檔案說明文件。如要進一步瞭解如何使用沙箱機制找出不安全的程式碼,請參閱「沙箱評估」一文。如要進一步瞭解《內容安全政策》,請參閱我們的擴充功能相關教學課程和 HTML5Rocks 詳細說明。