說明
使用 chrome.permissions
API 在執行階段要求宣告選用權限,而非在安裝時要求權限,讓使用者瞭解需要權限的原因,並僅授予必要的權限。
概念和用法
權限警告是為了說明 API 授予的功能,但其中某些警告並不明顯。開發人員可以透過 Permissions API 說明權限警告,並逐步導入新功能,讓使用者在瞭解這項擴充功能時毫無風險。如此一來,使用者就可以指定他們願意授予的權限量,以及要啟用哪些功能。
舉例來說,選用權限擴充功能的核心功能會覆寫新分頁。其中一項功能是顯示使用者當天的目標。這項功能只需要儲存空間權限,且不含警告。這項擴充功能還有一個功能,使用者只要點選下列按鈕即可啟用:
要顯示使用者的熱門網站,需要具備 topSites 權限,並顯示以下警告。
實作選用權限
步驟 1:決定需要以及選用的權限
擴充功能可宣告必要和選用權限。一般而言,您應:
- 請視需要授予擴充功能基本功能所需的權限。
- 如果擴充功能需要擴充功能,請視需要使用選用權限。
必要權限的優點:
- 提示較少:擴充功能可以提示使用者一次接受所有權限,
- 簡化開發流程:保證能提供所需權限。
選用權限的優點如下:
- 強化安全性:使用者只啟用所需的權限,因此擴充功能執行的權限較少。
- 為使用者提供更多資訊:使用者啟用相關功能時,擴充功能可說明其需要特定權限的原因。
- 升級更輕鬆:升級擴充功能時,如果升級時新增了選擇性權限 (而非必要權限),Chrome 就不會為使用者停用該擴充功能。
步驟 2:在資訊清單中宣告選用權限
使用 optional_permissions
鍵,在擴充功能資訊清單中宣告選用權限,格式與權限欄位相同:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
如要要求只在執行階段找到的主機,請在擴充功能的 optional_host_permissions
欄位中加入 "https://*/*"
。這樣就能在 "Permissions.origins"
中指定任何來源,只要來源有相符的配置即可。
無法指定為選用的權限
大部分的 Chrome 擴充功能權限都可以指定為選用權限,但有以下例外:
權限 | 說明 |
---|---|
"debugger" |
chrome.debugger API 是 Chrome 遠端偵錯通訊協定的替代傳輸方式。 |
"declarativeNetRequest" |
授予擴充功能 chrome.declarativeNetRequest API 的存取權。 |
"devtools" |
允許擴充功能展開 Chrome 開發人員工具功能。 |
"geolocation" |
允許擴充功能使用 HTML5 geolocation API。 |
"mdns" |
授予擴充功能 chrome.mdns API 的存取權。 |
"proxy" |
授予擴充功能 chrome.proxy API 的存取權,藉此管理 Chrome 的 Proxy 設定。 |
"tts" |
chrome.tts API 可播放合成的文字轉語音 (TTS)。 |
"ttsEngine" |
chrome.ttsEngine API 使用擴充功能實作文字轉語音 (TTS) 引擎。 |
"wallpaper" |
僅限 ChromeOS。使用 chrome.wallpaper API 可變更 ChromeOS 桌布。 |
如要進一步瞭解可用權限及警示,請查看「宣告權限」。
步驟 3:要求選用權限
使用 permissions.request()
在使用者手勢中要求權限:
document.querySelector('#my-button').addEventListener('click', (event) => {
// Permissions must be requested from inside a user gesture, like a button's
// click handler.
chrome.permissions.request({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (granted) => {
// The callback argument will be true if the user granted the permissions.
if (granted) {
doSomething();
} else {
doSomethingElse();
}
});
});
與已看過並接受的使用者相比,Chrome 會提示使用者新增的權限會導致不同的警告訊息。舉例來說,先前的程式碼可能會產生如下的提示:
步驟 4:檢查擴充功能目前的權限
如要檢查擴充功能是否具備特定權限或一組權限,請使用 permission.contains()
:
chrome.permissions.contains({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (result) => {
if (result) {
// The extension has the permissions.
} else {
// The extension doesn't have the permissions.
}
});
步驟 5:移除權限
如有不再需要的權限,請移除這類權限。移除權限後,呼叫 permissions.request()
通常會加回權限,不會提示使用者。
chrome.permissions.remove({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (removed) => {
if (removed) {
// The permissions have been removed.
} else {
// The permissions have not been removed (e.g., you tried to remove
// required permissions).
}
});
類型
Permissions
屬性
-
來源
string[] 選填
主機權限清單,包括資訊清單中的
optional_permissions
或permissions
金鑰中指定的權限,以及與 Content Script 相關聯的權限。 -
權限
string[] 選填
已命名權限清單 (不包括主機或來源)。
方法
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
檢查擴充功能是否具備指定權限。
參數
-
權限
-
回呼
函式選用
callback
參數如下所示:(result: boolean) => void
-
結果
boolean
如果擴充功能具備指定權限,則為「是」。如果同時指定了選用權限和內容指令碼比對模式,如未同時授予兩項權限,則系統會傳回
false
。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getAll()
chrome.permissions.getAll(
callback?: function,
)
取得擴充功能目前的權限組合。
參數
-
回呼
函式選用
callback
參數如下所示:(permissions: Permissions) => void
傳回
-
Promise<權限>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
移除指定權限的存取權。如果在移除權限時發生任何問題,系統會設定 runtime.lastError
。
參數
-
權限
-
回呼
函式選用
callback
參數如下所示:(removed: boolean) => void
-
已移除
boolean
如果權限已移除,則為「是」。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
要求存取指定的權限,並在必要時向使用者顯示提示。這些權限必須在資訊清單的 optional_permissions
欄位中定義,或必須是使用者保留的必要權限。系統會忽略來源模式上的路徑。您可以要求部分選用的來源權限;例如,如果您在資訊清單的 optional_permissions
區段中指定 *://*\/*
,則可要求 http://example.com/
。如果在要求權限時遇到任何問題,系統會設定 runtime.lastError
。
參數
-
權限
-
回呼
函式選用
callback
參數如下所示:(granted: boolean) => void
-
已授予
boolean
如果使用者授予了指定權限,則為「是」。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
當擴充功能取得新權限時觸發。
參數
-
回呼
功能
callback
參數如下所示:(permissions: Permissions) => void
-
權限
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
從擴充功能中移除權限時觸發。
參數
-
回呼
功能
callback
參數如下所示:(permissions: Permissions) => void
-
權限
-