chrome.permissions

说明

请使用 chrome.permissions API 在运行时（而不是安装时）请求声明的可选权限，以便用户了解需要相关权限的原因，并仅授予必要的权限。

概念和用法

权限警告旨在描述 API 授予的功能，但其中一些警告可能并不明显。Permissions API 允许开发者解释权限警告并逐步推出新功能，以便用户放心地了解扩展程序。这样，用户就可以指定他们愿意授予多少访问权限以及想要启用哪些功能。

例如，可选权限扩展程序的核心功能将替换新标签页。其中一项功能是显示用户当天的目标。此功能仅需要 storage 权限，不包括警告。该扩展程序还有一项附加功能，用户可通过点击以下按钮启用该功能：

用于启用更多功能的扩展程序按钮。

显示用户浏览次数最多的网站需要 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 开发者工具功能。
"geolocation"	允许此扩展程序使用 HTML5 geolocation API。
"mdns"	向扩展程序授予对 chrome.mdns API 的访问权限。
"proxy"	向扩展程序授予对 chrome.proxy API 的访问权限，以便管理 Chrome 的代理设置。
"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[] 可选

  列出已命名的权限（不包括主机或源）。

方法

contains()

Promise

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

检查扩展程序是否具有指定的权限。

参数

• 权限

  权限

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean)=>void

  • 结果

    boolean

    如果扩展程序具有指定的权限，则为“true”。如果将某个来源同时指定为可选权限和内容脚本匹配模式，则系统将返回 false，除非同时授予这两项权限。

返回

• Promise<boolean>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAll()

Promise

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

获取扩展程序的当前权限集。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (permissions: Permissions)=>void

  • 权限

    权限

    扩展程序的有效权限。请注意，origins 属性将包含清单中的 permissions 和 optional_permissions 键中指定的已授权来源，以及与内容脚本关联的来源。

返回

• Promise<权限>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

remove()

Promise

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

移除对指定权限的访问权限。如果在移除权限时出现任何问题，系统会设置 runtime.lastError。

参数

• 权限

  权限

• callback

  函数（可选）

  callback 参数如下所示：

  (removed: boolean)=>void

  • 已删除

    boolean

    如果权限已移除，则为“true”。

返回

• Promise<boolean>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

request()

Promise

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

请求访问指定的权限，如有必要，系统会向用户显示提示。这些权限必须在清单的 optional_permissions 字段中定义，或者是用户未授予的必需权限。基于原始模式的路径将被忽略。您可以请求部分可选的来源权限；例如，如果您在清单的 optional_permissions 部分中指定 *://*\/*，则可以请求 http://example.com/。如果在请求权限时遇到任何问题，系统将设置 runtime.lastError。

参数

• 权限

  权限

• callback

  函数（可选）

  callback 参数如下所示：

  (granted: boolean)=>void

  • 同意

    boolean

    如果用户授予指定权限，则为 true。

返回

• Promise<boolean>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onAdded

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

在扩展程序获取新权限时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (permissions: Permissions)=>void

  • 权限

    权限

onRemoved

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

在移除扩展程序的权限时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (permissions: Permissions)=>void

  • 权限

    权限