本頁面由 Cloud Translation API 翻譯而成。

chrome.permissions

說明

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

概念與用法

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

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

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

針對 topSites API 的擴充功能警告。 — `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 開發人員工具的功能。
`"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>

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

contains()

Promise

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

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

參數

權限

權限
回呼

函式選填

callback 參數如下所示：
```
(result: boolean) => void
```
- 結果
  
  布林值
  
  如果擴充功能具有指定的權限，則為 True。如果來源同時指定為選用權限和內容指令碼比對模式，除非同時授予這兩項權限，否則會傳回 false。

傳回

Promise<boolean>

Chrome 96 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getAll()

Promise

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

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

參數

回呼

函式選填

callback 參數如下所示：
```
(permissions: Permissions) => void
```
- 權限
  
  權限
  
  擴充功能的有效權限。請注意，origins 屬性會包含資訊清單中 permissions 和 optional_permissions 鍵中指定的授權來源，以及與內容指令碼相關聯的來源。

傳回

Promise<Permissions>

Chrome 96 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

remove()

Promise

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

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

參數

權限

權限
回呼

函式選填

callback 參數如下所示：
```
(removed: boolean) => void
```
- 已移除
  
  布林值
  
  如果權限已移除，則為「是」。

傳回

Promise<boolean>

Chrome 96 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

removeSiteAccessRequest()

Promise 待處理MV3 以上版本

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

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

參數

申請。

物件
- documentId
  
  string 選填
  
  系統將移除網站存取要求的文件 ID。必須是分頁中的頂層文件。必須指定這個或 tabId。
- 圖案
  
  string 選填
  
  網站存取要求將遭到移除的網址模式。如果提供這項資訊，則必須完全符合現有網站存取要求的模式。
- tabId
  
  號碼選填
  
  要移除網站存取要求的分頁 ID。必須指定這個或 documentId。
回呼

函式選填

callback 參數如下所示：
```
() => void
```

傳回

Promise<void>

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

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 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onAdded

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

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

參數

回呼

函式

callback 參數如下所示：
```
(permissions: Permissions) => void
```
- 權限
  
  權限

onRemoved

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

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

參數

回呼

函式

callback 參數如下所示：
```
(permissions: Permissions) => void
```
- 權限
  
  權限