chrome.permissions

說明

概念和用法

權限警告是為了說明 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 擴充功能權限都可以指定為選用權限，但有以下例外：

如要進一步瞭解可用權限及警示，請查看「宣告權限」。

步驟 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).
  }
});

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

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

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

chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

chrome.permissions.onAdded.addListener(
  callback: function,
)

chrome.permissions.onRemoved.addListener(
  callback: function,
)