# 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 )_ 原始權限列表。