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 开发者工具 功能
"experimental" Canary 版和开发者版 。向扩展程序授予对 chrome.experimental API 的访问权限。
"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();
    }
  });
});

如果添加权限导致的警告消息与 用户已经看到并接受的内容。例如，之前的代码可能会导致如下提示： ：

权限确认提示示例

第 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()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

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

返回

  • Promise&lt;boolean&gt;

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.permissions.getAll(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (permissions: Permissions) => void

    • 权限

      权限

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

返回

  • Promise&lt;Permissions&gt;

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

remove()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (removed: boolean) => void

    • 已移除

      布尔值

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

返回

  • Promise&lt;boolean&gt;

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

request()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (granted: boolean) => void

    • 同意

      布尔值

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

返回

  • Promise&lt;boolean&gt;

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 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