diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/webextensions/api/permissions/index.html')
| -rw-r--r-- | files/zh-cn/mozilla/add-ons/webextensions/api/permissions/index.html | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/index.html new file mode 100644 index 0000000000..df6c1c8e5c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/index.html @@ -0,0 +1,93 @@ +--- +title: permissions +slug: Mozilla/Add-ons/WebExtensions/API/permissions +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Permissions + - Reference + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/permissions +--- +<div>{{AddonSidebar}}</div> + +<div>Enables extensions to request extra permissions at runtime, after they have been installed.</div> + +<div></div> + +<p>Extensions need permissions to access more powerful WebExtension APIs. They can ask for permissions at install time, by including the permissions they need in the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> manifest.json key. The main advantages of asking for permissions at install time are:</p> + +<ul> + <li>The user is only asked once, so it's less disruptive for them, and a simpler decision.</li> + <li>The extension can rely on the access to the APIs it needs, because if already running, the permissions have been granted.</li> +</ul> + +<p>There is not yet a simple GUI, for users to view permissions of their installed WebExtension Add-ons. Users must use about:debugging, go to the Add-ons section, then use the "Manifest Url" link for this Add-on. This shows raw json, which includes a "permissions" block, showing the permissions used by this addon.</p> + +<p>With the permissions API, an extension can ask for additional permissions at runtime. These permissions need to be listed in the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code> manifest.json key. Note that some permissions are not allowed in <code>optional_permissions</code>. The main advantages of this are:</p> + +<ul> + <li>The extension can run with a smaller set of permissions, except when it actually needs them.</li> + <li>The extension can handle permission denial in a graceful manner, instead of presenting the user with a global "all or nothing" choice at install time. You can still get a lot out of that map extension, without giving it access to your location, for example.</li> + <li> + <p>The extension may need <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permissions</a>, but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, asking for a more specific range of hosts at runtime, can be an alternative to asking for "<all_urls>" at install time.</p> + </li> +</ul> + +<div>To use the permissions API, decide which permissions your extension can request at runtime, and list them in <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code>. After this, you can request any permissions that were included in <code>optional_permissions</code>. Requests may only be made in the handler for a user action (for example, a click handler).</div> + +<div></div> + +<div>For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Request_the_right_permissions#Request_permissions_at_runtime">Request permissions at runtime</a>.</div> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("permissions.Permissions")}}</dt> + <dd>Represents a set of permissions.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{WebExtAPIRef("permissions.contains()")}}</dt> + <dd>Discover an extension's given set of permissions.</dd> + <dt>{{WebExtAPIRef("permissions.getAll()")}}</dt> + <dd>Get all the permissions this extension currently has.</dd> + <dt>{{WebExtAPIRef("permissions.remove()")}}</dt> + <dd>Give up a set of permissions.</dd> + <dt>{{WebExtAPIRef("permissions.request()")}}</dt> + <dd>Ask for a set of permissions.</dd> +</dl> + +<h2 id="Event_handlers">Event handlers</h2> + +<dl> + <dt>{{WebExtAPIRef("permissions.onAdded")}}</dt> + <dd>Fired when a new permission is granted.</dd> + <dt>{{WebExtAPIRef("permissions.onRemoved")}}</dt> + <dd>Fired when a permission is removed.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.permissions")}}</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><code>manifest.json</code> <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> property</li> + <li><code>manifest.json</code> <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions">optional_permissions</a></code> property</li> +</ul> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/permissions"><code>chrome.permissions</code></a> API.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> |