說明
請使用 chrome.permissions
API,在執行階段 (而非安裝時) 要求宣告選用權限,讓使用者瞭解需要權限的原因,並只授予必要的權限。
總覽
權限警告旨在說明 API 授予的功能,但部分警告可能不明顯。開發人員可透過 Permissions API 說明權限警告,並逐步推出新功能,讓使用者安心瞭解擴充功能。如此一來,使用者就能指定他們願意授予的權限,以及想啟用哪些功能。
舉例來說,選用權限擴充功能的核心功能會覆寫新分頁。其中一項功能是顯示使用者當天的目標。這項功能只需要儲存空間權限,不包含警告。這個擴充功能還有另一項功能,使用者可以點選下列按鈕啟用:
必須具備以下警告的 topSites 權限,才能顯示使用者的熱門網站。
實作選用權限
步驟 1:決定需要和哪些權限
擴充功能可以宣告必要和選用權限。一般而言,你可以:
- 請視需要使用必要權限,以便執行擴充功能的基本功能。
- 如果需要在擴充功能中存取選用功能,請視需要使用選用權限。
必要權限的優點:
- 減少提示次數:擴充功能可以提示使用者一次接受所有權限。
- 簡化開發流程:保證提供必要的權限。
選用權限的優點:
- 更高的安全性:由於使用者只啟用權限,因此擴充功能執行時所需的權限較少 所需資料
- 為使用者提供更實用的資訊:擴充功能可以解釋為何需要特定權限 使用者啟用相關功能時。
- 升級更輕鬆:升級擴充功能後,如果 Chrome 未為使用者停用擴充功能, 升級後,系統會加入選用權限,而非必要權限。
步驟 2:在資訊清單中宣告選用權限
在擴充功能資訊清單中,使用 optional_permissions
鍵宣告選用權限。
使用與 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 開發人員工具 功能。 |
"experimental" |
Canary 版和開發人員版 。授予擴充功能 chrome.experimental API 的存取權。 |
"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
-
結果
布林值
如果擴充功能具有指定權限,則為「是」。如果同時指定來源為選用權限和內容指令碼比對模式,則除非同時授予這兩個權限,否則系統會傳回
false
。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
getAll()
chrome.permissions.getAll(
callback?: function,
)
取得擴充功能目前的權限組合。
參數
-
回呼
函式 選用
callback
參數如下所示:(permissions: Permissions) => void
-
權限
擴充功能的有效權限。請注意,
origins
屬性將包含資訊清單中permissions
和optional_permissions
金鑰所指定的來源,以及與 Content Script 相關聯的來源。
-
傳回
-
Promise<Permissions>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
參數
-
權限
-
回呼
函式 選用
callback
參數如下所示:(removed: boolean) => void
-
已移除
布林值
如果權限已遭移除,則為「是」。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
要求存取指定權限,並在必要時向使用者顯示提示。您必須在資訊清單的 optional_permissions
欄位中定義這些權限,或是使用者保留的必要權限。系統會忽略來源模式的路徑。您可以要求部分選用來源權限。舉例來說,如果您在資訊清單的 optional_permissions
區段中指定 *://*\/*
,就可以要求 http://example.com/
。如果要求權限時有任何問題,將會設定 runtime.lastError
。
參數
-
權限
-
回呼
函式 選用
callback
參數如下所示:(granted: boolean) => void
-
已授予
布林值
如果使用者授予指定權限,則為 True。
-
傳回
-
Promise<boolean>
Chrome 96 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
活動
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
在擴充功能取得新權限時觸發。
參數
-
回呼
函式
callback
參數如下所示:(permissions: Permissions) => void
-
權限
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
從擴充功能中移除權限時,就會觸發。
參數
-
回呼
函式
callback
參數如下所示:(permissions: Permissions) => void
-
權限
-