chrome.permissions

说明

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

概念和用法

权限警告旨在说明 API 授予的功能，但其中一些警告可能并不明显。借助 Permissions API，开发者可以解释权限警告并逐步引入新功能，从而让用户能够无风险地了解扩展程序。这样，用户可以指定他们愿意授予的访问权限级别以及他们想要启用的功能。

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

用于启用其他功能的扩展程序按钮。
用于启用其他功能的扩展程序按钮。

如需显示用户的热门网站，需要 topSites 权限，该权限会显示以下警告。

针对 topSites API 的扩展程序警告。
针对 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 地理定位 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[] 可选

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

方法

addHostAccessRequest()

Promise 待处理MV3+ 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

添加主机访问权限请求。只有在扩展程序可以获得请求中主机的访问权限时，系统才会向用户发出请求信号。在跨源导航时，请求将重置。被接受后，会授予对网站主要来源的永久访问权限

参数

  • request

    对象

    • documentId

      字符串（选填）

      可显示主机访问权限请求的文档的 ID。必须是标签页中的顶级文档。如果已提供，该请求会显示在指定文档的标签页中，并会在文档导航到新来源时移除。添加新请求会覆盖 tabId 的所有现有请求。必须指定此值或 tabId。

    • 图案

      字符串（选填）

      可以显示主机访问权限请求的网址格式。如果已提供，主机访问权限请求将仅显示在与此模式匹配的网址上。

    • tabId

      number 可选

      用于显示主机访问权限请求的标签页的 ID。如果已提供，请求会显示在指定标签页上，并会在该标签页导航到新来源时移除。添加新请求会覆盖现有的 documentId 请求。必须指定此值或 documentId。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

contains()

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

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

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

返回

  • Promise<boolean>

    Chrome 96 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getAll()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (permissions: Permissions) => void

    • 权限

      权限

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

返回

  • Promise<权限>

    Chrome 96 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

remove()

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

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (removed: boolean) => void

    • 已移除

      布尔值

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

返回

  • Promise<boolean>

    Chrome 96 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

removeHostAccessRequest()

Promise 待处理MV3+ 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

移除主机访问请求（如果存在）。

参数

  • request

    对象

    • documentId

      字符串（选填）

      要移除主机访问权限请求的文档的 ID。必须是标签页中的顶级文档。必须指定此值或 tabId。

    • 图案

      字符串（选填）

      要移除主机访问权限请求的网址格式。如果提供，此值必须与现有主机访问请求的模式完全匹配。

    • tabId

      number 可选

      要移除主机访问权限请求的标签页的 ID。必须指定此值或 documentId。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

request()

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

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

参数

  • 权限

    权限

  • callback

    函数（可选）

    callback 参数如下所示： 

    (granted: boolean) => void

    • 同意

      布尔值

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

返回

  • Promise<boolean>

    Chrome 96 及更高版本

    清单 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