chrome.permissions

Description

使用 chrome.permissions API 在运行时而不是安装时请求声明的可选权限declared optional permissions，以便用户了解为什么需要这些权限并只授予那些必要的权限。

# Implementing optional permissions(实现可选权限)

# Step 1: Decide which permissions are required and which are optional(步骤 1：决定哪些权限是必需的，哪些是可选的)

扩展可以声明必需和可选的权限。一般来说，你应该：

• 在扩展的基本功能需要时使用所需的权限。
• 在扩展中的可选功能需要时使用可选权限。

所需权限的优点：

• 更少的提示：一个扩展可以提示用户一次接受所有权限。
• 更简单的开发：保证存在所需的权限。

可选权限的优点：

• 更好的安全性：扩展程序以较少的权限运行，因为用户只启用所需的权限。
• 为用户提供更好的信息：当用户启用相关功能时，扩展程序可以解释为什么它需要特定权限。
• 更轻松的升级：当您升级扩展程序时，如果升级添加了可选而非必需的权限，Chrome 不会为您的用户禁用它。

# Step 2: Declare optional permissions in the manifest(第 2 步：在清单中声明可选权限)

使用 optional_permissions 键在扩展清单中声明可选权限，使用与权限字段相同的格式：

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "host_permissions": ["https://www.google.com/"],
  ...
}

如果您想请求仅在运行时发现的主机，请在 Manifest V3 扩展的 host_permissions 字段（或 Manifest V2 的 optional_permissions）中包含“https://*/”。这允许您在 Permissions.origins 中指定任何来源，只要它具有匹配的方案。

不能指定为可选的权限

大多数 Chrome 扩展程序权限都可以指定为可选，但以下情况除外。

查看声明权限和警告用户（Declare Permissions and Warn Users）以获取有关可用权限及其警告的更多信息。

# Step 3: Request optional permissions(第 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();
    }
  });
});

如果添加权限导致与用户已经看到和接受的警告消息不同的警告消息（warning messages），Chrome 会提示用户。例如，前面的代码可能会导致如下提示：

# Step 4: Check the extension's current permissions(第 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.
  }
});

# Step 5: Remove 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).
  }
});

Summary

• Types

  Permissions

• Methods

  contains

  getAll

  remove

  request

• Events

  onAdded

  onRemoved

Types

Permissions

PROPERTIES

• origins

  string[] optional

  主机权限列表，包括在 optional_permissions 或清单中的permissions键中指定的权限，以及与内容脚本（Content Scripts）关联的权限。

• permissions

  string[] optional

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

Methods

contains

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

Promise

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

PARAMETERS

• permissions

  Permissions

• callback

  function optional

  The callback parameter looks like:

  (result: boolean) => void

  • result

    boolean

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

RETURNS

• Promise<boolean>

  Pending

  这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getAll

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

Promise

获取扩展的当前权限集。

PARAMETERS

• callback

  function optional

  The callback parameter looks like:

  (permissions: Permissions) => void

  • permissions

    Permissions

    扩展的活动权限。请注意， origins 属性将包含来自清单中的permissions和 optional_permissions 键中指定的源以及与内容脚本（Content Scripts）相关联的源。

RETURNS

• Promise<Permissions>

  Pending

  这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

remove

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

Promise

删除对指定权限的访问。如果删除权限有任何问题，runtime.lastError 将被设置。

PARAMETERS

• permissions

  Permissions

• callback

  function optional

  The callback parameter looks like:

  (removed: boolean) => void

  • removed

    boolean

    如果删除了权限，则为真。

RETURNS

• Promise<boolean>

  Pending

  这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

request

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

Promise

请求访问指定的权限，必要时向用户显示提示。这些权限必须在清单的 optional_permissions 字段中定义，或者是用户保留的必需权限。原始模式上的路径将被忽略。您可以请求可选原始权限的子集；例如，如果您在清单的 optional_permissions 部分指定 *://*\/* ，则可以请求 http://example.com/。如果在请求权限时出现任何问题，将设置 runtime.lastError。

PARAMETERS

• permissions

  Permissions

• callback

  function optional

  The callback parameter looks like:

  (granted: boolean) => void

  • granted

    boolean

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

RETURNS

• Promise<boolean>

  Pending

  这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

Events

onAdded

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

当扩展获得新权限时触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (permissions: Permissions) => void

  • permissions

    Permissions

onRemoved

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

当从扩展中删除对权限的访问时触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (permissions: Permissions) => void

  • permissions

    Permissions

By.一粒技术服务.