chrome.permissions

說明

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

總覽

權限警告會說明 API 授予的功能，但部分警告可能不明顯。Permissions API 可讓開發人員說明權限警告，並逐步推出新功能，讓使用者無須擔心風險，就能瞭解擴充功能。如此一來，使用者就能指定願意授予的存取權，以及要啟用的功能。

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

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

如要顯示使用者的熱門網站，您必須取得 topSites 權限，但這會顯示以下警告。

針對 topSites API 的擴充功能警告

實作選用權限

步驟 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 擴充功能權限都可以指定為選用，但以下權限除外：

權限 說明
"debugger" chrome.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。
"declarativeNetRequest" 授予擴充功能存取 chrome.declarativeNetRequest API 的權限。
"devtools" 允許擴充功能擴充 Chrome 開發人員工具的功能。
"experimental" 僅限 Canary 和開發人員版。授予擴充功能存取 chrome.experimental API 的權限。
"geolocation" 允許擴充功能使用 HTML5 地理位置 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 鍵中指定的權限，以及與內容指令碼相關聯的權限。

  • 權限

    string[] 選填

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

方法

addSiteAccessRequest()

Promise 待處理MV3 以上版本 
chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

新增網站存取要求。只有在擴充功能可授予網站存取權時，系統才會向使用者發出要求信號。跨來源導覽時，要求會重設。接受後，即可持續存取網站的主要來源

參數

  • 申請。

    物件

    • documentId

      string 選填

      可顯示網站存取要求的文件 ID。必須是分頁中的頂層文件。如果提供，系統就會在指定文件的分頁中顯示要求，並在文件導覽至新來源時移除。新增要求後，系統會覆寫 tabId 的所有現有要求。必須指定這個或 tabId。

    • 圖案

      string 選填

      網站存取要求可顯示的網址模式。如果提供這項資訊，系統只會在網址符合這個模式時顯示網站存取要求。

    • tabId

      號碼 選填

      可顯示網站存取要求的分頁 ID。如果提供，系統就會在指定分頁中顯示要求，並在分頁導覽至新來源時移除。新增要求會覆寫 documentId 的現有要求。必須指定這個或 documentId。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

contains()

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

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

參數

  • 權限

    權限

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: boolean) => void

    • 結果

      布林值

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

傳回

  • Promise<boolean>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getAll()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (permissions: Permissions) => void

    • 權限

      權限

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

傳回

  • Promise<Permissions>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

remove()

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

移除指定權限的存取權。如果移除權限時發生任何問題，系統會設定 runtime.lastError。

參數

  • 權限

    權限

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (removed: boolean) => void

    • 已移除

      布林值

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

傳回

  • Promise<boolean>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

removeSiteAccessRequest()

Promise 待處理MV3 以上版本 
chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

移除網站存取要求 (如果有的話)。

參數

  • 申請。

    物件

    • documentId

      string 選填

      系統將移除網站存取要求的文件 ID。必須是分頁中的頂層文件。必須指定這個或 tabId。

    • 圖案

      string 選填

      網站存取要求將遭到移除的網址模式。如果提供這項資訊，則必須完全符合現有網站存取要求的模式。

    • tabId

      號碼 選填

      要移除網站存取要求的分頁 ID。必須指定這個或 documentId。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

request()

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

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

參數

  • 權限

    權限

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (granted: boolean) => void

    • 已授予

      布林值

      如果使用者已授予指定權限，則為「是」。

傳回

  • Promise<boolean>

    Chrome 96 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

活動

onAdded

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (permissions: Permissions) => void

onRemoved

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (permissions: Permissions) => void