browser.permissions

說明

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

概念和用途

權限警告會說明 API 授予的功能，但部分警告可能不明顯。開發人員可透過 Permissions API 說明權限警告，並逐步推出新功能，讓使用者在無風險的情況下瞭解擴充功能。這樣一來，使用者就能指定要授予多少存取權，以及要啟用哪些功能。

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

可啟用其他功能的擴充功能按鈕。

如要顯示使用者的熱門網站，必須具備 topSites 權限，並顯示下列警告。

topSites 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"	browser.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。
"declarativeNetRequest"	授予擴充功能 browser.declarativeNetRequest API 的存取權。
"devtools"	允許擴充功能擴充 Chrome 開發人員工具功能。
"geolocation"	允許擴充功能使用 HTML5 geolocation API。
"mdns"	授予擴充功能 browser.mdns API 的存取權。
"proxy"	授予擴充功能 browser.proxy API 的存取權，以便管理 Chrome 的 Proxy 設定。
"tts"	browser.tts API 會播放合成的文字轉語音 (TTS) 內容。
"ttsEngine"	browser.ttsEngine API 會使用擴充功能實作文字轉語音 (TTS) 引擎。
"wallpaper"	僅適用於 ChromeOS。使用 browser.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.
  browser.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 顯示與使用者已看過並接受的警告訊息不同的訊息，Chrome 就會提示使用者。舉例來說，上述程式碼可能會產生如下的提示：

權限確認提示範例。

步驟 4：檢查擴充功能目前的權限

如要檢查擴充功能是否具有特定權限或一組權限，請使用 permission.contains()：

browser.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() 通常會重新加入權限，而不會提示使用者。

browser.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

屬性

• origins

  string[] 選填

  主機權限清單，包括資訊清單中 optional_permissions 或 permissions 鍵指定的權限，以及與內容指令碼相關聯的權限。

• 權限

  string[] 選填

  具名權限清單 (不含主機或來源)。

方法

addHostAccessRequest()

Chrome 133+ 瀏覽器。*自 Chrome 148 起 MV3+

browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

新增主機存取要求。只有在擴充功能可取得要求中主機的存取權時，系統才會向使用者發出要求。跨來源導覽時，系統會重設要求。接受後，系統會授予網站頂層來源的永久存取權

參數

• 申請。

  物件

  • documentId

    字串 選填

    可顯示主機存取權要求的文件 ID。必須是分頁中的頂層文件。如果提供，要求會顯示在指定文件的分頁上，並在文件前往新來源時移除。新增要求後，系統會覆寫「tabId」現有的任何要求。必須指定這個項目或 tabId。

  • 圖案

    字串 選填

    可顯示主機存取權要求的網址模式。如果提供，主機存取要求只會顯示在符合這個模式的網址上。

  • tabId

    數字 選填

    可顯示主機存取權要求的標籤頁 ID。如果提供，要求會顯示在指定分頁上，並在分頁前往新來源時移除。新增要求會覆寫現有的「documentId」要求。必須指定這個項目或 documentId。

傳回

• 承諾<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

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

參數

• 權限

  權限

傳回

• Promise<boolean>

  Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

getAll()

browser.permissions.getAll(): Promise<Permissions>

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

傳回

• Promise<Permissions>

  Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

移除指定權限的存取權。如果移除權限時發生任何問題，系統會拒絕承諾。

參數

• 權限

  權限

傳回

• Promise<boolean>

  Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

removeHostAccessRequest()

Chrome 133+ 瀏覽器。*自 Chrome 148 起 MV3+

browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

移除主機存取要求 (如有)。

參數

• 申請。

  物件

  • documentId

    字串 選填

    要移除主機存取權要求的文件 ID。必須是分頁中的頂層文件。必須指定這個項目或 tabId。

  • 圖案

    字串 選填

    主機存取權要求將從這個網址模式中移除。如果提供，則必須與現有主機存取要求的模式完全相符。

  • tabId

    數字 選填

    要移除主機存取權要求的網頁分頁 ID。必須指定這個項目或 documentId。

傳回

• 承諾<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

要求指定權限，並在必要時向使用者顯示提示。這些權限必須在資訊清單的 optional_permissions 欄位中定義，或屬於使用者拒絕授予的必要權限。系統會忽略來源模式中的路徑。您可以要求選用來源權限的子集；例如，如果您在資訊清單的 optional_permissions 部分指定 *://*\/*，則可以要求 http://example.com/。如果要求權限時發生問題，系統會拒絕承諾。

參數

• 權限

  權限

傳回

• Promise<boolean>

  Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

事件

onAdded

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

擴充功能取得新權限時觸發。

參數

• callback

  函式

  callback 參數如下：

  (permissions: Permissions) => void

  • 權限

    權限

onRemoved

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

在擴充功能的權限存取權遭移除時觸發。

參數

• callback

  函式

  callback 參數如下：

  (permissions: Permissions) => void

  • 權限

    權限