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.addSiteAccessRequest(
  request: object,
  callback?: function,
)

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

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

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

chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

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

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

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