chrome.permissions

說明

請使用 chrome.permissions API，在執行階段 (而非安裝時) 要求宣告選用權限，讓使用者瞭解需要權限的原因，並只授予必要的權限。

總覽

權限警告旨在說明 API 授予的功能，但部分警告可能不明顯。開發人員可透過 Permissions API 說明權限警告，並逐步推出新功能，讓使用者安心瞭解擴充功能。如此一來，使用者就能指定他們願意授予的權限，以及想啟用哪些功能。

舉例來說，選用權限擴充功能的核心功能會覆寫新分頁。其中一項功能是顯示使用者當天的目標。這項功能只需要儲存空間權限，不包含警告。這個擴充功能還有另一項功能，使用者可以點選下列按鈕啟用：

可啟用額外功能的擴充功能按鈕

必須具備以下警告的 topSites 權限，才能顯示使用者的熱門網站。

TopSite API 的擴充功能警告

實作選用權限

步驟 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()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

檢查擴充功能是否具有指定權限。

參數

  • 權限

    權限

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (result: boolean) => void

    • 結果

      布林值

      如果擴充功能具有指定權限，則為「是」。如果同時指定來源為選用權限和內容指令碼比對模式，則除非同時授予這兩個權限，否則系統會傳回 false。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
)

取得擴充功能目前的權限組合。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (permissions: Permissions) => void

    • 權限

      權限

      擴充功能的有效權限。請注意，origins 屬性將包含資訊清單中 permissions 和 optional_permissions 金鑰所指定的來源，以及與 Content Script 相關聯的來源。

傳回

  • Promise<Permissions>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

移除指定權限的存取權。如果在移除權限時有任何問題，系統將設定「runtime.lastError」。

參數

  • 權限

    權限

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (removed: boolean) => void

    • 已移除

      布林值

      如果權限已遭移除，則為「是」。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

request()

Promise 
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