说明
请使用 chrome.permissions
API 在运行时(而不是安装时)请求声明的可选权限,以便用户了解需要相关权限的原因,并仅授予必要的权限。
概念和用法
权限警告旨在描述 API 授予的功能,但其中一些警告可能并不明显。Permissions API 允许开发者解释权限警告并逐步推出新功能,以便用户放心地了解扩展程序。这样,用户就可以指定他们愿意授予多少访问权限以及想要启用哪些功能。
例如,可选权限扩展程序的核心功能将替换新标签页。其中一项功能是显示用户当天的目标。此功能仅需要 storage 权限,不包括警告。该扩展程序还有一项附加功能,用户可通过点击以下按钮启用该功能:
![一个扩展程序按钮,可启用更多功能。](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=9&hl=nb)
显示用户浏览次数最多的网站需要 topSites 权限,但权限却有以下警告。
![针对 topSites API 的拉伸警告。](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=9&hl=nb)
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 会提示用户。例如,上述代码可能会导致如下所示的提示:
![权限确认提示示例。](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=9&hl=nb)
第 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()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
检查扩展程序是否具有指定的权限。
参数
-
权限
-
callback
函数(可选)
callback
参数如下所示:(result: boolean) => void
-
结果
boolean
如果扩展程序具有指定的权限,则为“true”。如果将某个来源同时指定为可选权限和内容脚本匹配模式,则系统将返回
false
,除非同时授予这两项权限。
-
返回
-
Promise<boolean>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getAll()
chrome.permissions.getAll(
callback?: function,
)
获取扩展程序的当前权限集。
参数
-
callback
函数(可选)
callback
参数如下所示:(permissions: Permissions) => void
返回
-
Chrome 96 及更高版本
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
remove()
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()
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
-
权限
-