chrome.permissions

refresh date: 2026-09-25 robots: noindex

說明

使用 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" 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 顯示與使用者已看過並接受的警告訊息不同的訊息，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

屬性

  • origins

    string[] 選填

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

  • 權限

    string[] 選填

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

方法

contains()

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

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

參數

  • 權限

    權限

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

      如果擴充功能具有指定權限，則為 True。如果來源同時指定為選用權限和內容指令碼比對模式，除非兩項權限都已授予，否則會傳回 false。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

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

getAll()

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

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

參數

  • callback

    函式 選填

    callback 參數如下： 

    (permissions: Permissions) => void

    • 權限

      權限

      擴充功能的使用中權限。請注意，origins 屬性會包含資訊清單中 permissions 和 optional_permissions 鍵指定的來源，以及與內容指令碼相關聯的來源。

傳回

  • Promise<Permissions>

    Chrome 96 以上版本

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

remove()

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

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

參數

  • 權限

    權限

  • callback

    函式 選填

    callback 參數如下： 

    (removed: boolean) => void

    • 已移除

      布林值

      如果權限已移除，則為 True。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

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

參數

  • 權限

    權限

  • callback

    函式 選填

    callback 參數如下： 

    (granted: boolean) => void

    • 已授予

      布林值

      如果使用者授予指定權限，則為 True。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

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

事件

onAdded

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (permissions: Permissions) => void

onRemoved

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (permissions: Permissions) => void