說明
請在執行階段 (而非安裝階段) 使用 chrome.permissions API 要求已宣告的選用權限，讓使用者瞭解為何需要這些權限，並只授予必要的權限。
概念和用法
權限警告會說明 API 授予的功能，但部分警告可能不明顯。Permissions API 可讓開發人員說明權限警告，並逐步推出新功能，讓使用者無須擔心風險，就能瞭解擴充功能。如此一來，使用者就能指定願意授予的存取權，以及要啟用的功能。
舉例來說，選用權限擴充功能的核心功能是覆寫新分頁頁面。其中一個功能是顯示使用者當天的目標。這項功能只需要儲存空間權限，不包含警告。擴充功能還有其他功能，使用者只要按一下下列按鈕即可啟用：
如要顯示使用者的熱門網站，您必須取得 topSites 權限，但這會顯示以下警告。
topSites API 的擴充功能警告實作選用權限
步驟 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 地理位置 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鍵中指定的權限，以及與內容指令碼相關聯的權限。 -
權限
string[] 選填
已命名權限清單 (不含主機或來源)。
方法
addHostAccessRequest()
chrome.permissions.addHostAccessRequest(
request: object,
callback?: function,
)
新增主機存取要求。只有在擴充功能可在要求中獲得主機存取權時，系統才會向使用者發出要求信號。跨來源導覽時，要求會重設。接受後，即可持續存取網站的主要來源
參數
-
申請。
物件
-
documentId
string 選填
可顯示主機存取要求的文件 ID。必須是分頁中的頂層文件。如果提供，系統就會在指定文件的分頁中顯示要求，並在文件導覽至新來源時移除。新增要求後，系統會覆寫
tabId的所有現有要求。必須指定這個或tabId。 -
圖案
string 選填
可顯示主機存取要求的網址模式。如果提供此模式，主機存取要求只會顯示在符合此模式的網址上。
-
tabId
號碼 選填
主機存取要求可顯示的分頁 ID。如果提供，系統就會在指定分頁中顯示要求，並在分頁導覽至新來源時移除。新增要求會覆寫
documentId的現有要求。必須指定這個或documentId。
-
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
檢查擴充功能是否具有指定的權限。
參數
-
權限
-
回呼
函式 選填
callback參數如下所示：(result: boolean) => void
-
結果
布林值
如果擴充功能具有指定的權限，則為 True。如果來源同時指定為選用權限和內容指令碼比對模式，除非同時授予這兩項權限，否則會傳回
false。
-
傳回
-
Promise<布林值>
Chrome 96 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
getAll()
chrome.permissions.getAll(
callback?: function,
)
取得擴充功能目前的權限組合。
參數
-
回呼
函式 選填
callback參數如下所示：(permissions: Permissions) => void
傳回
-
Promise<Permissions>
Chrome 96 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
移除指定權限的存取權。如果移除權限時發生任何問題，系統會設定 runtime.lastError。
參數
-
權限
-
回呼
函式 選填
callback參數如下所示：(removed: boolean) => void
-
已移除
布林值
如果權限已移除，則為「是」。
-
傳回
-
Promise<布林值>
Chrome 96 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
removeHostAccessRequest()
chrome.permissions.removeHostAccessRequest(
request: object,
callback?: function,
)
移除主機存取要求 (如果有的話)。
參數
-
申請。
物件
-
documentId
string 選填
系統將移除主機存取要求的文件 ID。必須是分頁中的頂層文件。必須指定這個或
tabId。 -
圖案
string 選填
主機存取要求將移除的網址模式。如果提供此參數，則必須完全符合現有主機存取要求的模式。
-
tabId
號碼 選填
要移除主機存取權要求的分頁 ID。必須指定這個或
documentId。
-
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
要求存取指定權限，並視需要向使用者顯示提示。這些權限必須在資訊清單的 optional_permissions 欄位中定義，或是使用者拒絕授予的必要權限。系統會忽略來源模式中的路徑。您可以要求選用來源權限的子集，例如，如果您在資訊清單的 optional_permissions 部分指定 *://*\/*，就可以要求 http://example.com/。如果要求權限時發生任何問題，系統會設定 runtime.lastError。
參數
-
權限
-
回呼
函式 選填
callback參數如下所示：(granted: boolean) => void
-
已授予
布林值
如果使用者已授予指定權限，則為「是」。
-
傳回
-
Promise<布林值>
Chrome 96 以上版本承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
活動
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
擴充功能取得新權限時觸發。
參數
-
回呼
函式
callback參數如下所示：(permissions: Permissions) => void
-
權限
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
當擴充功能的權限存取權遭到移除時觸發。
參數
-
回呼
函式
callback參數如下所示：(permissions: Permissions) => void
-
權限
-