Chrome 瀏覽器插件 Manifest.json V3 中權限（Permissions）字段解析詳情 - 前端,chrome-extension,瀏覽器,permissions,2023-年度總結月恆動態日志

本文參與了SegmentFault 思否 2023 年度有獎徵文活動，歡迎正在閲讀的你也加入。

一、權限（`Permissions`）

再使用拓展程序的 API 時，大多數的時候，需要在 manifest.json 文件中聲明 permissions 字段。

一、權限類型

在 V3 版本中可以聲明以下類別的權限：

permissions：
- 包含下面 permissions 權限列表中的項；
optional_permissions：
- 由用户在運行時（而不是在安裝時）授予；
content_scripts.matches：
- 包含一個或多個匹配模式，可允許內容腳本注入到一個或多個主機中；
host_permissions：
- 包含一個或多個匹配模式，可提供對一個或多個主機的訪問權限；
optional_host_permissions：
- 由用户在運行時（而不是在安裝時）授予。

如果您的擴展程序遭到惡意軟件入侵，設置權限有助於限制對您的擴展程序造成的破壞。在安裝之前或運行時，系統會向用户顯示一些權限警告，以徵求用户同意

二、`Manifest.json` 示例

{
  "name": "Permissions Extension",
  "permissions": [
    "activeTab",
    "contextMenus",
    "storage"
  ],
  "optional_permissions": [
    "topSites",
  ],
  "host_permissions": [
    "https://www.developer.chrome.com/*"
  ],
  "optional_host_permissions":[
    "https://*/*",
    "http://*/*"
  ],
  "manifest_version": 3
}

三、主機權限（`Host permissions`）

主機權限允許擴展程序與網址的匹配格式進行交互。有些 Chrome API 不僅需要擁有自己的 API 權限，還需要主機權限。

需要主機權限的 API：

從擴展程序 Service Worker 和擴展程序頁面發出 fetch() 請求。
使用 chrome.tabs API 讀取和查詢敏感的標籤頁屬性（網址、標題和 favIconUrl）。
以編程方式注入內容腳本。
使用 chrome.webRequest API 監控和控制網絡請求。
使用 chrome.cookies API 訪問 Cookie。
使用 chrome.declarativeNetRequest API 重定向和修改請求及響應標頭。

四、包含警告的權限

如果擴展程序請求多項權限，並且其中的許多權限會在安裝時顯示警告，用户會看到警告列表
示例：
警告權限示例
如果擴展程序只顯示少量警告或向用户説明權限，用户更有可能信任該擴展程序。請考慮實現可選權限或功能略弱的 API，以避免收到警告。
在 host_permissions 和 content_scripts.matches 字段中添加或更改匹配模式也會觸發警告。

1. 權限警告列表

權限	説明	警告
`http:///` `https:///` `:///*` `<all_urls>`	對所有主機的訪問權限	讀取和更改在所有網站上的所有數據
`https://HostName.com/`	對 `https://HostName.com/` 的訪問權限	讀取和更改在 `HostName.com` 上的數據
`accessibilityFeatures.modify`	允許此擴展程序修改個別無障礙功能的狀態	更改無障礙設置
`accessibilityFeatures.read`	允許此擴展程序讀取各個無障礙功能狀態	查看無障礙設置
`bookmarks`	對 `chrome.bookmarks API` 的訪問權限	讀取和更改書籤
`clipboardRead`	如果擴展程序使用 `document.execCommand('paste')`，則必須提供	讀取複製和粘貼的數據
`clipboardWrite`	表示該擴展程序使用 `document.execCommand('copy')` 或 `document.execCommand('cut')`	修改複製和粘貼的數據
`contentSettings`	對 `chrome.contentSettings API` 的訪問權限	更改用於控制網站對 `Cookie`、`JavaScript`、插件、地理定位、麥克風、攝像頭等功能的使用權限的設置。
`debugger`	對 `chrome.debugger API` 的訪問權限	訪問頁面調試程序後端讀取和更改在所有網站上的所有數據
`declarativeNetRequest`	對 `chrome.declarativeNetRequest API` 的訪問權限	屏蔽任何網頁上的內容
`declarativeNetRequestFeedback`	函數和事件的訪問權限，這些函數和事件會返回匹配的聲明式規則的相關信息	讀取瀏覽記錄
`desktopCapture`	對 `chrome.desktopCapture API` 的訪問權限	截取屏幕上的內容
`downloads`	對 `chrome.downloads API` 的訪問權限	管理下載內容
`favicon`	對 `Favicon API` 的訪問權限	讀取訪問的網站的圖標
`geolocation`	允許擴展程序在不提示用户授予權限的情況下使用 `HTML5 geolocation API`	檢測實際位置
`history`	對 `chrome.history API` 的訪問權限	讀取和更改所有已登錄設備上的瀏覽記錄
`identity.email`	通過 `chrome.identity API` 對電子郵件地址的訪問權限	獲取電子郵件地址
`management`	對 `chrome.management API` 的訪問權限	管理應用、擴展程序和主題背景
`nativeMessaging`	對 `Native Messaging API` 的訪問權限	與協作的原生應用通信
`notifications`	對 `chrome.notifications API` 的訪問權限	顯示通知
`pageCapture`	對 `chrome.pageCapture API` 的訪問權限	讀取和更改在所有網站上的所有數據
`privacy`	對 `chrome.privacy API` 的訪問權限	更改與隱私相關的設置
`proxy`	對 `chrome.proxy API` 的訪問權限	讀取和更改在所有網站上的所有數據
`readingList`	對 `chrome.readingList API` 的訪問權限	讀取和更改閲讀清單中的條目
`sessions` 和 `history`	對 `chrome.sessionsAPI` 和 `chrome.history API` 的訪問權限	讀取和更改所有已登錄設備上的瀏覽記錄
`sessions` 和 `tabs`	對 `chrome.sessions API` 以及 `Tab` 對象的特權字段的訪問權限	讀取在所有已登錄賬號設備上的瀏覽記錄
`system.storage`	對 `chrome.system.storage API` 的訪問權限	識別和彈出存儲設備
`tabCapture`	對 `chrome.tabCapture API` 的訪問權限	讀取和更改在所有網站上的所有數據
`tabGroups`	對 `chrome.tabGroups API` 的訪問權限	查看和管理標籤頁分組
`tabs`	對多個 `API`（包括 `chrome.tabs` 和 `chrome.windows`）使用的 `Tab` 對象的特權字段的訪問權限	讀取瀏覽記錄
`topSites`	對 `chrome.topSites API` 的訪問權限	讀取最常訪問的網站列表
`ttsEngine`	對 `chrome.ttsEngine API` 的訪問權限	朗讀使用合成語音説出的所有文字
`webAuthenticationProxy`	對 `chrome.webAuthenticationProxy API` 的訪問權限	讀取和更改在所有網站上的所有數據
`webNavigation`	對 `chrome.webNavigation API` 的訪問權限	讀取瀏覽記錄

五、權限列表

1. `accessibilityFeatures.modify`

允許擴展程序在使用 chrome.accessibilityFeatures API 時修改無障礙功能狀態。

2. `accessibilityFeatures.read`

允許擴展程序在使用 chrome.accessibilityFeatures API 時讀取無障礙功能狀態。

3. `activeTab`

通過用户手勢對活動標籤頁的臨時訪問權限。

4. `alarms`

對 chrome.alarms API 的訪問權限。

5. `audio`

對 chrome.audio API 的訪問權限。

6. `background`

讓 Chrome 儘早啓動（用户登錄計算機、啓動 Chrome 之前）和延遲關閉（即使最後一個窗口已關閉，直到用户明確退出 Chrome）。

7. `bookmarks`

對 chrome.bookmarks API 的訪問權限。

8. `browsingData`

對 chrome.browsingData API 的訪問權限。

9. `certificateProvider`

對 chrome.certificateProvider API 的訪問權限。

10. `contentSettings`

對 chrome.contentSettings API 的訪問權限。

11. `contextMenus`

對 chrome.contextMenus API 的訪問權限。

12. `cookies`

對 chrome.cookies API 的訪問權限。

13. `debugger`

對 chrome.debugger API 的訪問權限。

14. `declarativeContent`

對 chrome.declarativeContent API 的訪問權限。

15. `declarativeNetRequest`

對 chrome.declarativeNetRequest API 的訪問權限。

16. `declarativeNetRequestWithHostAccess`

在需要主機權限時對 chrome.declarativeNetRequest API 的訪問權限。

17. `declarativeNetRequestFeedback`

使用 chrome.declarativeNetRequest API 時向開發者工具控制枱寫入錯誤和警告的權限。

18. `dns`

對 chrome.dns API 的訪問權限。

19. `desktopCapture`

對 chrome.desktopCapture API 的訪問權限。

20. `documentScan`

對 chrome.documentScan API 的訪問權限。

21. `downloads`

對 chrome.downloads API 的訪問權限。

22. `downloads.open`

允許使用 chrome.downloads.open()。

23. `downloads.ui`

允許使用 chrome.downloads.setUiOptions()。

24. `enterprise.deviceAttributes`

對 chrome.enterprise.deviceAttributes API 的訪問權限。

25. `enterprise.hardwarePlatform`

對 chrome.enterprise.hardwarePlatform API 的訪問權限。

26. `enterprise.networkingAttributes`

對 chrome.enterprise.networkingAttributes API 的訪問權限。

27. `enterprise.platformKeys`

對 chrome.enterprise.platformKeys API 的訪問權限。

28. `favicon`

對 Favicon API 的訪問權限。

29. `fileBrowserHandler`

對 chrome.fileBrowserHandler API 的訪問權限。

30. `fileSystemProvider`

對 chrome.fileSystemProvider API 的訪問權限。

31. `fontSettings`

對 chrome.fontSettings API 的訪問權限。

32. `gcm`

對 chrome.gcm 和 chrome.instanceID API 的訪問權限。

33. `geolocation`

允許擴展程序在不提示用户授予權限的情況下使用 geolocation API。

34. `history`

對 chrome.history API 的訪問權限。

35. `identity`

對 chrome.identity API 的訪問權限。

36. `idle`

對 chrome.idle API 的訪問權限。

37. `loginState`

對 chrome.loginState API 的訪問權限。

38. `management`

對 chrome.management API 的訪問權限。

39. `nativeMessaging`

對 Native Messaging API 的訪問權限。

40. `notifications`

對 chrome.notifications API 的訪問權限。

41. `offscreen`

對 chrome.offscreen API 的訪問權限。

42. `pageCapture`

對 chrome.pageCapture API 的訪問權限。

43. `platformKeys`

對 chrome.platformKeys API 的訪問權限。

44. `power`

對 chrome.power API 的訪問權限。

45. `printerProvider`

對 chrome.printerProvider API 的訪問權限。

46. `printing`

對 chrome.printing API 的訪問權限。

47. `printingMetrics`

對 chrome.printingMetrics API 的訪問權限。

48. `privacy`

對 chrome.privacy API 的訪問權限。

49. `processes`

對 chrome.processes API 的訪問權限。

50. `proxy`

對 chrome.proxy API 的訪問權限。

51. `runtime`

對 runtime.connectNative() 和 runtime.sendNativeMessage() 的訪問權限。對於 runtime 命名空間的所有其他功能，無需任何權限。

52. `scripting`

對 chrome.scripting API 的訪問權限。

53. `search`

對 chrome.search API 的訪問權限。

54. `sessions`

對 chrome.sessions API 的訪問權限。

55. `sidePanel`

對 chrome.sidePanel API 的訪問權限。

56. `storage`

對 chrome.storage API 的訪問權限。

57. `system.cpu`

對 chrome.system.cpu API 的訪問權限。

58. `system.display`

對 chrome.system.display API 的訪問權限。

59. `system.memory`

對 chrome.system.memory API 的訪問權限。

60. `system.storage`

對 chrome.system.storage API 的訪問權限。

61. `tabCapture`

對 chrome.tabCapture API 的訪問權限。

62. `tabGroups`

對 chrome.tabGroups API 的訪問權限。

63. `tabs`

對多個 API（包括 chrome.tabs 和 chrome.windows）使用的 Tab 對象的特權字段的訪問權限。

64. `topSites`

對 chrome.topSites API 的訪問權限。

65. `tts`

對 chrome.tts API 的訪問權限。

66. `ttsEngine`

對 chrome.ttsEngine API 的訪問權限。

67. `unlimitedStorage`

針對 chrome.storage.local、IndexedDB 提供無限制的配額，
為 chrome.storage.local、IndexedDB、Cache Storage 和 Origin Private File System 提供無限制的配額。

68. `vpnProvider`

對 chrome.vpnProvider API 的訪問權限。

69. `wallpaper`

對 chrome.wallpaper API 的訪問權限。

70. `webAuthenticationProxy`

對 chrome.webAuthenticationProxy API 的訪問權限。

71. `webNavigation`

對 chrome.webNavigation API 的訪問權限。

72. `webRequest`

對 chrome.webRequest API 的訪問權限。

73. `webRequestBlocking`

允許使用 chrome.webRequest API 進行屏蔽。

六、可選權限

1. 確定必需權限和可選權限

擴展程序可以聲明必需權限和可選權限。
- 如果擴展程序的基本功能需要用到所需權限，請使用這些權限。
- 如果擴展程序中的可選功能需要用到可選權限，請使用這些權限。
必需權限的優點：
- 提示更少：擴展程序可以提示用户接受所有權限一次。
- 開發更簡單：必要權限必定存在。
可選權限的優點：
- 安全性更高：由於用户僅啓用所需的權限，因此擴展程序能夠以更少的權限運行。
- 為用户提供更實用的信息：在用户啓用相關功能時，擴展程序可以解釋為什麼它需要特定權限。
- 升級更輕鬆：升級擴展程序時，如果升級過程增加了可選權限而非必需權限，Chrome 不會為用户停用該擴展程序。
2. 在 Manifest.json 中聲明可選權限

使用 optional_permissions 鍵在擴展程序清單中聲明可選權限，格式與 permissions 字段相同：
```
{
"name": "My extension",
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
}
```
2.1 無法指定為可選的權限

大多數 Chrome 擴展程序權限均可指定為可選權限，但以下權限除外。
debugger
declarativeNetRequest"devtools
experimental
geolocation
mdns
proxy
tts
ttsEngine

wallpaper

3. 請求可選權限

示例：
使用 permissions.request() 在 click 中請求權限：

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.
  // 如果用户授予權限，則callback參數將為true。
  if (granted) {
    doSomething();
  } else {
    doSomethingElse();
  }
});
});

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).
}
});

七、類型（`Types`）

1. `Permissions` 屬性

1.1 `origins`

string[] 選填
主機權限的列表，包括清單中的 optional_permissions 或 permissions 鍵中指定的權限，以及與內容腳本相關聯的權限。

1.2 permissions
string[] 選填
已命名權限（不包括主機或源）的列表。

八、方法（Methods）

1. contains()

檢查擴展程序是否具有指定權限。

1.1 示例
```
chrome.permissions.contains(
permissions:
Permissions,
callback?:
function,
)
```
1.2 參數
permissions: Permissions
callback: function 可選 (result: boolean) => void

1.3 返回
Promise<boolean>
如果擴展程序具有指定的權限，則為 true。如果將某個來源同時指定為可選權限和內容腳本匹配模式，則返回 false，除非同時授予這兩項權限。

2. getAll()

獲取擴展程序的當前權限集。

2.1 示例
```
chrome.permissions.getAll(
callback?:
function,
)
```
2.2 參數
callback: function 可選 (permissions: Permissions)=>void

2.3 返回
Promise<Permissions>
擴展程序的有效權限。

3. remove()

移除對指定權限的訪問權限。

3.1 示例
```
chrome.permissions.remove(
permissions:
Permissions,
callback?:
function,
)
```
3.2 參數
permissions: Permissions
callback: function 可選 (removed: boolean)=>void

3.3 返回
Promise<boolean>
如果權限已移除，則為 true。

4. request()

請求訪問指定權限，必要時向用户顯示提示。這些權限必須在清單的 optional_permissions 字段中定義，或者是用户保留的必需權限。

4.1 示例
```
chrome.permissions.request(
permissions:
Permissions,
callback?:
function,
)
```
4.2 參數
permissions: Permissions
callback: function 可選 (granted: boolean)=>void

4.3 返回
Promise<boolean>
如果用户授予了指定的權限，則為 true。

九、事件（Events）

1. onAdded

在擴展程序獲取新權限時觸發。

1.1 示例
```
chrome.permissions.onAdded.addListener(
callback:
function,
)
```
1.2 參數
callback: function
```
(permissions:  Permissions)=>void
```

2. `onRemoved`

在移除擴展程序的權限時觸發。

2.1 參數

callback: function
```
(permissions:  Permissions)=>void
```

引用

【permissions】
【declare-permissions】

月恆 動態日志

@gqkmiss

標簽

前端 (1158)

Javascript (735)

人工智能 (486)

Python (289)

vue.js (260)

react (167)

node.js (141)

chrome (57)

ecmascript-6 (55)

性能優化 (53)

llm (53)

瀏覽器 (43)

動態

Chrome 瀏覽器插件 Manifest.json V3 中權限（Permissions）字段解析 - 動態 詳情

一、權限（Permissions）

一、權限類型

二、Manifest.json 示例

三、主機權限（Host permissions）

四、包含警告的權限

1. 權限警告列表

五、權限列表

1. accessibilityFeatures.modify

2. accessibilityFeatures.read

3. activeTab

4. alarms

5. audio

6. background

7. bookmarks

8. browsingData

9. certificateProvider

10. contentSettings

11. contextMenus

12. cookies

13. debugger

14. declarativeContent

15. declarativeNetRequest

16. declarativeNetRequestWithHostAccess

17. declarativeNetRequestFeedback

18. dns

19. desktopCapture

20. documentScan

21. downloads

22. downloads.open

23. downloads.ui

24. enterprise.deviceAttributes

25. enterprise.hardwarePlatform

26. enterprise.networkingAttributes

27. enterprise.platformKeys

28. favicon

29. fileBrowserHandler

30. fileSystemProvider

31. fontSettings

32. gcm

33. geolocation

34. history

35. identity

36. idle

37. loginState

38. management

39. nativeMessaging

40. notifications

41. offscreen

42. pageCapture

43. platformKeys

44. power

45. printerProvider

46. printing

47. printingMetrics

48. privacy

49. processes

50. proxy

51. runtime

52. scripting

53. search

54. sessions

55. sidePanel

56. storage

月恆動態日志

Chrome 瀏覽器插件 Manifest.json V3 中權限（Permissions）字段解析 - 動態詳情