# Optional Permissions ## 内容 1. [在一个扩展中实现可选权限](permissions.html#howto) 1. [步骤1：确定哪些权限作为可选，哪些作为必选。](permissions.html#types) 2. [步骤2：在manifest文件中声明可选权限](permissions.html#manifest_) 3. [步骤3：扩展运行过程中请求可选权限](permissions.html#request) 4. [步骤4：扩展运行过程中检查的当前已有的权限](permissions.html#contains) 5. [步骤5：扩展运行过程删除不再需要的权限](permissions.html#remove) 2. [API 参考：Chrome.permissions](permissions.html#apiReference) 1. [方法](permissions.html#global-methods) 1. [contains](permissions.html#method-contains) 2. [getAll](permissions.html#method-getAll) 3. [remove](permissions.html#method-remove) 4. [request](permissions.html#method-request) 2. [事件](permissions.html#global-events) 1. [onAdded](permissions.html#event-onAdded) 2. [onRemoved](permissions.html#event-onRemoved) 3. [类型](permissions.html#types_) 1. [Permissions](permissions.html#type-Permissions) `Chrome.permissions`用于实现可选权限。在您扩展的运行过程中，而不是在安装的时候请求权限。这能帮助用户清楚为什需要此权限，且仅在必要的时候才运行扩展使用此权限。 关于权限的相关信息及每个权限的详细信息，可参见manifest章节的[permissions](manifest.html#permissions)。 ## 实现可选权限 ### 步骤1：确定哪些权限作为可选，哪些权限作为必选。 为了满足基本的功能，扩展需要一些必须的权限，而另一些权限则可以在扩展运行过程再请求用户授予。 可选权限的优势： * 扩展激活时仅仅需要少量的权限，扩展运行中需要时才请求用户授予更多的权限。 * 当扩展运行过程中请求更多权限时，可以更清楚地向用户解释为什么需要这些特定的权限。 * 可以避免Chrome浏览器禁止扩展升级（原因：当一个扩展的新版本相比老版本需要更多必选权限时，Chrome会阻止这样的扩展的自动升级）。 必选权限的优点： * 扩展可以一次性提示用户接受所需的权限。 * 扩展运行过程可以确保拥有相关权限，从而简化了扩展的开发。 ### 步骤2：在manifest文件中声明可选权限 在[extension manifest](manifest.html)中用`optional_permissions`关键字声明可选权限，与声明[permissions](manifest.html#permissions)相同： <a name="h2-2"> ``` { "name": "My extension", ... **"optional_permissions": [ "tabs", "http://www.google.com/" ],** ... } ``` </a> 您可以指定下列任何可选权限： * _host permissions_ * appNotifications * background * bookmarks * clipboardRead * clipboardWrite * contentSettings * contextMenus * cookies * debugger * history * idle * management * notifications * pageCapture * tabs * topSites * webNavigation * webRequest * webRequestBlocking **版本说明：**此列表适用于Chrome 17。在之后的版本中会提供更多的可选权限。 ### 步骤3：请求可选权限 通过调用`permissions.request()`请求权限，并且需要获得用户授权： <a name="h2-2"> ``` document.querySelector('#my-button').addEventListener('click', function(event) { // Permissions must be requested from inside a user gesture, like a button's // click handler. Chrome.permissions.request({ permissions: ['tabs'], origins: ['http://www.google.com/'] }, function(granted) { // The callback argument will be true if the user granted the permissions. if (granted) { doSomething(); } else { doSomethingElse(); } }); }); ``` </a> 如果添加与用户看到和接受的权限不同。Chrome会提示用户[warning messages](http://code.google.com/chrome/extensions/permission_warnings.html)。比如，上面的示例代码会导致这样的提示：  ### 步骤4：检查扩展的当前权限 检查扩展是否拥有特定的权限，可以通过`permission.contains()`实现： <a name="h2-2"> ``` Chrome.permissions.contains({ permissions: ['tabs'], origins: ['http://www.google.com/'] }, function(result) { if (result) { // The extension has the permissions. } else { // The extension doesn't have the permissions. } }); ``` </a> ### 步骤5：删除权限 您应该删除不再需要的权限。当某个用户已授权权限被删除后，使用`permissions.request()`再次添加此权限时不会再提示用户。 <a name="h2-2"> ``` Chrome.permissions.remove({ permissions: ['tabs'], origins: ['http://www.google.com/'] }, function(removed) { if (removed) { // The permissions have been removed. } else { // The permissions have not been removed (e.g., you tried to remove // required permissions). } }); ``` </a> ## API 参考：Chrome.permissions ### 方法 #### contains Chrome.permissions.contains(Permissions `permissions`, function `callback`) 检查是否拥有某些权限。 #### 参数 `permissions`_( [Permissions](permissions.html#type-Permissions) )_ Undocumented. `callback`_( function )_ Undocumented. #### Callback function 如果需要指定_回调函数_，则回调函数格式如下： ``` function(boolean result) {...}; ``` `result`_( boolean )_ 如果扩展已拥有指定的权限，返回true。 #### getAll Chrome.permissions.getAll(function `callback`) 获取扩展当前的权限。 #### 参数 `callback`_( function )_ Undocumented. #### Callback function 如果需要指定_回调函数_，则回调函数格式如下： ``` function(Permissions permissions) {...}; ``` `permissions`_( [Permissions](permissions.html#type-Permissions) )_ 扩展当前拥有的权限。 #### remove Chrome.permissions.remove(Permissions `permissions`, function `callback`) 删除指定的权限。如果在删除过程中出现异常，[Chrome.extension.lastError](extension.html#property-lastError)将会被设置 #### 参数 `permissions`_( [Permissions](permissions.html#type-Permissions) )_ Undocumented. `callback`_( optional function )_ Undocumented. #### Callback function 如果需要指定_回调函数_，则回调函数格式如下： ``` function(boolean removed) {...}; ``` `removed`_( boolean )_ 如果成功删除，返回true。 #### request Chrome.permissions.request(Permissions `permissions`, function `callback`) 请求指定的权限。所请求的权限必需包含在manifest文件的optional_permissions里。如果在删除过程中出现异常，[Chrome.extension.lastError](extension.html#property-lastError)将会被设置 #### 参数 `permissions`_( [Permissions](permissions.html#type-Permissions) )_ Undocumented. `callback`_( optional function )_ Undocumented. #### Callback function 如果需要指定_回调函数_，则回调函数格式如下： ``` function(boolean granted) {...}; ``` `granted`_( boolean )_ 如果用户授予请求的权限，返回true。 ### 事件 #### onAdded Chrome.permissions.onAdded.addListener(function(Permissions permissions) {...}); 在扩展获得新的权限时触发。 #### 参数 `permissions`_( [Permissions](permissions.html#type-Permissions) )_ 新获得的权限。 #### onRemoved Chrome.permissions.onRemoved.addListener(function(Permissions permissions) {...}); Fired when access to permissions has been removed from the extension. #### 参数 `permissions`_( [Permissions](permissions.html#type-Permissions) )_ 被删除的权限。 ### 类型 #### Permissions _( object )_ Undocumented. `permissions`_( optional array of string )_ 权限名列表（不包括hosts或者origins）。 `origins`_( optional array of string )_ 原始权限列表。