chrome.permissions

说明

概览

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

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

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

实现可选权限

第 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 扩展程序权限都可以指定为可选，但以下权限除外。

如需详细了解可用权限及其警告，请参阅声明权限并向用户发出警告。

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

chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

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

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

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

chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

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

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

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