diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/webextensions/api')
63 files changed, 7109 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/create/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/create/index.html new file mode 100644 index 0000000000..ac3bafecc4 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/create/index.html @@ -0,0 +1,127 @@ +--- +title: alarms.create() +slug: Mozilla/Add-ons/WebExtensions/API/alarms/create +tags: + - API + - WebExtensions + - alarms + - 创建 + - 参考 + - 拓展 + - 方法 + - 附件 + - 非标准 +translation_of: Mozilla/Add-ons/WebExtensions/API/alarms/create +--- +<div>{{AddonSidebar()}}</div> + +<p>创建一个新的alarm.</p> + +<h2 id="使用语法">使用语法</h2> + +<pre class="syntaxbox brush:js">browser.alarms.create( + name, // 可选的字符串(string)类型 + alarmInfo // 可选的对象(object)类型 +) +</pre> + +<h3 id="参数介绍">参数介绍</h3> + +<dl> + <dt><code>name</code>{{optional_inline}}</dt> + <dd><code>字符串(string)类型。</code>alarm的名称。默认为空的字符串。</dd> + <dd>alarm的名称可以在{{WebExtAPIRef('alarms.get()')}}方法和{{WebExtAPIRef('alarms.clear()')}}方法中引用。同时它也可以通过{{WebExtAPIRef('alarms.onAlarm')}}监听方法传入的参数对象{{WebExtAPIRef('alarms.Alarm')}}的name属性访问到。</dd> + <dd>Alarm的名称是唯一的 (在单个附件范围内). 如果传入了已经在这个附件存在的名称， 原来的同名alarm会被移除并且没有警告。</dd> + <dt><code>alarmInfo</code>{{optional_inline}}</dt> + <dd> + <p><code>对象(object)类型</code>. 你可以对过它来指定什么时间alarm会开始触发，其值可以是一个具体的时间值或者是一个延时（从alarm设置开始）。为了让alarm能复现，需要指定<code>periodInMinutes。</code></p> + + <p>在Chrome浏览器上，除非附件以非打包(unpackaged)方式加载，alarm的创建每分钟不允许超过一次。如果附件尝试设置<code>delayInMinutes</code><code>为小于1的值，alarm只能在到达1分钟之后才会触发，并且会变成每分钟触发一次。</code></p> + + <p><code>alarmInfo对象</code>可以设置以下属性:</p> + </dd> + <dd> + <dl class="reference-values"> + <dt><code>when</code>{{optional_inline}}</dt> + <dd><code>double类型</code>. alarm第一次触发的时间，值为自1970-01-01 00:00:00 UTC过去的毫秒数。请使用<code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now">Date.now()</a>来获取</code>1970-01-01 00:00:00 UTC到<code>当前时间过去的毫秒数。如果你设置了when属性，请不要设置delayInMinutes属性。</code></dd> + <dt><code>delayInMinutes</code>{{optional_inline}}</dt> + <dd><code>double类型</code>. alarm设置好到第一次触发之间的分钟数。如果你设置了<code>delayInMinutes属性，请不要设置when属性。</code></dd> + <dt><code>periodInMinutes</code>{{optional_inline}}</dt> + <dd><code>double类型</code>. 如果设置此属性，alarm会从第一次触发开始每隔<code>periodInMinutes分钟再次触发。如果你没有设置when及delayInMinutes属性，alarm会在alarm设置好之后periodInMinutes分钟第一次触发。如果periodInMinutes属性没有设置，则alarm只会触发一次。</code></dd> + </dl> + </dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.alarms.create")}}</p> + +<h2 id="示例">示例</h2> + +<p>Create a one-time delay-based alarm with "" for the name:</p> + +<pre class="brush: js">const delayInMinutes = 5; + +<span class="pl-smi">browser</span>.<span class="pl-smi">alarms</span>.<span class="pl-en">create</span>({ + delayInMinutes +});</pre> + +<p>Create a periodic delay-based alarm named "my-periodic-alarm":</p> + +<pre class="brush: js">const delayInMinutes = 5; +const periodInMinutes = 2; + +browser.alarms.create("my-periodic-alarm", { + delayInMinutes, + periodInMinutes +});</pre> + +<p>Create a periodic absolute alarm named "my-periodic-alarm":</p> + +<pre class="brush: js">const when = 1545696000; +const periodInMinutes = 2; + +browser.alarms.create("my-periodic-alarm", { + when, + periodInMinutes +});</pre> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/alarms"><code>chrome.alarms</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/index.html new file mode 100644 index 0000000000..66b7c52339 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/alarms/index.html @@ -0,0 +1,58 @@ +--- +title: alarms +slug: Mozilla/Add-ons/WebExtensions/API/alarms +translation_of: Mozilla/Add-ons/WebExtensions/API/alarms +--- +<div>{{AddonSidebar}}</div> + +<p>在未来一个特定的时间运行的计划任务代码。这很像<code><a href="/zh-CN/docs/Web/API/WindowTimers/setTimeout">setTimeout()</a></code>和<code><a href="/zh-CN/docs/Web/API/WindowTimers/setInterval">setInterval()</a></code>，不过这些函数仅可以按需使用而不能在后台页面工作。</p> + +<p>想要使用这个API，您需要获取"alarms"的<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("alarms.Alarm")}}</dt> + <dd>Information about a particular alarm.</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("alarms.create()")}}</dt> + <dd>创建新的alarm.</dd> + <dt>{{WebExtAPIRef("alarms.get()")}}</dt> + <dd>通过名称获取指定的alarm.</dd> + <dt>{{WebExtAPIRef("alarms.getAll()")}}</dt> + <dd>获取所有的alarm.</dd> + <dt>{{WebExtAPIRef("alarms.clear()")}}</dt> + <dd>清除指定名称的alarm.</dd> + <dt>{{WebExtAPIRef("alarms.clearAll()")}}</dt> + <dd>清除所有的alarm.</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("alarms.onAlarm")}}</dt> + <dd>当alarm发生的时候触发.</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.alarms")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<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/alarms"><code>chrome.alarms</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> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/bookmarktreenode/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/bookmarktreenode/index.html new file mode 100644 index 0000000000..bec868a18d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/bookmarktreenode/index.html @@ -0,0 +1,81 @@ +--- +title: bookmarks.BookmarkTreeNode +slug: Mozilla/Add-ons/WebExtensions/API/bookmarks/BookmarkTreeNode +translation_of: Mozilla/Add-ons/WebExtensions/API/bookmarks/BookmarkTreeNode +--- +<p>{{AddonSidebar()}}</p> + +<p>代表书签树中的一个节点（书签或文件夹），子节点在它们的父文件夹中按顺序排列。</p> + +<h2 id="类型">类型</h2> + +<p>这种类型的值都是对象。它们包含以下属性：</p> + +<dl class="reference-values"> + <dt><code>id</code></dt> + <dd><code>string</code>. 节点的唯一标识符。唯一标识符在当前用户配置文件中保证唯一，并且在浏览器重新启动后仍然有效。</dd> + <dt><code>parentId</code>{{optional_inline}}</dt> + <dd><code>string</code>. 父节点的标识符（id）。根节点没有此属性。</dd> + <dt><code>index</code>{{optional_inline}}</dt> + <dd><code>integer</code>. 该节点在父文件夹中的位置（从 0 开始）。</dd> + <dt><code>url</code>{{optional_inline}}</dt> + <dd><code>string</code>. 当用户单击书签时打开的URL。文件夹没有此属性。</dd> + <dt><code>title</code></dt> + <dd><code>string</code>. 该节点显示的文字。</dd> + <dt><code>dateAdded</code>{{optional_inline}}</dt> + <dd><code>number</code>. 该节点创建的时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数（new Date(dateAdded)）。</dd> + <dt><code>dateGroupModified</code>{{optional_inline}}</dt> + <dd><code>number</code>. 该文件夹内容的上一次修改时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数。</dd> + <dt><code>unmodifiable</code>{{optional_inline}}</dt> + <dd>{{WebExtAPIRef('bookmarks.BookmarkTreeNodeUnmodifiable')}}. 表示该节点不可修改的原因，"<var>managed</var>"表示该节点由系统管理员配置。如果该节点可以由用户和扩展程序修改（默认）则省略。</dd> + <dt><code>children</code>{{optional_inline}}</dt> + <dd><code>array</code> of <code>{{WebExtAPIRef('bookmarks.BookmarkTreeNode')}}</code>. 该节点的所有子节点（已排序）。</dd> +</dl> + +<p> </p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.bookmarks.BookmarkTreeNode", 10)}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/bookmarks#type-BookmarkTreeNode"><code>chrome.bookmarks</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/bookmarks.json"><code>bookmarks.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/gettree/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/gettree/index.html new file mode 100644 index 0000000000..10571a1642 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/gettree/index.html @@ -0,0 +1,120 @@ +--- +title: bookmarks.getTree() +slug: Mozilla/Add-ons/WebExtensions/API/bookmarks/getTree +tags: + - API + - WebExtensions + - getTree + - 书签 + - 参考 + - 拓展 + - 方法 + - 附件 + - 非标准 +translation_of: Mozilla/Add-ons/WebExtensions/API/bookmarks/getTree +--- +<div>{{AddonSidebar()}}</div> + +<p><strong><code>bookmarks.getTree()</code></strong> 返回一个数组，该数组每一项为{{WebExtAPIRef("bookmarks.BookmarkTreeNode")}}对象，作为书签树的根节点。</p> + +<p>如果它们是文件夹的话，你可以通过其<code>children属性及其后代的children属性</code>递归地访问整个树。</p> + +<p>这是一个异步的函数，返回<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>。</code></p> + +<h2 id="使用格式">使用格式</h2> + +<pre class="syntaxbox brush:js">var gettingTree = browser.bookmarks.getTree() +</pre> + +<h3 id="参数">参数</h3> + +<p>无。</p> + +<h3 id="返回值">返回值</h3> + +<p><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>对象，该对象未来会得到一个填充代表根节点的</code><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/bookmarks/BookmarkTreeNode" title="An object of type bookmarks.BookmarkTreeNode represents a node in the bookmark tree, where each node is a bookmark or bookmark folder. Child nodes are ordered by an index within their respective parent folders.">bookmarks.BookmarkTreeNode</a>对象的数组。</code></p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p> </p> + +<p>{{Compat("webextensions.api.bookmarks.getTree")}}</p> + +<p> </p> + +<h2 id="示例">示例</h2> + +<p>这个示例会打印出整个书签树：</p> + +<pre class="brush: js">function makeIndent(indentLength) { + return ".".repeat(indentLength); +} + +function logItems(bookmarkItem, indent) { + if (bookmarkItem.url) { + console.log(makeIndent(indent) + bookmarkItem.url); + } else { + console.log(makeIndent(indent) + "Folder"); + indent++; + } + if (bookmarkItem.children) { + for (child of bookmarkItem.children) { + logItems(child, indent); + } + } + indent--; +} + +function logTree(bookmarkItems) { + logItems(bookmarkItems[0], 0); +} + +function onRejected(error) { + console.log(`An error: ${error}`); +} + +var gettingTree = browser.bookmarks.getTree(); +gettingTree.then(logTree, onRejected); +</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/bookmarks#method-getTree"><code>chrome.bookmarks</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/bookmarks.json"><code>bookmarks.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/index.html new file mode 100644 index 0000000000..06155a5972 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/index.html @@ -0,0 +1,128 @@ +--- +title: bookmarks +slug: Mozilla/Add-ons/WebExtensions/API/bookmarks +translation_of: Mozilla/Add-ons/WebExtensions/API/bookmarks +--- +<div>{{AddonSidebar}}</div> + +<p>此<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> {{WebExtAPIRef("bookmarks")}} API允许一个附加组件和浏览器的书签系统交互和操作。您可以用它给页面加书签，获取已有的书签，以及编辑，移除和管理书签。</p> + +<p>欲使用此API，一个附件组件必须请求"bookmarks" <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>在它的<code><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code>文件当中。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("bookmarks.BookmarkTreeNode")}}</dt> + <dd>表示在书签树中的一个书签或者文件夹。</dd> + <dt>{{WebExtAPIRef("bookmarks.BookmarkTreeNodeType")}}</dt> + <dd>一个描述在树中的一个节点是否是一个书签，一个文件夹或是一个分割符的 {{jsxref("String")}} 枚举类型。</dd> + <dt>{{WebExtAPIRef("bookmarks.BookmarkTreeNodeUnmodifiable")}}</dt> + <dd>一个说明了为什么一个书签或者文件夹是不可修改的 {{jsxref("String")}} 枚举类型。</dd> + <dt>{{WebExtAPIRef("bookmarks.CreateDetails")}}</dt> + <dd>当创建一个新书签时，包含被传递给这个 {{WebExtAPIRef("bookmarks.create()")}} 函数的信息。</dd> +</dl> + +<dl> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("bookmarks.create()")}}</dt> + <dd>创建一个书签或文件夹。</dd> + <dt>{{WebExtAPIRef("bookmarks.get()")}}</dt> + <dd>获得一个或者多个{{WebExtAPIRef("bookmarks.BookmarkTreeNode", "BookmarkTreeNode")}}，提供一个书签的编号或者一个书签编号的数组。</dd> + <dt>{{WebExtAPIRef("bookmarks.getChildren()")}}</dt> + <dd>获取指定{{WebExtAPIRef("bookmarks.BookmarkTreeNode", "BookmarkTreeNode")}}节点的所有子节点。</dd> + <dt>{{WebExtAPIRef("bookmarks.getRecent()")}}</dt> + <dd>获取最近添加的几个书签。</dd> + <dt>{{WebExtAPIRef("bookmarks.getSubTree()")}}</dt> + <dd>获取从指定节点开始的部分书签树。</dd> + <dt>{{WebExtAPIRef("bookmarks.getTree()")}}</dt> + <dd>获取整个书签树。</dd> + <dt>{{WebExtAPIRef("bookmarks.search()")}}</dt> + <dd>搜索书签树节点，找出匹配的结果。如果以对象方式指定查询，得到的 BookmarkTreeNodes 匹配所有指定的属性。</dd> + <dt>{{WebExtAPIRef("bookmarks.create()")}}</dt> + <dd>在指定的上一级文件夹下创建新的书签或文件夹。如果 url 为 null 或者省略，则创建文件夹。</dd> + <dt>{{WebExtAPIRef("bookmarks.move()")}}</dt> + <dd>将指定的书签树节点移到指定位置</dd> + <dt>{{WebExtAPIRef("bookmarks.update()")}}</dt> + <dd>更新书签或文件夹的属性。只需要指定您需要更改的属性，未指定的属性不会更改。注意：目前只支持“title”和“url”属性。</dd> + <dt>{{WebExtAPIRef("bookmarks.remove()")}}</dt> + <dd>删除书签或者空文件夹。</dd> + <dt>{{WebExtAPIRef("bookmarks.removeTree()")}}</dt> + <dd>删除整个书签文件夹。</dd> + <dt>{{WebExtAPIRef("bookmarks.import()")}}</dt> + <dd>从一个html书签文件导入书签</dd> + <dt>{{WebExtAPIRef("bookmarks.export()")}}</dt> + <dd>导出书签为一个html书签文件</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("bookmarks.onCreated")}}</dt> + <dd>当书签或文件夹创建时产生。</dd> + <dt>{{WebExtAPIRef("bookmarks.onRemoved")}}</dt> + <dd>当删除书签或文件夹时产生。当删除整个文件夹（包括其中所有内容）时，仅为该文件夹发送通知，不为其中任何内容发送通知。</dd> + <dt>{{WebExtAPIRef("bookmarks.onChanged")}}</dt> + <dd>一个书签或文件夹更改时发生。注意：目前只有标题和URL更改时会触发这一事件。</dd> + <dt>{{WebExtAPIRef("bookmarks.onMoved")}}</dt> + <dd>当书签或文件夹移动到另一个父文件夹中时产生。</dd> + <dt>{{WebExtAPIRef("bookmarks.onChildrenReordered")}}</dt> + <dd>文件夹中的子节点在用户界面中调整顺序时产生。调用 move() 不会触发该事件。</dd> + <dt>{{WebExtAPIRef("bookmarks.onImportBegan")}}</dt> + <dd>开始导入书签时产生。复杂的事件处理函数在这一事件产生后不应该再处理 onCreated 事件，直到 onImportEnded 事件产生，在此过程中其他事件仍然应该立即处理。</dd> + <dt>{{WebExtAPIRef("bookmarks.onImportEnded")}}</dt> + <dd>书签导入结束时产生。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.bookmarks")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<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/bookmarks"><code>chrome.bookmarks</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/bookmarks.json"><code>bookmarks.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/remove/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/remove/index.html new file mode 100644 index 0000000000..ee23ed285e --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/bookmarks/remove/index.html @@ -0,0 +1,106 @@ +--- +title: bookmarks.remove() +slug: Mozilla/Add-ons/WebExtensions/API/bookmarks/remove +tags: + - API + - Add-ons + - Bookmarks + - Method + - remove + - 书签 + - 参考文档 + - 扩展 + - 方法 + - 移除 +translation_of: Mozilla/Add-ons/WebExtensions/API/bookmarks/remove +--- +<div>{{AddonSidebar()}}</div> + +<p> <strong><code>bookmarks.remove()</code></strong> 方法用于删除单个书签或一个空的书签文件夹。</p> + +<div class="blockIndicator warning"> +<p>如果你的扩展尝试从书签树的根节点中移除一个书签，该调用将会引发一个“书签根不能被修改的”的错误信息并且这个书签不会被移除。</p> +</div> + +<p><code>这是一个异步方法，返回<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>对象。</code></p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var removingBookmark = browser.bookmarks.remove( + id // 字符串 +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>id</code></dt> + <dd>{{jsxref("string")}} 要删除的书签或空书签文件夹的id标识</dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>若方法执行完成，返回一个无参的 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>对象。</code></p> + +<p>若未找到该书签或该空书签文件夹，将返回一个带有错误信息的<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>对象。</code></p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.bookmarks.remove")}}</p> + +<h2 id="例子">例子</h2> + +<pre class="brush: js">function onRemoved() { + console.log("Removed!"); +} + +function onRejected(error) { + console.log(`An error: ${error}`); +} + +var bookmarkId = "abcdefghijkl"; + +var removingBookmark = browser.bookmarks.remove(bookmarkId); +removingBookmark.then(onRemoved, onRejected);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/bookmarks#method-remove"><code>chrome.bookmarks</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/bookmarks.json"><code>bookmarks.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/browseraction/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/browseraction/index.html new file mode 100644 index 0000000000..2d49dff094 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/browseraction/index.html @@ -0,0 +1,116 @@ +--- +title: browserAction +slug: Mozilla/Add-ons/WebExtensions/API/browserAction +translation_of: Mozilla/Add-ons/WebExtensions/API/browserAction +--- +<div>{{AddonSidebar}}</div> + +<p>添加按钮到浏览器的工具栏。</p> + +<p>您可以为该按钮指派一个弹出窗。弹出窗可采用 HTML、CSS 和 JavaScript 编写，就像是一个普通的网页。运行在该弹出窗中的 JavaScript 可以同您的后台脚本一样访问所有的 WebExtension API，但它的全局上下文是该弹出窗，而不是浏览器中的当前页面。要影响网页，您需要通过<a href="/en-US/Add-ons/WebExtensions/Modify_a_web_page#Messaging">消息</a>通信。</p> + +<p>如果您指定了弹出窗，它将显示——内容将在用户点击该图标时被加载。如果您没有指定一个弹出窗，用户单击该图标的事件将派发到您的扩展。</p> + +<p>您可以用 manifest.json 中的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 键值声明定义大多数浏览器动作属性。</p> + +<p>使用 <code>browserAction</code> API，您可以：</p> + +<ul> + <li>使用 {{WebExtAPIRef("browserAction.onClicked")}} 监听该图标的点击事件。</li> + <li>获取和设置该图标的属性——图标、标题、弹出窗等。 You can get and set these globally across all tabs, or for a specific tab by passing the tab ID as an additional argument.</li> +</ul> + +<p>另见<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_interface_components">用户界面组件</a>中的浏览器动作章节。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.ColorArray")}}</dt> + <dd>0-255范围内的四个整数的数组，定义RGBA颜色。</dd> + <dt>{{WebExtAPIRef("browserAction.ImageDataType")}}</dt> + <dd>一个图像的像素数据。必须为一个 <code><a href="/en-US/docs/Web/API/ImageData">ImageData</a></code> 对象（例如，来自一个 {{htmlelement("canvas")}} 元素）。</dd> +</dl> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.setTitle()")}}</dt> + <dd>设置浏览器动作的标题。这将在工具提示（鼠标悬停时）显示。</dd> + <dt>{{WebExtAPIRef("browserAction.getTitle()")}}</dt> + <dd>获取浏览器动作的标题。</dd> + <dt>{{WebExtAPIRef("browserAction.setIcon()")}}</dt> + <dd>设置浏览器动作的图标。</dd> + <dt>{{WebExtAPIRef("browserAction.setPopup()")}}</dt> + <dd>设置 HTML 文档作为浏览器动作图标被用户点击时显示的弹出窗。</dd> + <dt>{{WebExtAPIRef("browserAction.getPopup()")}}</dt> + <dd>获取作为浏览器动作的弹出窗的 HTML 文档。</dd> + <dt>{{WebExtAPIRef("browserAction.setBadgeText()")}}</dt> + <dd>设置浏览器动作的徽章文本。该徽章显示在图标上方。</dd> + <dt>{{WebExtAPIRef("browserAction.getBadgeText()")}}</dt> + <dd>获取浏览器动作的徽章文本。</dd> + <dt>{{WebExtAPIRef("browserAction.setBadgeBackgroundColor()")}}</dt> + <dd>设置徽章的后台颜色。</dd> + <dt>{{WebExtAPIRef("browserAction.getBadgeBackgroundColor()")}}</dt> + <dd>获取徽章的后台颜色。</dd> + <dt>{{WebExtAPIRef("browserAction.enable()")}}</dt> + <dd>为一个标签页启用浏览器动作。默认情况下，浏览器动作为所有标签页启用。</dd> + <dt>{{WebExtAPIRef("browserAction.disable()")}}</dt> + <dd>为一个标签页禁用浏览器动作，使该标签页为活动时无法单击它。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.onClicked")}}</dt> + <dd>在浏览器动作图标点击时被触发。如果浏览器动作有弹出窗，则该事件不会触发。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.browserAction")}}</p> + +<div class="hidden note"> +<p>"Chrome兼容性"是从 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> 包含，使用<a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a>宏。</p> + +<p>如果你需要更新此章节，编辑 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>，然后刷新查看更改。</p> +</div> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>致谢</strong> + +<p>此 API 基于 Chromium 的 <a href="https://developer.chrome.com/extensions/browserAction"><code>chrome.browserAction</code></a> API。此文档派生自 Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/browser_action.json"><code>browser_action.json</code></a>。</p> + +<p>Microsoft Edge 兼容性数据由微软公司提供，并以 知识共享 署名 3.0 美国版 许可。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/index.html new file mode 100644 index 0000000000..f58017fba8 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/index.html @@ -0,0 +1,90 @@ +--- +title: captivePortal +slug: Mozilla/Add-ons/WebExtensions/API/captivePortal +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - captivePortal +translation_of: Mozilla/Add-ons/WebExtensions/API/captivePortal +--- +<div>{{AddonSidebar}}</div> + +<p>Determine the captive portal state of the user’s connection. A captive portal is a web page displayed when a user first connects to a Wi-Fi network. The user provides information or acts on the captive portal web page to gain broader access to network resources, such as accepting terms and conditions or making a payment. </p> + +<p>To use this API you need to have the "captivePortal" <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("captivePortal.canonicalURL")}}</dt> + <dd>Return the canonical URL of the captive-portal detection page. Read-only.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("captivePortal.getLastChecked()")}}</dt> + <dd>Returns the time, in milliseconds, since the last request was completed.</dd> + <dt>{{WebExtAPIRef("captivePortal.getState()")}}</dt> + <dd>Returns the portal state as one of <code>unknown</code>, <code>not_captive</code>, <code>unlocked_portal</code>, or <code>locked_portal</code>.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("captivePortal.onConnectivityAvailable")}}</dt> + <dd>Fires when the captive portal service determines that the user can connect to the internet.</dd> + <dt>{{WebExtAPIRef("captivePortal.onStateChanged")}}</dt> + <dd> + <p>Fires when the captive portal state changes.</p> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.captivePortal")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/onstatechanged/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/onstatechanged/index.html new file mode 100644 index 0000000000..3211026253 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/captiveportal/onstatechanged/index.html @@ -0,0 +1,94 @@ +--- +title: onStateChanged +slug: Mozilla/Add-ons/WebExtensions/API/captivePortal/onStateChanged +translation_of: Mozilla/Add-ons/WebExtensions/API/captivePortal/onStateChanged +--- +<div>{{AddonSidebar()}}</div> + +<p>Fires when the captive portal state changes.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">browser.captivePortal.onStateChanged.addListener(callback) +browser.captivePortal.onStateChanged.removeListener(listener) +browser.captivePortal.onStateChanged.hasListener(listener) +</pre> + +<p>Events have three functions:</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>Adds a listener to this event.</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>Stop listening to this event. The <code>listener</code> argument is the listener to remove.</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>Check whether <code>listener</code> is registered for this event. Returns <code>true</code> if it is listening, <code>false</code> otherwise.</dd> +</dl> + +<h2 id="addListener_syntax">addListener syntax</h2> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>callback</code></dt> + <dd> + <p>Function that is called when this event occurs. The function is passed the following arguments:</p> + + <dl class="reference-values"> + <dt><code>details</code></dt> + <dd> + <p><code>string</code> The captive portal state, being one of <code>unknown</code>, <code>not_captive</code>, <code>unlocked_portal</code>, or <code>locked_portal</code>.</p> + </dd> + </dl> + </dd> +</dl> + +<h2 id="Examples">Examples</h2> + +<p>Handle a change in captive portal status:</p> + +<pre class="brush: js">function handlePortalStatus(portalstatusInfo) { + console.log("The portal status is now: " + portalstatusInfo.details); +} + +browser.captivePortal.onStateChanged.addListener(handlePortalStatus) +</pre> + +<p>{{WebExtExamples}}</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.captivePortal.onStateChanged")}}</p> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/contentscripts/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/contentscripts/index.html new file mode 100644 index 0000000000..544b32d556 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/contentscripts/index.html @@ -0,0 +1,41 @@ +--- +title: contentScripts +slug: Mozilla/Add-ons/WebExtensions/API/contentScripts +tags: + - API + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/contentScripts +--- +<div>{{AddonSidebar}}</div> + +<p>使用此 API 以注册内容脚本。“注册内容脚本”意味着浏览器会将给定的内容脚本插入到每个与给定的 URL 模式相匹配的页面中。</p> + +<p>此 API 与 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code> 的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">"content_scripts"</a></code> 键非常相似，但 <code>"content_scripts"</code> 键所能注册的内容脚本是固定的，自拓展安装后便不可更改。但<span class="seoSummary">通过 <code>contentScripts</code> API，拓展可以在运行时动态地注册或取消注册脚本。</span></p> + +<p>To use the API, call {{WebExtAPIRef("contentScripts.register()")}} passing in an object defining the scripts to register, the URL patterns, and other options. This returns a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that is resolved with a {{WebExtAPIRef("contentScripts.RegisteredContentScript")}} object.</p> + +<p>The <code>RegisteredContentScript</code> object represents the scripts that were registered in the <code>register()</code> call. It defines an <code>unregister()</code> method that you can use to unregister the content scripts. Content scripts are also unregistered automatically when the page that created them is destroyed. For example, if they are registered from the background page they will be unregistered automatically when the background page is destroyed, and if they are registered from a sidebar or a popup, they will be unregistered automatically when the sidebar or popup is closed.</p> + +<p>没有与 <code>contentScripts</code> API 相关联的权限，但是拓展必须拥有与其试图通过 <code>register()</code> 注册的脚本的匹配模式相对应的<a href="/zh-CN/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">主机权限</a>，才能实现注入。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("contentScripts.RegisteredContentScript")}}</dt> + <dd> + <p>{{WebExtAPIRef("contentScripts.register()")}} 函数会返回一个持有此类型的对象。它表示被通过调用此函数注册的内容脚本，可被用于取消注册对应的内容脚本。</p> + </dd> +</dl> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("contentScripts.register()")}}</dt> + <dd>注册给定的内容脚本。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.contentScripts", 10, 1)}}</p> + +<p>{{WebExtExamples("h2")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/contextmenus/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/contextmenus/index.html new file mode 100644 index 0000000000..ffcb6ce7b7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/contextmenus/index.html @@ -0,0 +1,191 @@ +--- +title: contextMenus +slug: Mozilla/Add-ons/WebExtensions/API/contextMenus +tags: + - API + - WebExtensions + - contextMenus +translation_of: Mozilla/Add-ons/WebExtensions/API/menus +--- +<div>{{AddonSidebar}}</div> + +<div>在浏览器菜单中添加条目。</div> + +<div></div> + +<div>此API基于Chrome的“contextMenus”API构建，该API可让Chrome扩展程序将项目添加到浏览器的上下文菜单中。 <code>browser.menus</code> API为Chrome的API添加了一些功能，特别是可以将项目添加到浏览器的“工具”菜单以及上下文菜单中。</div> + +<div></div> + +<div>在Firefox 55之前，这个API最初也被命名为<code>contextMenus</code>，并且这个名字被保留为别名，所以你可以使用<code>contextMenus</code>编写在Firefox和其他浏览器中工作的代码。</div> + +<div></div> + +<div>你需要拥有“menus”（或别名" contextMenus "）权限来使用此API。</div> + +<h2 id="创建菜单项">创建菜单项</h2> + +<p>使用 {{WebExtAPIRef("menus.create()")}}方法创建一个菜单项。你需要传递一个包含条目选项的对象，它包括条目的id，类型，和需要显示出来的文本值。</p> + +<p>绑定一个监听器到{{WebExtAPIRef("contextMenus.onClicked")}}事件来监听你菜单项目的点击事件。此监听器会传递一个{{WebExtAPIRef("contextMenus.OnClickData")}}，它包含该事件的详细信息。</p> + +<p>你可以根据在调用<code>create()</code>时所传递的参数中使用不同的<code>type</code>值来创建四种不同类型的菜单：</p> + +<ul> + <li>"normal"：只显示为一个标签的菜单项</li> + <li>"checkbox"：一个表示二进制状态的菜单项。 它在菜单项旁边显示一个复选标记。 点击该菜单项切换复选标记。监听器会被传递两个额外的属性：“checked”，指示当前是否被选中，以及“wasChecked”，指示在此点击事件发生前是否被选中。</li> + <li>"radio"：表示一组选项之一的上下文菜单项。 类似于复选框，它也在菜单项旁边显示一个复选标记，监听它的监听器也会被传递“checked”和“wasChecked”。 但是，如果您创建多个单选项，则这些项目将作为一组单选：组内只能选择一项，点击菜单项来选中它。</li> + <li>"separator"：用于分割菜单的分割线。</li> +</ul> + +<p>如果您创建了多个上下文菜单项目或多个工具菜单项目，则这些项目将被放置在子菜单中。 子菜单的父项将标有扩展名。 例如，下面是一个名为“Menu Demo”的扩展，添加了两个上下文菜单项：</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15431/menus-1.png" style="display: block; height: 501px; margin-left: auto; margin-right: auto; width: 700px;"></p> + +<h2 id="图标">图标</h2> + +<p>如果你使用 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/icons">"icons" manifest key</a> 为你的扩展指定一个图标，你的菜单项的旁边就会显示一个指定的图标。浏览器会尝试在普通分辨率下使用16 x 16像素的图标，在高分辨率下使用32 x 32像素的图标：</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15433/menus-2.png" style="display: block; height: 409px; margin-left: auto; margin-right: auto; width: 500px;"> 你可以通过调用 {{WebExtAPIRef("menus.create()")}} 时指定icons选项来给子菜单项设置图标。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15435/menus-3.png" style="display: block; height: 396px; margin-left: auto; margin-right: auto; width: 500px;"></p> + +<h2 id="例子">例子</h2> + +<p>下面是一个包含四个项目的菜单，他们分别是：一个普通选项，两个周围有分割线的单选，和一个复选框。单选框使用了自定义图标。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15437/menus-4.png" style="display: block; height: 790px; margin-left: auto; margin-right: auto; width: 500px;"></p> + +<p>你可以使用以下代码创建一个这样的子菜单：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"remove-me"</span><span class="punctuation token">,</span> + title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemRemoveMe"</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"separator-1"</span><span class="punctuation token">,</span> + type<span class="punctuation token">:</span> <span class="string token">"separator"</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"greenify"</span><span class="punctuation token">,</span> + type<span class="punctuation token">:</span> <span class="string token">"radio"</span><span class="punctuation token">,</span> + title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemGreenify"</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + checked<span class="punctuation token">:</span> <span class="keyword token">true</span><span class="punctuation token">,</span> + icons<span class="punctuation token">:</span> <span class="punctuation token">{</span> + <span class="string token">"16"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-green-16.png"</span><span class="punctuation token">,</span> + <span class="string token">"32"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-green-32.png"</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"bluify"</span><span class="punctuation token">,</span> + type<span class="punctuation token">:</span> <span class="string token">"radio"</span><span class="punctuation token">,</span> + title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemBluify"</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + checked<span class="punctuation token">:</span> <span class="keyword token">false</span><span class="punctuation token">,</span> + icons<span class="punctuation token">:</span> <span class="punctuation token">{</span> + <span class="string token">"16"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-blue-16.png"</span><span class="punctuation token">,</span> + <span class="string token">"32"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-blue-32.png"</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"separator-2"</span><span class="punctuation token">,</span> + type<span class="punctuation token">:</span> <span class="string token">"separator"</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="keyword token">var</span> checkedState <span class="operator token">=</span> <span class="keyword token">true</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + id<span class="punctuation token">:</span> <span class="string token">"check-uncheck"</span><span class="punctuation token">,</span> + type<span class="punctuation token">:</span> <span class="string token">"checkbox"</span><span class="punctuation token">,</span> + title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemUncheckMe"</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + checked<span class="punctuation token">:</span> checkedState +<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("contextMenus.ContextType")}}</dt> + <dd>菜单里可以出现的不同内容。可能的值有："all", "audio", "browser_action", "editable", "frame", "image", "link", "page", "page_action", "password", "selection", "tab", "video".</dd> + <dt>{{WebExtAPIRef("contextMenus.ItemType")}}</dt> + <dd>菜单项的类别有: "normal", "checkbox", "radio", "separator".</dd> + <dt>{{WebExtAPIRef("contextMenus.OnClickData")}}</dt> + <dd>当菜单项被点击时发送的信息。</dd> +</dl> + +<h2 id="属性">属性</h2> + +<dl> + <dt>{{WebExtAPIRef("contextMenus.ACTION_MENU_TOP_LEVEL_LIMIT")}}</dt> + <dd>可以被添加进上下文菜单项的顶级扩展项的最大值，其ContextType可以是"browser_action" 或者 "page_action".</dd> +</dl> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("contextMenus.create()")}}</dt> + <dd>创建一个新的上下文菜单项目。</dd> + <dt>{{WebExtAPIRef("contextMenus.update()")}}</dt> + <dd>更新一个已经创建了的上下文菜单项目。</dd> + <dt>{{WebExtAPIRef("contextMenus.remove()")}}</dt> + <dd>删除一个上下文菜单项目。</dd> + <dt>{{WebExtAPIRef("contextMenus.removeAll()")}}</dt> + <dd>移除该插件创建的所有上下文菜单项目。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("contextMenus.onClicked")}}</dt> + <dd>当一个上下文菜单项被点击时触发。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{ Compat("webextensions.api.menus", 1, "true") }}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>致谢</strong> + +<p>此API基于Chromium的 <a href="https://developer.chrome.com/extensions/contextMenus"><code>chrome.contextMenus</code></a> API. 此文档来自于Chromium代码中的<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/context_menus.json"><code>context_menus.json</code></a>。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/cookie/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/cookie/index.html new file mode 100644 index 0000000000..1a5c4dfdd4 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/cookie/index.html @@ -0,0 +1,121 @@ +--- +title: cookies.Cookie +slug: Mozilla/Add-ons/WebExtensions/API/cookies/Cookie +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies/Cookie +--- +<div>{{AddonSidebar()}}</div> + +<p>The <code>Cookie</code> type of the {{WebExtAPIRef("cookies")}} API represents information about an HTTP cookie.</p> + +<h2 id="类型">类型</h2> + +<p>这玩意是一个 Object，可以包含以下的属性：</p> + +<dl class="reference-values"> + <dt><code>domain</code></dt> + <dd>储存这个 cookie 对应网站的字符串 (例如 "www.tengxun.com")。</dd> + <dt><code>expirationDate</code>{{optional_inline}}</dt> + <dd>A <code>number</code> representing the expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.</dd> + <dt><code>firstPartyDomain</code></dt> + <dd>A <code>string</code> representing the first-party domain associated with the cookie. This will be an empty string if the cookie was set while first-party isolation was off. See <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/cookies#First-party_isolation">First-party isolation</a>.</dd> + <dt><code>hostOnly</code></dt> + <dd>A <code>boolean</code>, <code>true</code> if the cookie is a host-only cookie (i.e. the request's host must exactly match the domain of the cookie), or <code>false</code> otherwise.</dd> + <dt><code>httpOnly</code></dt> + <dd>A <code>boolean</code>, <code>true</code> if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts), or <code>false</code> otherwise.</dd> + <dt><code>name</code></dt> + <dd>A <code>string</code> representing the name of the cookie.</dd> + <dt><code>path</code></dt> + <dd>A <code>string</code> representing the path of the cookie.</dd> + <dt><code>secure</code></dt> + <dd>A <code>boolean</code>, <code>true</code> if the cookie is marked as secure (i.e. its scope is limited to secure channels, typically HTTPS), or <code>false</code> otherwise.</dd> + <dt><code>session</code></dt> + <dd>A <code>boolean</code>, <code>true</code> if the cookie is a session cookie, or <code>false</code> if it is a persistent cookie with an expiration date.</dd> + <dt><code>sameSite</code></dt> + <dd>A {{WebExtAPIRef("cookies.SameSiteStatus")}} value that indicates the SameSite state of the cookie.</dd> + <dt><code>storeId</code></dt> + <dd>A <code>string</code> representing the ID of the cookie store containing this cookie, as provided by {{WebExtAPIRef("cookies.getAllCookieStores()")}}.</dd> + <dt><code>value</code></dt> + <dd>代表 cookie 的值的一个字符串。</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.cookies.Cookie")}}</p> + +<h2 id="举例">举例</h2> + +<p>Cookies API中的大多数方法都将 <code>Cookie</code> 对象用作输入参数或用作返回值的一部分。例如调用 {{WebExtAPIRef("cookies.getAll()")}} 将会返回一个 <code>Cookie</code> 对象的数组。</p> + +<p>在下面的例子中我们将会获取所有的 cookie ，然后 <code>console.log()</code> 出这些 <code>Cookie</code> 对象所对应的值。</p> + +<pre class="brush: js notranslate">function logCookies(cookies) { + for (cookie of cookies) { + console.log(`Domain: ${cookie.domain}`); + console.log(`Name: ${cookie.name}`); + console.log(`Value: ${cookie.value}`); + console.log(`Persistent: ${!cookie.session}`); + } +} + +var gettingAll = browser.cookies.getAll({}); +gettingAll.then(logCookies);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>声明</strong> + +<p>这 API 是基于 Chromium 的 <a href="https://developer.chrome.com/extensions/cookies#type-Cookie"><code>chrome.cookies</code></a> API 的。 这个文档来自于 Chromium code 中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json"><code>cookies.json</code></a> 。</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> + +<div id="simple-translate"> +<div> +<div class="simple-translate-button isShow" style="height: 22px; width: 22px; top: 2528px; left: 464px;"></div> + +<div class="simple-translate-panel " style="width: 300px; height: 200px; top: 0px; left: 0px; font-size: 16px; background-color: rgb(17, 17, 17);"> +<div class="simple-translate-result-wrapper" style="overflow: hidden;"> +<div class="simple-translate-move"></div> + +<div class="simple-translate-result-contents"> +<p class="simple-translate-result" style="color: rgb(234, 234, 234);"></p> + +<p class="simple-translate-candidate" style="color: rgb(195, 195, 195);"></p> +</div> +</div> +</div> +</div> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/index.html new file mode 100644 index 0000000000..4011b4fe56 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/cookies/index.html @@ -0,0 +1,151 @@ +--- +title: cookies +slug: Mozilla/Add-ons/WebExtensions/API/cookies +tags: + - API + - Add-ons + - Cookies + - Extensions + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies +--- +<div>{{AddonSidebar}}</div> + +<p>使用 WebExtensions 获取或设置 cookies, 并且在修改时能够获得通知。</p> + +<p>你需要在 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 文件中开启“cookies”<a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 权限</a>，并且需要对应站点的 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">主机权限</a> 才能设置指定站点的cookie。详细信息查看 <a href="/en-US/Add-ons/WebExtensions/API/cookies#Permissions">cookie 权限</a>.</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.Cookie")}}</dt> + <dd>代表一个HTTP cookie的信息。</dd> + <dt>{{WebExtAPIRef("cookies.CookieStore")}}</dt> + <dd>代表一个保存在浏览器中的 cookie。</dd> + <dt>{{WebExtAPIRef("cookies.OnChangedCause")}}</dt> + <dd>代表 cookie 改变的原因。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.get()")}}</dt> + <dd>返回一个单独的 cookie 的信息。</dd> + <dt>{{WebExtAPIRef("cookies.getAll()")}}</dt> + <dd>返回所有符合筛选条件的 cookies。</dd> + <dt>{{WebExtAPIRef("cookies.set()")}}</dt> + <dd>根据给定cookie数据设置一个cookie；如果同样的cookie存在讲会覆盖。</dd> + <dt>{{WebExtAPIRef("cookies.remove()")}}</dt> + <dd>根据名字删除cookie。</dd> + <dt>{{WebExtAPIRef("cookies.getAllCookieStores()")}}</dt> + <dd>列出所有保存的cookie。</dd> +</dl> + +<h2 id="事件句柄">事件句柄</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.onChanged")}}</dt> + <dd>当设置或删除cookie时触发。</dd> +</dl> + +<h2 id="权限">权限</h2> + +<p>为了使用这个API，插件必须在它的manifest中指定"cookies" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 权限</a>，和它想要使用cookie的任何网站的 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host 权限</a> 。插件将能读取或写入host权限中所匹配的URL可以读取或写入的任何cookie。例如：</p> + +<dl> + <dt><code>http://*.example.com/</code></dt> + <dd> + <p>拥有这个host权限的插件将可以：</p> + + <ul> + <li>读取一个<code>www.example.com</code>任意路径下的不安全cookie。</li> + <li>写入一个<code>www.example.com</code>任意路径下的不安全cookie。</li> + </ul> + + <p><em>它不能：</em></p> + + <ul> + <li>读取<code>www.example.com</code>的安全cookie。</li> + </ul> + </dd> + <dt><code>http://www.example.com/</code></dt> + <dd> + <p>拥有这个host权限的插件将可以：</p> + + <ul> + <li>读取 <code>www.example.com</code>任意路径下的不安全cookie。</li> + <li>读取 <code>.example.com</code> 任意路径下的不安全cookie。</li> + <li>写入 <code>www.example.com</code> 任意路径下的安全和不安全cookie。</li> + <li>写入 <code>.example.com</code> 任意路径下的安全和不安全cookie。</li> + </ul> + + <p>它不能：</p> + + <ul> + <li>读取或写入 <code>foo.example.com</code> 的cookie。</li> + <li>读取或写入 <code>foo.www.example.com</code> 的cookie。</li> + </ul> + </dd> + <dt><code>*://*.example.com/</code></dt> + <dd> + <p>拥有这个host权限的插件将可以：</p> + + <ul> + <li>读取或写入 <code>www.example.com</code> 任意路径下安全的和不安全的cookie。</li> + </ul> + </dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.cookies")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<h3 id="Edge_不兼容">Edge 不兼容</h3> + +<p>在 Edge 中不支持 Promises，使用 callbacks 代替。</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>这个API 基于 Chromium 的 <a href="https://developer.chrome.com/extensions/cookies"><code>chrome.cookies</code></a> API. 这篇文档来源于Chromium 代码的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json"><code>cookies.json</code></a> 。</p> + +<p>Microsoft Edge 兼容性数据由 Microsoft Corporation 提供，并包含在 Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/devtools.inspectedwindow/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/devtools.inspectedwindow/index.html new file mode 100644 index 0000000000..d59f29ffde --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/devtools.inspectedwindow/index.html @@ -0,0 +1,72 @@ +--- +title: devtools.inspectedWindow +slug: Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow +translation_of: Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>This page describes the WebExtensions devtools APIs as they exist in Firefox 54. Although the APIs are based on the <a href="https://developer.chrome.com/extensions/devtools">Chrome devtools APIs</a>, there are still many features that are not yet implemented in Firefox, and therefore are not documented here. To see which features are currently missing please see <a href="/en-US/Add-ons/WebExtensions/Using_the_devtools_APIs#Limitations_of_the_devtools_APIs">Limitations of the devtools APIs</a>.</p> +</div> + +<p>The <code>devtools.inspectedWindow</code> API lets a devtools extension interact with the window that the developer tools are attached to.</p> + +<p>Like all the <code>devtools</code> APIs, this API is only available to code running in the document defined in the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a> manifest.json key, or in other devtools documents created by the extension (such as the document hosted by a panel the extension created). See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools</a> for more.</p> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.inspectedWindow/tabId">devtools.inspectedWindow.tabId</a></code></dt> + <dd>The ID of the window that the developer tools are attached to.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.inspectedWindow/eval">devtools.inspectedWindow.eval()</a></code></dt> + <dd>Evaluate some JavaScript in the target window.</dd> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.inspectedWindow/reload">devtools.inspectedWindow.reload()</a></code></dt> + <dd>Reload the target window's document.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.devtools.inspectedWindow")}}{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/devtools_inspectedWindow"><code>chrome.devtools.inspectedWindow</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/download/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/download/index.html new file mode 100644 index 0000000000..c7b6216ee8 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/download/index.html @@ -0,0 +1,144 @@ +--- +title: downloads.download() +slug: Mozilla/Add-ons/WebExtensions/API/downloads/download +tags: + - API + - Add-ons + - Extensions + - Method + - WebExtensions + - download + - downloads +translation_of: Mozilla/Add-ons/WebExtensions/API/downloads/download +--- +<div>{{AddonSidebar()}}</div> + +<p>{{WebExtAPIRef("downloads")}} API 的 <strong><code>download()</code></strong> 函数根据给出的URL和其他首选项下载一个文件。</p> + +<ul> + <li>如果指定的 <code>url</code> 使用HTTP或者HTTPS协议, 那么下载请求将会包含当前为该域名所设置的所有cookie。</li> + <li>如果<code>filename</code> 和 <code>saveAs</code> 都已经指定，那么将会弹出“保存为” 对话框，并且默认名称显示为<code>filename</code>.</li> +</ul> + +<p>这是一个异步函数，其返回值为 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var downloading = browser.downloads.download( + options // object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>options</code></dt> + <dd>一个 <code>object</code> ，用来指定你想要下载的文件和其他想要在下载时设置的首选项。可以包含以下属性：</dd> + <dd> + <dl class="reference-values"> + <dt><code>allowHttpErrors</code>{{optional_inline}}</dt> + <dd>一个 <code>boolean</code>，启用后即使遇到HTTP错误仍然继续下载。 例如，可以使用该标志下载服务错误页面。默认值为<code>false</code>. 当设置为以下值时: + <ul> + <li><code>false</code>,遇到HTTP错误时下载会被取消。</li> + <li><code>true</code>, 即使遇到HTTP错误也会继续下载，并且不会弹出HTTP服务错误报告。但是，如果下载失败的原因是文件相关，网络相关，用户相关，或者说其他错误，仍然会报错。<span style="display: none;"> </span></li> + </ul> + </dd> + <dt><code>body</code>{{optional_inline}}</dt> + <dd>一个 <code>string</code>，代表请求的内容。</dd> + <dt><code>conflictAction</code>{{optional_inline}}</dt> + <dd>一个字符串，表示如果存在命名冲突时你希望进行的操作，字符串内容所代表的类型由 {{WebExtAPIRef('downloads.FilenameConflictAction')}} 定义(未指定时默认为 "uniquify" )。</dd> + <dt><code>filename</code>{{optional_inline}}</dt> + <dd>一个 <code>string</code> ，表示相对默认保存位置的文件路径——这里提供你希望文件保存的位置，和你想要使用的文件名。绝对路径，空路径，以及包含反向引用的路径 (<code>../</code>) 会导致错误产生。 如果省略，该值将默认为已经提供给下载文件的文件名，并且直接保存到下载文件夹中。</dd> + <dt><code>headers</code>{{optional_inline}}</dt> + <dd>如果URL使用HTTP或者HTTPS协议, 保存在 <code>array</code> 中的一系列 <code>objects</code> 表示与请求一起发送的额外HTTP请求头。每一个请求头表示为字典对象，包含有关键字 <code>name</code> 还有 <code>value</code>或<code>binaryValue</code>中的一个。 无法指定 <code>XMLHttpRequest</code>和 <code>fetch</code>禁止的请求头，但是 Firefox 70 之后允许使用<code>Referer</code>请求头。尝试使用被禁止的请求头会产生一个错误。</dd> + <dt><code>incognito</code>{{optional_inline}}</dt> + <dd>一个 <code>boolean</code>：如果被设置为 true，那么这次下载会建立一个隐私浏览会话。 这意味着它只会出现在当前打开的任意隐私窗口的下载管理器。</dd> + <dt><code>method</code>{{optional_inline}}</dt> + <dd>一个 <code>string</code>，表示<code>url</code>使用HTTP[S] 协议时使用的HTTP方法。其值可能是 "GET" 或 "POST"。</dd> + <dt><code>saveAs</code>{{optional_inline}}</dt> + <dd> + <p>一个<code>boolean</code> 指定是(<code>true</code>)否(<code>false</code>)提供一个文件选择对话框允许用户选择文件名。.</p> + + <p>如果该选项省略, 浏览器会根据用户对于该行为的偏好设置决定是否提供一个文件选择对话框 (在火狐这项设置标签在about:preferences里为"每次都问您要存到哪" ，或者about:config里 <code>browser.download.useDownloadDir</code> )。</p> + + <div class="note"> + <p><strong>Note</strong>: 如果 <code>saveAs</code> 被设置为 <code>true</code>，Firefox for Android 将会引发一个错误。 当 <code>saveAs</code> 为 <code>false</code> 或空时这个参数会被忽略.</p> + </div> + </dd> + <dt><code>url</code></dt> + <dd>一个 <code>string</code>，表示需要下载的链接地址。</dd> + </dl> + </dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>. 如果成功开始下载，promise会被新创建的{{WebExtAPIRef("downloads.DownloadItem")}} 的 <code>id</code> 填充。否则 promise 会被拒绝并产生一条{{WebExtAPIRef("downloads.InterruptReason")}}错误信息.</p> + +<p>如果你使用 <a href="/en-US/docs/Web/API/URL/createObjectURL">URL.createObjectURL()</a> 下载由 JavaScript 创建的数据并且之后想要(使用 <a href="/en-US/docs/Web/API/URL/revokeObjectURL">revokeObjectURL</a>)撤销对象链接(并且强烈推荐这么做)，你必须在下载完成后再这么做。监听 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/downloads/onChanged">downloads.onChanged</a> 事件来判断是否下载完成。</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.downloads.download")}}</p> + +<h2 id="例子">例子</h2> + +<p>下面这段代码尝试下载一个example文件，同时指定文件名和保存位置，还有 <code>uniquify</code> <code>conflictAction</code> 选项。</p> + +<pre class="brush: js">function onStartedDownload(id) { + console.log(`Started downloading: ${id}`); +} + +function onFailed(error) { + console.log(`Download failed: ${error}`); +} + +var downloadUrl = "https://example.org/image.png"; + +var downloading = browser.downloads.download({ + url : downloadUrl, + filename : 'my-image-again.png', + conflictAction : 'uniquify' +}); + +downloading.then(onStartedDownload, onFailed);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>这个 API 基于 Chromium的 <a href="https://developer.chrome.com/extensions/downloads#method-download"><code>chrome.downloads</code></a> API.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.html new file mode 100644 index 0000000000..ce523d15af --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.html @@ -0,0 +1,101 @@ +--- +title: downloads.DownloadItem +slug: Mozilla/Add-ons/WebExtensions/API/downloads/DownloadItem +translation_of: Mozilla/Add-ons/WebExtensions/API/downloads/DownloadItem +--- +<div>{{AddonSidebar()}}</div> + +<p>{{WebExtAPIRef("downloads")}} API 的 <code>DownloadItem</code> 类代表了一个被下载的文件。</p> + +<h2 id="Type">Type</h2> + +<p>这个类型的值是对象，包含了以下属性：</p> + +<dl class="reference-values"> + <dt><code>byExtensionId</code>{{optional_inline}}</dt> + <dd>一个代表了触发此下载的扩展的 ID 的 <code>string</code> （如果是被扩展触发的话）。一旦设置，不会改变。如果下载不是由扩展触发的，则为 undefined。</dd> + <dt><code>byExtensionName</code>{{optional_inline}}</dt> + <dd>一个代表了触发此下载的扩展的名字的 <code>string</code> （如果是被扩展触发的话）。如果用户改变了扩展的语言环境，则这个属性的值也可能变化。如果下载不是由扩展触发的，则为 undefined。</dd> + <dt><code>bytesReceived</code></dt> + <dd>一个代表了在下载过程中从主机接收到的字节数的 <code>number</code> ；不考虑文件压缩。</dd> + <dt><code>canResume</code></dt> + <dd>一个标识当前中断（例如暂停）的下载是否可以从当前位置恢复的 <code>boolean</code>。</dd> + <dt><code>danger</code></dt> + <dd>一个标识这个下载是否通过一个不安全的或已知的可疑的站点。可能被设置为 {{WebExtAPIRef('downloads.DangerType')}} 类型。</dd> + <dt><code>endTime</code>{{optional_inline}}</dt> + <dd>A <code>string</code> (in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format) representing the number of milliseconds between the UNIX epoch and when this download ended. This is undefined if the download has not yet finished.</dd> + <dt><code>error</code>{{optional_inline}}</dt> + <dd>A string indicating why a download was interrupted. Possible values are defined in the {{WebExtAPIRef('downloads.InterruptReason')}} type. This is undefined if an error has not occurred.</dd> + <dt><code>estimatedEndTime</code>{{optional_inline}}</dt> + <dd>A <code>string</code> (in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format) representing the estimated number of milliseconds between the UNIX epoch and when this download is estimated to be completed. This is undefined if it is not known (in particular, it is undefined in the <code>DownloadItem</code> that's passed into {{WebExtAPIRef("downloads.onCreated")}}).</dd> + <dt><code>exists</code></dt> + <dd>A <code>boolean</code> indicating whether a downloaded file still exists (<code>true</code>) or not (<code>false</code>). This information might be out-of-date, as browsers do not automatically watch for file removal — to check whether a file exists, call the {{WebExtAPIRef('downloads.search()')}} method, filtering for the file in question.</dd> + <dt><code>filename</code></dt> + <dd>A <code>string</code> representing the file's absolute local path.</dd> + <dt><code>fileSize</code></dt> + <dd>A <code>number</code> indicating the total number of bytes in the whole file, after decompression. A value of -1 here means that the total file size is unknown.</dd> + <dt><code>id</code></dt> + <dd>An <code>integer</code> representing a unique identifier for the downloaded file that is persistent across browser sessions.</dd> + <dt><code>incognito</code></dt> + <dd>A <code>boolean</code> that indicates whether the download is recorded in the browser's history (<code>false</code>), or not (<code>true</code>).</dd> + <dt><code>mime</code></dt> + <dd>A <code>string</code> representing the downloaded file's MIME type.</dd> + <dt><code>paused</code></dt> + <dd>A <code>boolean</code> indicating whether the download is paused, i.e. if the download has stopped reading data from the host but has kept the connection open. If so, the value is <code>true</code>, <code>false</code> if not.</dd> + <dt><code>referrer</code></dt> + <dd>A <code>string</code> representing the downloaded file's referrer.</dd> + <dt><code>startTime</code></dt> + <dd>A <code>string</code> (in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format) representing the number of milliseconds between the UNIX epoch and when this download began.</dd> + <dt><code>state</code></dt> + <dd>A <code>string</code> Indicating whether the download is progressing, interrupted, or complete. Possible values are defined in the {{WebExtAPIRef('downloads.State')}} type.</dd> + <dt><code>totalBytes</code></dt> + <dd>A <code>number</code> indicating the total number of bytes in the file being downloaded. This does not take file compression into consideration. A value of -1 here means that the total number of bytes is unknown.</dd> + <dt><code>url</code></dt> + <dd>A <code>string</code> representing the absolute URL from which the file was downloaded.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.downloads.DownloadItem")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/downloads#type-DownloadItem"><code>chrome.downloads</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/index.html new file mode 100644 index 0000000000..a2074471b7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/downloads/index.html @@ -0,0 +1,134 @@ +--- +title: downloads +slug: Mozilla/Add-ons/WebExtensions/API/downloads +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - downloads +translation_of: Mozilla/Add-ons/WebExtensions/API/downloads +--- +<div>{{AddonSidebar}}</div> + +<div>启用与浏览器的下载管理器交互的扩展。你可以使用这个 API 模块来下载文件、取消、暂停、恢复下载和在文件管理器中显示下载的文件。</div> + +<p>为使用此 API，你需要在你的 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 文件中声明 "downloads" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 权限</a>。</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.FilenameConflictAction")}}</dt> + <dd>定义当一个下载的文件与现存的文件命名冲突时要做什么。</dd> + <dt>{{WebExtAPIRef("downloads.InterruptReason")}}</dt> + <dd>定义一系列中断下载的可能理由。</dd> + <dt>{{WebExtAPIRef("downloads.DangerType")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">定义一组与可下载文件相关的潜在危险的常见警告。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.State")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">定义当前下载可能处于的不同状态。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.DownloadItem")}}</dt> + <dd>代表下载的文件。</dd> + <dt>{{WebExtAPIRef("downloads.StringDelta")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">表示两个字符串之间的差异。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.DoubleDelta")}}</dt> + <dd>代表两个双精度浮点数之间的差异。</dd> + <dt>{{WebExtAPIRef("downloads.BooleanDelta")}}</dt> + <dd>代表两个布尔数之间的差异。</dd> + <dt>{{WebExtAPIRef("downloads.DownloadTime")}}</dt> + <dd>代表一个下载将会花费的时间。</dd> + <dt>{{WebExtAPIRef("downloads.DownloadQuery")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">定义一组参数，可用于在下载管理器中搜索一组特定的下载。</span></span></dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.download()")}}</dt> + <dd>下载一个文件，给出它的 URL 和其他可选的参数。</dd> + <dt>{{WebExtAPIRef("downloads.search()")}}</dt> + <dd>查询 {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} 是否在浏览器的下载管理器中可用，返回匹配指定的搜索标准的条目。</dd> + <dt>{{WebExtAPIRef("downloads.pause()")}}</dt> + <dd>暂停一个下载。</dd> + <dt>{{WebExtAPIRef("downloads.resume()")}}</dt> + <dd>恢复一个暂停的下载。</dd> + <dt>{{WebExtAPIRef("downloads.cancel()")}}</dt> + <dd>取消一个下载。</dd> + <dt>{{WebExtAPIRef("downloads.getFileIcon()")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">检索指定下载的图标。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.open()")}}</dt> + <dd>用下载的文件相关联的程序打开它。</dd> + <dt>{{WebExtAPIRef("downloads.show()")}}</dt> + <dd>打开当前平台的文件管理应用来在它包含的文件夹中显示下载的文件。</dd> + <dt>{{WebExtAPIRef("downloads.showDefaultFolder()")}}</dt> + <dd>用当前平台的文件管理应用显示默认下载文件夹。</dd> + <dt>{{WebExtAPIRef("downloads.erase()")}}</dt> + <dd>擦除浏览器的下载历史中匹配 {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} 的下载记录，不会在磁盘中删除文件。</dd> + <dt>{{WebExtAPIRef("downloads.removeFile()")}}</dt> + <dd>从磁盘中移除下载的文件，但不从浏览器的下载历史中去除。</dd> + <dt>{{WebExtAPIRef("downloads.acceptDanger()")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">提示用户接受或取消危险的下载。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.drag()")}}</dt> + <dd> <span class="tlid-translation translation" lang="zh-CN"><span title="">将下载的文件拖动到另一个应用程序。</span></span></dd> + <dt>{{WebExtAPIRef("downloads.setShelfEnabled()")}}</dt> + <dd><span class="tlid-translation translation" lang="zh-CN"><span title="">启用或禁用与当前浏览器配置文件关联的每个窗口底部的灰色架子。</span> <span title="">只要至少一个扩展名已禁用该架子，它就会被禁用。</span></span></dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.onCreated")}}</dt> + <dd>当一个下载开始时被 {{WebExtAPIRef("downloads.DownloadItem", "DownloadItem")}} 对象触发。</dd> + <dt>{{WebExtAPIRef("downloads.onErased")}}</dt> + <dd>当一个下载从历史中擦除时被 Fires with the <code>downloadId</code> 触发。</dd> + <dt>{{WebExtAPIRef("downloads.onChanged")}}</dt> + <dd>当任意一个 {{WebExtAPIRef("downloads.DownloadItem", "DownloadItem")}} 的属性期望 <code>bytesReceived</code> 改变时，此事件被这个 `downloadId` 和包含了变化属性的对象触发。</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.downloads")}}</p> + +<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/downloads"><code>chrome.downloads</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/find/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/find/index.html new file mode 100644 index 0000000000..cda583e456 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/find/index.html @@ -0,0 +1,25 @@ +--- +title: find +slug: Mozilla/Add-ons/WebExtensions/API/find +translation_of: Mozilla/Add-ons/WebExtensions/API/find +--- +<div><font><font>{{AddonSidebar}}</font></font></div> + +<p><font><font>在网页中查找文本，并突出显示匹配项。</font></font></p> + +<p><font><font>要使用此API，您需要具有“查找” </font></font><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions"><font><font>权限</font></font></a><font><font>。</font></font></p> + +<h2 id="功能"><font><font>功能</font></font></h2> + +<dl> + <dt>{{WebExtAPIRef("find.find()")}}</dt> + <dd><font><font>在网页中查找文本。</font></font></dd> + <dt>{{WebExtAPIRef("find.highlightResults()")}}</dt> + <dd><font><font>突出显示找到的最后一组匹配项。</font></font></dd> + <dt>{{WebExtAPIRef("find.removeHighlighting()")}}</dt> + <dd><font><font>删除所有突出显示。</font></font></dd> +</dl> + +<h2 id="浏览器兼容性"><font><font>浏览器兼容性</font></font></h2> + +<p>{{Compat("webextensions.api.find", 1, 1)}} {{WebExtExamples("h2")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/history/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/history/index.html new file mode 100644 index 0000000000..7412530cb6 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/history/index.html @@ -0,0 +1,134 @@ +--- +title: history +slug: Mozilla/Add-ons/WebExtensions/API/history +tags: + - API + - Add-ons + - Extensions + - History + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/history +--- +<div>{{AddonSidebar}}</div> + +<p>使用 <code>history</code> API与浏览器历史记录进行交互。</p> + +<div class="note"> +<p>注意：下载也被当做一个 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history/HistoryItem" title="A HistoryItem object provides information about a page in the browser history."><code>HistoryItem</code></a> 对象。因此，<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history/onVisited" title="Fired each time the user visits a page. A history.HistoryItem object is passed to the listener. This event fires before the page has loaded.">history.onVisited</a></code>等事件也会被下载所触发。</p> +</div> + +<p>浏览器历史记录是对用户所访问的页面按时间顺序进行的记录和保存。history API 可以帮你实现以下功能：</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/search">查找浏览器历史记录中出现过的页面</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteUrl">移除浏览器历史记录中的单个页面</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/addUrl">向浏览器历史记录中添加页面</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteAll">移除所有浏览器历史记录中的页面</a></li> +</ul> + +<p>然而，用户可能多次访问单个页面，因此API中有访问集合“visits”的概念。所以，该API还可以做如下使用：</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/getVisits">获取用户对单个页面的所有访问记录的集合</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteRange">移除给定期间内任意页面的访问记录的集合</a></li> +</ul> + +<p>使用该API之前，扩展程序必须在其 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code> 文件中获取history的<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">许可</a>。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("history.TransitionType")}}</dt> + <dd>描述浏览器如何转到特定页面。</dd> + <dt>{{WebExtAPIRef("history.HistoryItem")}}</dt> + <dd> + <p>提供浏览器历史记录中单个特定页面的详细信息。</p> + </dd> + <dt>{{WebExtAPIRef("history.VisitItem")}}</dt> + <dd> + <p>描述对一个页面的单次访问。</p> + </dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("history.search()")}}</dt> + <dd>在浏览器历史记录中查找符合给定条件的<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/History/HistoryItem" title="A HistoryItem object provides information about one result from a history query.">history.HistoryItem</a></code></dd> + <dt>{{WebExtAPIRef("history.getVisits()")}}</dt> + <dd>获取指定页面的访问集信息。</dd> + <dt>{{WebExtAPIRef("history.addUrl()")}}</dt> + <dd>为浏览器历史记录添加一个指定页面的访问。</dd> + <dt>{{WebExtAPIRef("history.deleteUrl()")}}</dt> + <dd>移除浏览器历史记录中所有对指定URL的访问。</dd> + <dt>{{WebExtAPIRef("history.deleteRange()")}}</dt> + <dd>移除指定时间段内对用户指定页面的访问。</dd> + <dt>{{WebExtAPIRef("history.deleteAll()")}}</dt> + <dd>移除浏览器历史记录中的所有访问。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("history.onTitleChanged")}}</dt> + <dd> + <div>当用户访问的页面标题被记录时触发。</div> + </dd> + <dt>{{WebExtAPIRef("history.onVisited")}}</dt> + <dd>每次用户访问页面时会触发，并提供该页面的 {{WebExtAPIRef("history.HistoryItem")}} 数据。</dd> + <dt>{{WebExtAPIRef("history.onVisitRemoved")}}</dt> + <dd> + <p>当一个URL被彻底从浏览器历史记录中移除时触发。</p> + </dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.history")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>致谢</strong> + +<p>该 API 基于Chromium的<a href="https://developer.chrome.com/extensions/history"><code>chrome.history</code></a> API。该文档由Chromium代码中的<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/history.json"><code>history.json</code></a>衍生而来。</p> + +<p>微软 Edge 兼容性数据由微软公司提供并包含在如下证书中—— Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/history/ontitlechanged/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/history/ontitlechanged/index.html new file mode 100644 index 0000000000..bf79b4c6d7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/history/ontitlechanged/index.html @@ -0,0 +1,111 @@ +--- +title: history.onTitleChanged +slug: Mozilla/Add-ons/WebExtensions/API/history/onTitleChanged +tags: + - History +translation_of: Mozilla/Add-ons/WebExtensions/API/history/onTitleChanged +--- +<div>{{AddonSidebar()}}</div> + +<div>当document的标题更改时触发</div> + +<div> </div> + +<div>你可以使用 {{WebExtAPIRef("history.onVisited")}}去进行监听. However, the {{WebExtAPIRef("history.HistoryItem")}} that this event passes to its listener does not include the page title, because the page title is typically not known at the time <code>history.onVisited</code> is sent.</div> + +<div> </div> + +<div>Instead, the stored {{WebExtAPIRef("history.HistoryItem")}} is updated with the page title after the page has loaded, once the title is known. The history.onTitleChanged event is fired at that time. So if you need to know the titles of pages as they are visited, listen for <code>history.onTitleChanged</code>.</div> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">browser.history.onTitleChanged.addListener(listener) +browser.history.onTitleChanged.removeListener(listener) +browser.history.onTitleChanged.hasListener(listener) +</pre> + +<p>Events have three functions:</p> + +<dl> + <dt><code>addListener(listener)</code></dt> + <dd>Adds a listener to this event.</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>Stop listening to this event. The <code>listener</code> argument is the listener to remove.</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>Check whether <code>listener</code> is registered for this event. Returns <code>true</code> if it is listening, <code>false</code> otherwise.</dd> +</dl> + +<h2 id="addListener_syntax">addListener syntax</h2> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>callback</code></dt> + <dd> + <p>Function that will be called when this event occurs. The function will be passed an object with the following properties:</p> + + <dl class="reference-values"> + <dt><code>url</code></dt> + <dd><code>String</code>. URL of the page visited.</dd> + <dt><code>title</code></dt> + <dd><code>String</code>. Title of the page visited.</dd> + </dl> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.history.onTitleChanged")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>Listen for title change events, and log the URL and title of the visited pages.</p> + +<pre class="brush: js">function handleTitleChanged(item) { + console.log(item.title); + console.log(item.url); +} + +browser.history.onTitleChanged.addListener(handleTitleChanged);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/history#event-onVisited"><code>chrome.history</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/history.json"><code>history.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/i18n/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/i18n/index.html new file mode 100644 index 0000000000..73897ac0ea --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/i18n/index.html @@ -0,0 +1,85 @@ +--- +title: i18n +slug: Mozilla/Add-ons/WebExtensions/API/i18n +translation_of: Mozilla/Add-ons/WebExtensions/API/i18n +--- +<div>{{AddonSidebar}}</div> + +<p>国际化扩展的函数。您可以使用这些 api 从与扩展打包在一起的本地化文件中获取本地化字符串，查找浏览器的当前语言，并查找其 <a href="/zh-CN/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">Accept-Language header</a>头的值。</p> + +<p id="See_also">有关对扩展使用 i18n 的详细信息，请参阅:</p> + +<ul> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Internationalization">Internationalization</a>国际化: 使用 WebExtension i18n 系统的指南</li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">Locale-Specific Message reference</a>: 扩展在 <code>messages.json</code>文件中提供特定于语言环境的字符串。 <font>此网页介绍</font><code>messages.json</code></li> +</ul> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.LanguageCode")}}</dt> + <dd>一个<a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10">语言标记</a> 例如 <code>"en-US"</code> 或者 "<code>fr</code>".</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.getAcceptLanguages()")}}</dt> + <dd>得到浏览器 <a href="/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">支持的语言</a> 。这与浏览器使用的区域设置不同。要获得区域设置，请使用{{WebExtAPIRef('i18n.getUILanguage')}}.</dd> + <dt>{{WebExtAPIRef("i18n.getMessage()")}}</dt> + <dd>获取指定消息的本地化字符串。</dd> + <dt>{{WebExtAPIRef("i18n.getUILanguage()")}}</dt> + <dd>获取浏览器的用户界面语言。 这与返回首选的用户语言 {{WebExtAPIRef('i18n.getAcceptLanguages')}} 不同。</dd> + <dt>{{WebExtAPIRef("i18n.detectLanguage()")}}</dt> + <dd>使用 <a href="https://github.com/CLD2Owners/cld2">Compact Language Detector</a>属性检测所提供文本的语言。</dd> +</dl> + +<dl> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.i18n")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<dl> +</dl> + +<div class="note"><strong>Acknowledgements</strong> + +<p>这个 API 是基于 Chromium 的 <a href="https://developer.chrome.com/extensions/i18n"><code>chrome.i18n</code></a> API，这个文档源自 Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/i18n.json"><code>history.json</code></a> 。</p> + +<p>微软 Edge 的兼容性数据由微软公司提供，并在这里收录在《知识共享3.0美国许可证》中。</p> +</div> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/idle/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/idle/index.html new file mode 100644 index 0000000000..a6160bc90d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/idle/index.html @@ -0,0 +1,97 @@ +--- +title: idle +slug: Mozilla/Add-ons/WebExtensions/API/idle +tags: + - API + - Idle + - WebExtensions + - requestIdleCallback + - 性能优化 +translation_of: Mozilla/Add-ons/WebExtensions/API/idle +--- +<div>{{AddonSidebar}}</div> + +<p>找出用户系统何时处于空闲，锁定或活动状态。</p> + +<p>要使用此API，您需要具有“空闲”<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("idle.IdleState")}}</dt> + <dd> + <p>描述设备空闲状态的字符串。</p> + </dd> +</dl> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("idle.queryState()")}}</dt> + <dd>如果系统被锁定则返回“已锁定”，如果用户未在指定的秒数内生成任何输入，则返回“空闲”，否则返回“活动”。</dd> + <dt>{{WebExtAPIRef("idle.setDetectionInterval()")}}</dt> + <dd>设置用于确定系统何时处于 {{WebExtAPIRef("idle.onStateChanged")}} 事件的空闲状态的时间间隔。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("idle.onStateChanged")}}</dt> + <dd>当系统改变状态时触发。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.idle")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>确认</strong> + +<p>此 API基于 Chromium 的 <a href="https://developer.chrome.com/extensions/idle"><code>chrome.idle</code></a> API。本文档源自 Chromium代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/idle.json"><code>idle.json</code></a> 。</p> + +<p>Microsoft Edge 兼容性数据由 Microsoft Corporation提供，并包含在Creative Commons Attribution 3.0 United States License下。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> + +<div></div> + +<h3 id="了解更多">了解更多:</h3> + +<div><a href="https://developer.mozilla.org/zh-CN/docs/Web/API/Window/requestIdleCallback">https://developer.mozilla.org/zh-CN/docs/Web/API/Window/requestIdleCallback </a></div> + +<div></div> + +<div></div> + +<div>...</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..a469192447 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,50 @@ +--- +title: API +slug: Mozilla/Add-ons/WebExtensions/API +tags: + - NeedsTranslation + - TopicStub +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>WebExtension JavaScript API 可以在附加组件的<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">后台脚本</a>和附加组件定义的任何<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/User_interface_components#Browser_actions">浏览器动作</a>或<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/User_interface_components#Page_actions">页面动作</a>中使用。这里的部分API也可以通过附加组件的<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">内容脚本</a>访问（见<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">内容脚本指南列表</a>）。</p> + +<p>要使用更强大的 API，您需要在您的 manifest.json 中<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/manifest.json/permissions">申请权限</a>。</p> + +<p>您可以使用 <code>browser</code> 命名空间访问这些 API。</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">function logTabs(tabs) { + console.log(tabs); +} + +browser.tabs.query({currentWindow: true}, logTabs);</code></pre> +</div> + +<div> +<p>许多 API 为异步，返回一个 <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">function logCookie(c) { + console.log(c); +} + +function logError(e) { + console.error(e); +} + +var setCookie = browser.cookies.set( + {url: "https://developer.mozilla.org/"} +); +setCookie.then(logCookie, logError);</code></pre> +</div> + +<div> +<p>请注意，这不同于 Google Chrome 的扩展系统，它使用 <code>chrome</code> 而非 <code>browser</code> 名字空间，并且对异步函数使用回调而不是 promises。为辅助移植，Firefox 实现的 WebExtensions 支持 <code>chrome</code> 和回调以及 <code>browser</code> 和 promises。Mozilla 也写了一个 polyfill 使使用 <code>browser</code> 和 promises 的代码能不经修改的在 Chrome 中使用：<a class="external external-icon" href="https://github.com/mozilla/webextension-polyfill">https://github.com/mozilla/webextension-polyfill</a>。</p> + +<p>微软 Edge 使用 <code>browser</code> 名字空间，但尚不支持基于 promise 的异步API。目前在 Edge 中，异步 API 必须使用回调。</p> + +<p>并非所有浏览器都支持这里的所有 API：详情见<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">浏览器对 JavaScript API 的支持</a>。</p> +</div> + +<div>{{SubpagesWithSummaries}}</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/contains/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/contains/index.html new file mode 100644 index 0000000000..c701942058 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/permissions/contains/index.html @@ -0,0 +1,94 @@ +--- +title: permissions.contains() +slug: Mozilla/Add-ons/WebExtensions/API/permissions/contains +tags: + - Contains + - permissions.contains() +translation_of: Mozilla/Add-ons/WebExtensions/API/permissions/contains +--- +<div>{{AddonSidebar()}}</div> + +<p>检查扩展名是否具有给定 {{WebExtAPIRef("permissions.Permissions")}} 对象中列出的权限。</p> + +<p>The <code>Permissions</code> argument may contain either an origins property, which is an array of <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permissions</a>, or a <code>permissions</code> property, which is an array of <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permissions</a>, or both.</p> + +<p>This is an asynchronous function that returns a <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>. The promise is fulfilled with true only if all the extension currently has all the given permissions. For host permissions, if the extension's permissions <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">pattern-match</a> the permissions listed in <code>origins</code>, then they are considered to match.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js notranslate">var getContains = browser.permissions.contains( + permissions // Permissions object +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>permissions</code></dt> + <dd>A {{WebExtAPIRef("permissions.Permissions")}} object.</dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with <code>true</code> if the extension already has all the permissions listed in the <code>permissions</code> argument, or <code>false</code> otherwise.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.permissions.contains")}}</p> + +<h2 id="Examples">Examples</h2> + +<pre class="brush: js notranslate">// Extension permissions are: +// "webRequest", "tabs", "*://*.mozilla.org/*" + +var testPermissions1 = { + origins: ["*://mozilla.org/"], + permissions: ["tabs"] +}; + +browser.permissions.contains(testPermissions1).then((result) => { + console.log(result); // true +}); + +var testPermissions2 = { + origins: ["*://mozilla.org/"], + permissions: ["tabs", "alarms"] +}; + +browser.permissions.contains(testPermissions2).then((result) => { + console.log(result); // false, "alarms" doesn't match +}); + +var testPermissions3 = { + origins: ["https://developer.mozilla.org/"], + permissions: ["tabs", "webRequest"] +}; + +browser.permissions.contains(testPermissions3).then((result) => { + console.log(result); // true: "https://developer.mozilla.org/" +}); // matches: "*://*.mozilla.org/*" + +var testPermissions4 = { + origins: ["https://example.org/"] +}; + +browser.permissions.contains(testPermissions4).then((result) => { + console.log(result); // false, "https://example.org/" +}); // does not match + +</pre> + +<p>{{WebExtExamples}}</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> + +<div id="gtx-trans" style="position: absolute; left: 677px; top: 46px;"> +<div class="gtx-trans-icon"></div> +</div> 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> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/proxy/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/proxy/index.html new file mode 100644 index 0000000000..e259cf65fc --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/proxy/index.html @@ -0,0 +1,65 @@ +--- +title: proxy +slug: Mozilla/Add-ons/WebExtensions/API/proxy +translation_of: Mozilla/Add-ons/WebExtensions/API/proxy +--- +<div>{{AddonSidebar}}</div> + +<div></div> + +<div class="blockIndicator warning"> +<p><strong>Warning</strong><br> + 不推荐使用 {{WebExtAPIRef("proxy.register()")}} 或者 {{WebExtAPIRef("proxy.unregister()")}} 方法使用 <a href="/en-US/Add-ons/WebExtensions/API/proxy/register#PAC_file_specification">Proxy Auto-Configuration (PAC) file</a>. 这个 API 将会在 Firefox 68 中废弃并且在 Firefox 71中删除.</p> +</div> + +<p>使用proxy API来代理web请求。你可以使用<code><strong>{{WebExtAPIRef("proxy.onRequest")}}</strong></code>事件监听器来拦截web请求，并且返回一个可以描述是否代理并且怎样代理它们的对象。</p> + +<p>{{WebExtAPIRef("proxy.onRequest")}}的好处在于，用于实现你拦截策略的代码在你的扩展的后台脚本运行，所以，它可以让<code><strong>WebExtension APIs</strong></code>能够完全的访问你的扩展(举例来说，可以访问你扩展的<code>storage</code>和像dns等类似的网络api)</p> + +<p>除了这个api，扩展也能够使用<strong><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserSettings/proxyConfig">browserSettings.proxyConfig</a></code></strong>属性来重新编辑你全局的<code>proxy</code>设置</p> + +<p>Chrome浏览器提供了一个叫做<code><a href="https://developer.chrome.com/extensions/proxy">'proxy'</a>的</code>api扩展，它的功能跟这个api类似，在chrome的api中也可以用来实现一个<code>拦截策略。</code>然而，Chrome 的API的设计跟这个API设计完全不同。因为这个API跟谷歌的<code>proxy</code>的<font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">API完全不同, 这个API只能通过'browser'命名空间访问</span></font></p> + +<p>如果你想用这个API你需要得到'<code>proxy</code>'的<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.并且，如果你想拦截一个请求，你同样也需要当前拦截请求的url的 <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">host permission</a>。</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("proxy.ProxyInfo")}}</dt> + <dd>Describes a proxy.</dd> + <dt>{{WebExtAPIRef("proxy.RequestDetails")}}</dt> + <dd> + <p>Contains information about a web request that the browser is about to make.</p> + </dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("proxy.settings")}}</dt> + <dd>Get and set proxy settings.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("proxy.register()")}} {{Deprecated_Inline}}</dt> + <dd>Registers the given proxy script.</dd> + <dt>{{WebExtAPIRef("proxy.unregister()")}} {{Deprecated_Inline}}</dt> + <dd>Unregisters the proxy script.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("proxy.onError")}}</dt> + <dd>Fired when the system encounters an error running the PAC script or the <code>onRequest</code> listener.</dd> + <dt>{{WebExtAPIRef("proxy.onRequest")}}</dt> + <dd>Fired when a web request is about to be made, giving the extension an opportunity to proxy it.</dd> +</dl> + +<p>{{WebExtExamples("h2")}}</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.proxy")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/connectnative/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/connectnative/index.html new file mode 100644 index 0000000000..d3d4d9a14d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/connectnative/index.html @@ -0,0 +1,114 @@ +--- +title: 连接本地应用程序方法 - runtime.connectNative() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/connectNative +tags: + - 附加组件连接本地应用程序 +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/connectNative +--- +<div>{{AddonSidebar()}}</div> + +<div>该方法能够把附加组件和用户计算机上的一个本地应用程序相连接.</div> + +<div> </div> + +<div>同时我们需要本地应用程序的名称作为参数. 当启动本地应用程序的时候会返回一个{{WebExtAPIRef("runtime.Port")}} 对象给调用者.</div> + +<div> </div> + +<div>之后可以通过该对象的 Port.onMessage() 和 Port.postMessage()方法来和本地应用程序进行信息交互.</div> + +<div> </div> + +<div>本地应用程序会一直运行直到退出, 除非调用了 <code>Port.disconnect()</code>方法, 亦或创建该Port对象的页面被摧毁了. 一旦Port对象断开连接, 浏览器会给该进程几秒的时间以便安全优雅的退出和释放, 之后如果发现该进程没退出的话就直接暴力干掉.</div> + +<div> </div> + +<p>更多信息, 请查看 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">Native messaging</a>.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var port = browser.runtime.connectNative( + application // 这是一个字符串 +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>application</code></dt> + <dd><code>值类型为string</code>. 该参数的值为要连接的本地应用程序的名称. 必须要跟 <a href="/en-US/Add-ons/WebExtensions/Native_messaging#App_manifest">native application's manifest file</a> 中的"name"特性的值一致.</dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>是一个 {{WebExtAPIRef('runtime.Port')}} 对象. 该对象是用来跟本地应用程序进行消息交互的.</p> + +<h2 id="浏览器的兼容性">浏览器的兼容性</h2> + +<p class="hidden">本页中的兼容性表格是通过结构化后的数据生成的. 如果你想提供更多的兼容性数据, 请检出 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 添加修改后再给我们发送一个pull请求.</p> + +<p>{{Compat("webextensions.api.runtime.connectNative")}}</p> + +<h2 id="示例">示例</h2> + +<p>本示例中连接了本地应用程序"ping_pong"并且启动了监听以便接收消息. 当用户单击浏览器上的操作按钮时它会发送一个本地应用程序的消息:</p> + +<pre class="brush: js">/* +启动时, 连接"ping_pong"本地应用程序. +*/ +var port = <code class="language-js">browser</code>.runtime.connectNative("ping_pong"); + +/* +监听(接收)来自"ping_pong"本地应用程序的消息. +*/ +port.onMessage.addListener((response) => { + console.log("Received: " + response); +}); + +/* +当浏览器上的单击操作被触发时, 发送一个消息给本地应用程序. +*/ +<code class="language-js">browser</code>.browserAction.onClicked.addListener(() => { + console.log("Sending: ping"); + port.postMessage("ping"); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>万分感谢</strong> + +<p>该 API 是基于 Chromium 的 <a href="https://developer.chrome.com/extensions/runtime#method-connectNative"><code>chrome.runtime</code></a> API. 本文档采自 Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a>.</p> + +<p>Microsoft Edge 的兼容性数据由微软公司提供, 并被列入以下许可证 Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html new file mode 100644 index 0000000000..77870d7010 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html @@ -0,0 +1,79 @@ +--- +title: 读取主文件信息方法 - runtime.getManifest() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/getManifest +tags: + - 读取主文件信息方法 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/getManifest +--- +<div>{{AddonSidebar()}}</div> + +<div>该方法会获取一个完整的主文件 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json </a>, 并返回一个序列化后的 JSON 对象.</div> + +<div> </div> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">browser.runtime.getManifest() +</pre> + +<h3 id="参数">参数</h3> + +<p>无.</p> + +<h3 id="返回值">返回值</h3> + +<p>是一个能表示主文件所有信息的 JSON 对象.</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.getManifest")}}</p> + +<h2 id="示例">示例</h2> + +<p>取得主文件中的 name 特性的值, 并输出到控制台:</p> + +<pre class="brush: js">var manifest = browser.runtime.getManifest(); +console.log(manifest.name);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#method-getManifest"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/index.html new file mode 100644 index 0000000000..5a1618e9e7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/index.html @@ -0,0 +1,181 @@ +--- +title: runtime +slug: Mozilla/Add-ons/WebExtensions/API/runtime +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - runtime +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime +--- +<div>{{AddonSidebar}}</div> + +<p>该模块提供关于附加组件以及运行环境的信息。</p> + +<p>它提供一组消息通信API，允许你：</p> + +<ul> + <li>在附加组件的不同模块间通信。</li> + <li>和其它的附加组件通信。</li> + <li>和native应用通信。</li> +</ul> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.Port")}}</dt> + <dd>表示两个特定上下文之间的连接的一端，可用于交换消息。</dd> + <dt>{{WebExtAPIRef("runtime.MessageSender")}}</dt> + <dd> + <div class="trans-right"> + <div class="output-wrap small-font"> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output clearfix"><span>包含有关消息或连接请求的发件人的信息。</span></p> + </div> + </div> + </div> + </div> + </dd> + <dt>{{WebExtAPIRef("runtime.PlatformOs")}}</dt> + <dd>标识浏览器的操作系统。</dd> + <dt>{{WebExtAPIRef("runtime.PlatformArch")}}</dt> + <dd>标识浏览器的处理器架构。</dd> + <dt>{{WebExtAPIRef("runtime.PlatformInfo")}}</dt> + <dd>包含有关浏览器正在运行的平台的信息。</dd> + <dt>{{WebExtAPIRef("runtime.RequestUpdateCheckStatus")}}</dt> + <dd>{{WebExtAPIRef("runtime.requestUpdateCheck()")}} 的返回结果。</dd> + <dt>{{WebExtAPIRef("runtime.OnInstalledReason")}}</dt> + <dd>{{WebExtAPIRef("runtime.onInstalled")}} 事件被触发的原因。</dd> + <dt>{{WebExtAPIRef("runtime.OnRestartRequiredReason")}}</dt> + <dd>{{WebExtAPIRef("runtime.onRestartRequired")}} 事件被触发的原因。</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.lastError")}}</dt> + <dd>当异步方法执行时发生了错误，它需要向其调用方报告时，该值会被设置。</dd> + <dt>{{WebExtAPIRef("runtime.id")}}</dt> + <dd>当前扩展的ID。</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.getBackgroundPage()")}}</dt> + <dd>取得当前扩展的后台页的 <a href="https://wiki.developer.mozilla.org/zh-CN/docs/Web/API/Window">Window</a> 对象。</dd> + <dt>{{WebExtAPIRef("runtime.openOptionsPage()")}}</dt> + <dd> + <p>打开你的扩展的 <a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Options_pages">选项页面</a>。</p> + </dd> + <dt>{{WebExtAPIRef("runtime.getManifest()")}}</dt> + <dd>获得完整的 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 声明文件的序列化对象。</dd> + <dt>{{WebExtAPIRef("runtime.getURL()")}}</dt> + <dd>给定某个打包在扩展中的资源的基于 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 相对路径，返回一个完整有效的 URL。</dd> + <dt>{{WebExtAPIRef("runtime.setUninstallURL()")}}</dt> + <dd>指定一个此扩展被卸载后打开的 URL。</dd> + <dt>{{WebExtAPIRef("runtime.reload()")}}</dt> + <dd>重新加载此扩展。</dd> + <dt>{{WebExtAPIRef("runtime.requestUpdateCheck()")}}</dt> + <dd>检查此扩展的更新。</dd> + <dt>{{WebExtAPIRef("runtime.connect()")}}</dt> + <dd>建立一个页面脚本到扩展主进程，或扩展主进程到页面脚本之间的通信连接。</dd> + <dt>{{WebExtAPIRef("runtime.connectNative()")}}</dt> + <dd> + <div>建立一个浏览器扩展与用户电脑上的原生应用的通信连接。</div> + </dd> + <dt>{{WebExtAPIRef("runtime.sendMessage()")}}</dt> + <dd>发送一条消息到此扩展或其他扩展的事件监听器，类似于 {{WebExtAPIRef('runtime.connect')}} 但只能发送一条消息，以及可选的响应处理函数。</dd> + <dt>{{WebExtAPIRef("runtime.sendNativeMessage()")}}</dt> + <dd>从扩展发送一条消息到原生应用。</dd> + <dt>{{WebExtAPIRef("runtime.getPlatformInfo()")}}</dt> + <dd>返回当前所在平台的信息。</dd> + <dt>{{WebExtAPIRef("runtime.getBrowserInfo()")}}</dt> + <dd>返回此扩展所在的浏览器的信息。</dd> + <dt>{{WebExtAPIRef("runtime.getPackageDirectoryEntry()")}}</dt> + <dd>返回此扩展所在目录的 DirectoryEntry。</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.onStartup")}}</dt> + <dd>当一个拥有此扩展的账户第一次启动时触发，注意若处于隐私模式中则不会触发。</dd> + <dt>{{WebExtAPIRef("runtime.onInstalled")}}</dt> + <dd>当扩展第一次安装，扩展更新，浏览器更新后触发。</dd> + <dt>{{WebExtAPIRef("runtime.onSuspend")}}</dt> + <dd>当扩展将被停止前触发，使得扩展可以执行一些清理工作。</dd> + <dt>{{WebExtAPIRef("runtime.onSuspendCanceled")}}</dt> + <dd>在此事件 {{WebExtAPIRef("runtime.onSuspend")}} 后触发，表明扩展最终没有被停止。</dd> + <dt>{{WebExtAPIRef("runtime.onUpdateAvailable")}}</dt> + <dd>当扩展更新可用时触发，注意若扩展运行中，更新不会马上被安装。</dd> + <dt>{{WebExtAPIRef("runtime.onBrowserUpdateAvailable")}}</dt> + <dd>当浏览器更新可用时触发，注意浏览器需要重启才能安装更新。</dd> + <dt>{{WebExtAPIRef("runtime.onConnect")}}</dt> + <dd>与扩展进程或页面脚本（content script）建立通信连接时触发。</dd> + <dt>{{WebExtAPIRef("runtime.onConnectExternal")}}</dt> + <dd>与其他扩展建立通信连接时触发。</dd> + <dt>{{WebExtAPIRef("runtime.onMessage")}}</dt> + <dd>当收到扩展进程或页面脚本（content script）的消息时触发。</dd> + <dt>{{WebExtAPIRef("runtime.onMessageExternal")}}</dt> + <dd>当收到其他扩展的消息时触发，不能在页面脚本（content script）中使用。</dd> + <dt>{{WebExtAPIRef("runtime.onRestartRequired")}}</dt> + <dd>当设备要重启时触发。</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.runtime")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<p>{{Compat("webextensions.api.runtime")}} {{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onconnect/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onconnect/index.html new file mode 100644 index 0000000000..d51cb8abbc --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onconnect/index.html @@ -0,0 +1,228 @@ +--- +title: runtime.onConnect +slug: Mozilla/Add-ons/WebExtensions/API/runtime/onConnect +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/onConnect +--- +<div>{{AddonSidebar()}}</div> + +<p>当使用扩展处理或content script建立连接时触发.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">browser.runtime.onConnect.addListener(listener) +browser.runtime.onConnect.removeListener(listener) +browser.runtime.onConnect.hasListener(listener) +</pre> + +<p>事件有三个方法:</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>为 这个事件添加一个监听器.</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>停止监听这个事件. <code>listener</code> 参数就是要移除的监听器.</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>检查监听器是否已经注册到这个事件上. 如果已经监听，则返回 <code>true</code> 否则返回 <code>false</code>.</dd> +</dl> + +<h2 id="addListener_语法">addListener 语法</h2> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>function</code></dt> + <dd> + <p>A callback function that will be called when this event occurs. The function will be passed the following arguments:</p> + + <dl class="reference-values"> + <dt><code>port</code></dt> + <dd>A {{WebExtAPIRef('runtime.Port')}} object connecting the current script to the other context it is connecting to.</dd> + </dl> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.onConnect")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>This content script:</p> + +<ul> + <li>connects to the background script, and stores the <code>Port</code> in a variable <code>myPort</code></li> + <li>listens for messages on <code>myPort</code>, and logs them</li> + <li>sends messages to the background script, using <code>myPort</code>, when the user clicks the document</li> +</ul> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// content-script.js</span> + +<span class="keyword token">var</span> myPort <span class="operator token">=</span> browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span><span class="function token">connect</span><span class="punctuation token">(</span><span class="punctuation token">{</span>name<span class="punctuation token">:</span><span class="string token">"port-from-cs"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +myPort<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"hello from content script"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +myPort<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span>m<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">"In content script, received message from background script: "</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>m<span class="punctuation token">.</span>greeting<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +document<span class="punctuation token">.</span>body<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">"click"</span><span class="punctuation token">,</span> <span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + myPort<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"they clicked the page!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>The corresponding background script:</p> + +<ul> + <li>listens for connection attempts from the content script</li> + <li>when it receives a connection attempt: + <ul> + <li>stores the port in a variable named <code>portFromCS</code></li> + <li>sends the content script a message using the port</li> + <li>starts listening to messages received on the port, and logs them</li> + </ul> + </li> + <li>sends messages to the content script, using <code>portFromCS</code>, when the user clicks the extension's browser action</li> +</ul> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// background-script.js</span> + +<span class="keyword token">var</span> portFromCS<span class="punctuation token">;</span> + +<span class="keyword token">function</span> <span class="function token">connected</span><span class="punctuation token">(</span>p<span class="punctuation token">)</span> <span class="punctuation token">{</span> + portFromCS <span class="operator token">=</span> p<span class="punctuation token">;</span> + portFromCS<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"hi there content script!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + portFromCS<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span>m<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">"In background script, received message from content script"</span><span class="punctuation token">)</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>m<span class="punctuation token">.</span>greeting<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span>onConnect<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>connected<span class="punctuation token">)</span><span class="punctuation token">;</span> + +browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + portFromCS<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"they clicked the button!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#event-onConnect"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> + +<div id="SL_balloon_obj" style="display: block;"> +<div class="SL_ImTranslatorLogo" id="SL_button" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%; opacity: 1; display: none; left: -8px; top: -25px;"> </div> + +<div id="SL_shadow_translation_result2" style="display: none;"> </div> + +<div id="SL_shadow_translator" style="display: none;"> +<div id="SL_planshet"> +<div id="SL_arrow_up" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;"> </div> + +<div id="SL_Bproviders"> +<div class="SL_BL_LABLE_ON" id="SL_P0" title="Google">G</div> + +<div class="SL_BL_LABLE_ON" id="SL_P1" title="Microsoft">M</div> + +<div class="SL_BL_LABLE_ON" id="SL_P2" title="Translator">T</div> +</div> + +<div id="SL_alert_bbl" style="display: none;"> +<div id="SLHKclose" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;"> </div> + +<div id="SL_alert_cont"> </div> +</div> + +<div id="SL_TB"> +<table id="SL_tables"> + <tbody> + <tr> + <td class="SL_td"><input></td> + <td class="SL_td"><select><option value="auto">检测语言</option><option value="eo">世界语</option><option value="zh-CN">中文简体</option><option value="zh-TW">中文繁体</option><option value="da">丹麦语</option><option value="uk">乌克兰语</option><option value="uz">乌兹别克语</option><option value="ur">乌尔都语</option><option value="hy">亚美尼亚语</option><option value="ig">伊博语</option><option value="ru">俄语</option><option value="bg">保加利亚语</option><option value="si">僧伽罗语</option><option value="hr">克罗地亚语</option><option value="is">冰岛语</option><option value="gl">加利西亚语</option><option value="ca">加泰罗尼亚语</option><option value="hu">匈牙利语</option><option value="zu">南非祖鲁语</option><option value="kn">卡纳达语</option><option value="hi">印地语</option><option value="su">印尼巽他语</option><option value="jw">印尼爪哇语</option><option value="id">印尼语</option><option value="gu">古吉拉特语</option><option value="kk">哈萨克语</option><option value="tr">土耳其语</option><option value="tg">塔吉克语</option><option value="sr">塞尔维亚语</option><option value="st">塞索托语</option><option value="cy">威尔士语</option><option value="bn">孟加拉语</option><option value="ceb">宿务语</option><option value="ne">尼泊尔语</option><option value="eu">巴斯克语</option><option value="af">布尔语(南非荷兰语)</option><option value="iw">希伯来语</option><option value="el">希腊语</option><option value="de">德语</option><option value="it">意大利语</option><option value="yi">意第绪语</option><option value="la">拉丁语</option><option value="lv">拉脱维亚语</option><option value="no">挪威语</option><option value="cs">捷克语</option><option value="sk">斯洛伐克语</option><option value="sl">斯洛文尼亚语</option><option value="sw">斯瓦希里语</option><option value="pa">旁遮普语</option><option value="ja">日语</option><option value="ka">格鲁吉亚语</option><option value="mi">毛利语</option><option value="fr">法语</option><option value="pl">波兰语</option><option value="bs">波斯尼亚语</option><option value="fa">波斯语</option><option value="te">泰卢固语</option><option value="ta">泰米尔语</option><option value="th">泰语</option><option value="ht">海地克里奥尔语</option><option value="ga">爱尔兰语</option><option value="et">爱沙尼亚语</option><option value="sv">瑞典语</option><option value="be">白俄罗斯语</option><option value="lt">立陶宛语</option><option value="so">索马里语</option><option value="yo">约鲁巴语</option><option value="my">缅甸语</option><option value="ro">罗马尼亚语</option><option value="lo">老挝语</option><option value="fi">芬兰语</option><option value="hmn">苗语</option><option value="en">英语</option><option value="nl">荷兰语</option><option value="tl">菲律宾语</option><option value="pt">葡萄牙语</option><option value="mn">蒙古语</option><option value="es">西班牙语</option><option value="ha">豪萨语</option><option value="vi">越南语</option><option value="az">阿塞拜疆语</option><option value="sq">阿尔巴尼亚语</option><option value="ar">阿拉伯语</option><option value="ko">韩语</option><option value="mk">马其顿语</option><option value="mg">马尔加什语</option><option value="mr">马拉地语</option><option value="ml">马拉雅拉姆语</option><option value="ms">马来语</option><option value="mt">马耳他语</option><option value="km">高棉语</option><option value="ny">齐切瓦语</option></select></td> + <td class="SL_td"> + <div id="SL_switch_b" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="切换语言"> </div> + </td> + <td class="SL_td"><select><option value="eo">世界语</option><option value="zh-CN">中文简体</option><option value="zh-TW">中文繁体</option><option value="da">丹麦语</option><option value="uk">乌克兰语</option><option value="uz">乌兹别克语</option><option value="ur">乌尔都语</option><option value="hy">亚美尼亚语</option><option value="ig">伊博语</option><option value="ru">俄语</option><option value="bg">保加利亚语</option><option value="si">僧伽罗语</option><option value="hr">克罗地亚语</option><option value="is">冰岛语</option><option value="gl">加利西亚语</option><option value="ca">加泰罗尼亚语</option><option value="hu">匈牙利语</option><option value="zu">南非祖鲁语</option><option value="kn">卡纳达语</option><option value="hi">印地语</option><option value="su">印尼巽他语</option><option value="jw">印尼爪哇语</option><option value="id">印尼语</option><option value="gu">古吉拉特语</option><option value="kk">哈萨克语</option><option value="tr">土耳其语</option><option value="tg">塔吉克语</option><option value="sr">塞尔维亚语</option><option value="st">塞索托语</option><option value="cy">威尔士语</option><option value="bn">孟加拉语</option><option value="ceb">宿务语</option><option value="ne">尼泊尔语</option><option value="eu">巴斯克语</option><option value="af">布尔语(南非荷兰语)</option><option value="iw">希伯来语</option><option value="el">希腊语</option><option value="de">德语</option><option value="it">意大利语</option><option value="yi">意第绪语</option><option value="la">拉丁语</option><option value="lv">拉脱维亚语</option><option value="no">挪威语</option><option value="cs">捷克语</option><option value="sk">斯洛伐克语</option><option value="sl">斯洛文尼亚语</option><option value="sw">斯瓦希里语</option><option value="pa">旁遮普语</option><option value="ja">日语</option><option value="ka">格鲁吉亚语</option><option value="mi">毛利语</option><option value="fr">法语</option><option value="pl">波兰语</option><option value="bs">波斯尼亚语</option><option value="fa">波斯语</option><option value="te">泰卢固语</option><option value="ta">泰米尔语</option><option value="th">泰语</option><option value="ht">海地克里奥尔语</option><option value="ga">爱尔兰语</option><option value="et">爱沙尼亚语</option><option value="sv">瑞典语</option><option value="be">白俄罗斯语</option><option value="lt">立陶宛语</option><option value="so">索马里语</option><option value="yo">约鲁巴语</option><option value="my">缅甸语</option><option value="ro">罗马尼亚语</option><option value="lo">老挝语</option><option value="fi">芬兰语</option><option value="hmn">苗语</option><option selected value="en">英语</option><option value="nl">荷兰语</option><option value="tl">菲律宾语</option><option value="pt">葡萄牙语</option><option value="mn">蒙古语</option><option value="es">西班牙语</option><option value="ha">豪萨语</option><option value="vi">越南语</option><option value="az">阿塞拜疆语</option><option value="sq">阿尔巴尼亚语</option><option value="ar">阿拉伯语</option><option value="ko">韩语</option><option value="mk">马其顿语</option><option value="mg">马尔加什语</option><option value="mr">马拉地语</option><option value="ml">马拉雅拉姆语</option><option value="ms">马来语</option><option value="mt">马耳他语</option><option value="km">高棉语</option><option value="ny">齐切瓦语</option></select></td> + <td class="SL_td"> + <div id="SL_TTS_voice" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="聆听翻译"> </div> + </td> + <td class="SL_td"> + <div class="SL_copy" id="SL_copy" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="复制译文"> </div> + </td> + <td class="SL_td"> + <div id="SL_bbl_font_patch"> </div> + + <div class="SL_bbl_font" id="SL_bbl_font" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="字体大小"> </div> + </td> + <td class="SL_td"> + <div id="SL_bbl_help" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="帮助"> </div> + </td> + <td class="SL_td"> + <div class="SL_pin_off" id="SL_pin" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="固定弹出窗口"> </div> + </td> + </tr> + </tbody> +</table> +</div> +</div> + +<div id="SL_shadow_translation_result" style=""> </div> + +<div class="SL_loading" id="SL_loading" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;"> </div> + +<div id="SL_player2"> </div> + +<div id="SL_alert100">文本转语音功能仅限200个字符</div> + +<div id="SL_Balloon_options" style="background: rgb(255, 255, 255) repeat scroll 0% 0%;"> +<div id="SL_arrow_down" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;"> </div> + +<table id="SL_tbl_opt" style="width: 100%;"> + <tbody> + <tr> + <td><input></td> + <td> + <div id="SL_BBL_IMG" style="background: rgba(0, 0, 0, 0) repeat scroll 0% 0%;" title="显示翻译器的按钮 3 秒"> </div> + </td> + <td><a class="SL_options" title="显示选项">选项</a> : <a class="SL_options" title="翻译历史记录">历史</a> : <a class="SL_options" title="反馈">反馈</a> : <a class="SL_options" href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GD9D8CPW8HFA2" title="作出一点点贡献">Donate</a></td> + <td><span id="SL_Balloon_Close" title="关闭">关闭</span></td> + </tr> + </tbody> +</table> +</div> +</div> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html new file mode 100644 index 0000000000..afa54c1aaf --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html @@ -0,0 +1,307 @@ +--- +title: runtime.onMessage +slug: Mozilla/Add-ons/WebExtensions/API/runtime/onMessage +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/onMessage +--- +<div>{{AddonSidebar()}}</div> + +<div>利用此事件来监听来自你的扩展其他部分的消息。例如，使用：</div> + +<div></div> + +<ul> + <li>in a <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">content script</a>, to listen for messages from a <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background script.</a></li> + <li>in a background script, to listen for messages from a content script.</li> + <li>in an <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Options_pages">options page</a> or <a href="/en-US/Add-ons/WebExtensions/User_interface_components#Popups">popup</a> script, to listen for messages from a background script.</li> + <li>in a background script, to listen for messages from an options page or popup script.</li> +</ul> + +<p>To send a message that is received by the <code>onMessage</code> listener, use {{WebExtAPIRef("runtime.sendMessage()")}} or (to send a message to a content script) {{WebExtAPIRef("tabs.sendMessage()")}}.</p> + +<div class="blockIndicator note"> +<p>Avoid creating multiple <code>onMessage</code> listeners for the same type of message, as the order in which multiple listeners will fire is not guaranteed. Where you want to guarantee the delivery of a message to a specific end point, use the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#Connection-based_messaging">connection-based approach to exchange messages</a>.</p> +</div> + +<p>Along with the message itself, the listener is passed:</p> + +<ul> + <li>a <code>sender</code> object giving details about the message sender.</li> + <li>a <code>sendResponse</code> function that can be used to send a response back to the sender.</li> +</ul> + +<p>You can send a synchronous response to the message by calling the <code>sendResponse</code> function inside your listener. <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/onMessage#Sending_a_synchronous_response">See an example</a>.</p> + +<p>To send an asynchronous response, there are two options:</p> + +<ul> + <li>return <code>true</code> from the event listener. This keeps the <code>sendResponse</code> function valid after the listener returns, so you can call it later. <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/onMessage#Sending_an_asynchronous_response_using_sendResponse">See an example</a>.</li> + <li>return a <code>Promise</code> from the event listener, and resolve when you have the response (or reject it in case of an error). <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/onMessage#Sending_an_asynchronous_response_using_a_Promise">See an example</a>.</li> +</ul> + +<div class="warning"> +<p>Returning a <code>Promise</code> is now preferred as <code>sendResponse</code> <a href="https://github.com/mozilla/webextension-polyfill/issues/16#issuecomment-296693219">will be removed from the W3C spec</a>. The popular <a href="https://github.com/mozilla/webextension-polyfill">webextension-polyfill</a> library has already removed the <code>sendResponse</code> function from its implementation.</p> +</div> + +<div class="blockIndicator note"> +<p>You can also use a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#Connection-based_messaging">connection-based approach to exchange messages</a>.</p> +</div> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">browser.runtime.onMessage.addListener(listener) +browser.runtime.onMessage.removeListener(listener) +browser.runtime.onMessage.hasListener(listener) +</pre> + +<p>Events have three functions:</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>Adds a listener to this event.</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>Stop listening to this event. The <code>listener</code> argument is the listener to remove.</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>Checks whether a <code>listener</code> is registered for this event. Returns <code>true</code> if it is listening, <code>false</code> otherwise.</dd> +</dl> + +<h2 id="addListener_syntax">addListener syntax</h2> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>function</code></dt> + <dd> + <p>A listener function that will be called when this event occurs. The function will be passed the following arguments:</p> + + <dl class="reference-values"> + <dt><code>message</code></dt> + <dd><code>object</code>. The message itself. This is a JSON-ifiable object.</dd> + </dl> + + <dl class="reference-values"> + <dt><code>sender</code></dt> + <dd>A {{WebExtAPIRef('runtime.MessageSender')}} object representing the sender of the message.</dd> + </dl> + + <dl class="reference-values"> + <dt><code>sendResponse</code></dt> + <dd> + <p>A function to call, at most once, to send a response to the message. The function takes a single argument, which may be any JSON-ifiable object. This argument is passed back to the message sender.</p> + + <p>If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response.</p> + + <p>To send a response synchronously, call <code>sendResponse</code> before the listener function returns. To send a response asynchronously:</p> + + <ul> + <li>either keep a reference to the <code>sendResponse</code> argument and return <code>true</code> from the listener function. You will then be able to call <code>sendResponse</code> after the listener function has returned.</li> + <li>or return a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> from the listener function and resolve the promise when the response is ready. This is a preferred way.</li> + </ul> + </dd> + </dl> + + <p>The listener function can return either a Boolean or a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + + <div class="blockIndicator warning"> + <p>Do not call <code>addListener</code> using the <code>async</code> function, as in:</p> + + <pre><code>browser.runtime.onMessage.addListener(async (data, sender) => { + if (data.type === 'handle_me') return 'done'; +}); +</code></pre> + + <p>as the listener will consume every message it receives, effectively blocking all other listeners from receiving and processing messages.</p> + + <p>If you want to take an asynchronous approach, use a promise instead, as in:</p> + + <pre><code>browser.runtime.onMessage.addListener(data, sender) => { + if (data.type === 'handle_me') return Promise.resolve('done'); +}); +</code></pre> + </div> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.onMessage")}}</p> + +<h2 id="Examples">Examples</h2> + +<h3 id="Simple_example">Simple example</h3> + +<p>This content script listens for click events on the web page. If the click was on a link, it messages the background page with the target URL:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// content-script.js</span> + +window<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">"click"</span><span class="punctuation token">,</span> notifyExtension<span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="keyword token">function</span> <span class="function token">notifyExtension</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>e<span class="punctuation token">.</span>target<span class="punctuation token">.</span>tagName <span class="operator token">!=</span> <span class="string token">"A"</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">return</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span><span class="function token">sendMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span><span class="string token">"url"</span><span class="punctuation token">:</span> e<span class="punctuation token">.</span>target<span class="punctuation token">.</span>href<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">; +}</span></code> +</pre> + +<p>The background script listens for these messages and displays a notification using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications">notifications</a></code> API:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// background-script.js</span> + +browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>notify<span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="keyword token">function</span> <span class="function token">notify</span><span class="punctuation token">(</span>message<span class="punctuation token">)</span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>notifications<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + <span class="string token">"type"</span><span class="punctuation token">:</span> <span class="string token">"basic"</span><span class="punctuation token">,</span> + <span class="string token">"iconUrl"</span><span class="punctuation token">:</span> browser<span class="punctuation token">.</span>extension<span class="punctuation token">.</span><span class="function token">getURL</span><span class="punctuation token">(</span><span class="string token">"link.png"</span><span class="punctuation token">)</span><span class="punctuation token">,</span> + <span class="string token">"title"</span><span class="punctuation token">:</span> <span class="string token">"You clicked a link!"</span><span class="punctuation token">,</span> + <span class="string token">"message"</span><span class="punctuation token">:</span> message<span class="punctuation token">.</span>url + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span></code></pre> + +<h3 id="Sending_a_synchronous_response">Sending a synchronous response</h3> + +<p>This content script sends a message to the background script when the user clicks on the page. It also logs any response sent by the background script:</p> + +<pre class="brush: js">// content-script.js + +function handleResponse(message) { + console.log(`background script sent a response: ${message.response}`); +} + +function handleError(error) { + console.log(`Error: ${error}`); +} + +function sendMessage(e) { + var sending = browser.runtime.sendMessage({content: "message from the content script"}); + sending.then(handleResponse, handleError); +} + +window.addEventListener("click", sendMessage);</pre> + +<p>Here is a version of the corresponding background script, that sends a response synchronously, from inside in the listener:</p> + +<pre class="brush: js">// background-script.js + +function handleMessage(request, sender, sendResponse) { + console.log(`content script sent a message: ${request.content}`); + sendResponse({response: "response from background script"}); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<p>And here is another version, that uses Promise.resolve():</p> + +<pre class="brush: js">// background-script.js + +function handleMessage(request, sender, sendResponse) { + console.log(`content script sent a message: ${request.content}`); + return Promise.resolve({response: "response from background script"}); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<h3 id="Sending_an_asynchronous_response_using_sendResponse">Sending an asynchronous response using sendResponse</h3> + +<p>Here is an alternative version of the background script from the previous example. It sends a response asynchronously after the listener has returned. Note <code>return true;</code> in the listener: this tells the browser that you intend to use the <code>sendResponse</code> argument after the listener has returned.</p> + +<pre class="brush: js">// background-script.js + +function handleMessage(request, sender, sendResponse) { + console.log(`content script sent a message: ${request.content}`); + setTimeout(() => { + sendResponse({response: "async response from background script"}); + }, 1000); + return true; +} + +browser.runtime.onMessage.addListener(handleMessage); +</pre> + +<h3 id="Sending_an_asynchronous_response_using_a_Promise">Sending an asynchronous response using a Promise</h3> + +<p>This content script gets the first <a> link on the page and sends a message asking if the link's location is bookmarked. It expects to get a Boolean response: <code>true</code> if the location is bookmarked, <code>false</code> otherwise:</p> + +<pre class="brush: js">// content-script.js + +const firstLink = document.querySelector("a"); + +function handleResponse(isBookmarked) { + if (isBookmarked) { + firstLink.classList.add("bookmarked"); + } +} + +browser.runtime.sendMessage({ + url: firstLink.href +}).then(handleResponse);</pre> + +<p>Here is the background script. It uses <code>{{WebExtAPIRef("bookmarks.search()")}}</code> to see if the link is bookmarked, which returns a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:</p> + +<pre class="brush: js">// background-script.js + +function isBookmarked(message, sender, response) { + return browser.bookmarks.search({ + url: message.url + }).then(function(results) { + return results.length > 0; + }); +} + +browser.runtime.onMessage.addListener(isBookmarked);</pre> + +<p>If the asynchronous handler doesn't return a promise, you can explicitly construct a promise. This rather contrived example sends a response after a 1-second delay, using <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">Window.setTimeout()</a></code>:</p> + +<pre class="brush: js">// background-script.js + +function handleMessage(request, sender, sendResponse) { + return new Promise(resolve => { + setTimeout(() => { + resolve({response: "async response from background script"}); + }, 1000); + }); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#event-onMessage"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/openoptionspage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/openoptionspage/index.html new file mode 100644 index 0000000000..701af9c2ea --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/openoptionspage/index.html @@ -0,0 +1,92 @@ +--- +title: runtime.openOptionsPage() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage +tags: + - API + - OpenPractices + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage +--- +<div> </div> + +<div>假如你的页面有<a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Options_pages">options page</a>（设置页面）的定义，使用此方法打开它。</div> + +<div> </div> + +<div>这是一个异步方法，返回一个 <code style="font-style: normal; font-weight: normal;"><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>对象</code></div> + +<div> </div> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var openingPage = browser.runtime.openOptionsPage() +</pre> + +<h3 id="参数">参数</h3> + +<p>无</p> + +<h3 id="返回值">返回值</h3> + +<p><code>当设置页面成功创建，执行<a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>的无参成功回调方法，否则执行<a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>的失败回调方法，参数为错误信息。</code></p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.openOptionsPage")}}</p> + +<h2 id="例子">例子</h2> + +<p>当用户点击浏览器行为图标时，打开一个设置页面。</p> + +<pre class="brush: js">function onOpened() { + console.log(`Options page opened`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var opening = browser.runtime.openOptionsPage(); +opening.then(onOpened, onError);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#method-openOptionsPage"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformarch/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformarch/index.html new file mode 100644 index 0000000000..0adfaf39f1 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformarch/index.html @@ -0,0 +1,70 @@ +--- +title: 获取处理器架构 - runtime.PlatformArch +slug: Mozilla/Add-ons/WebExtensions/API/runtime/PlatformArch +tags: + - 获取处理器架构 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/PlatformArch +--- +<div>{{AddonSidebar()}}</div> + +<p>当前浏览器所在的计算机的处理器架构.</p> + +<h2 id="值类型">值类型</h2> + +<p>该值的类型是字符串. 可能的值如下:</p> + +<dl> + <dt><code>"arm"</code></dt> + <dd>标识平台基于 arm 架构.</dd> + <dt><code>"x86-32"</code></dt> + <dd>表示平台基于 x86 32-bit 架构.</dd> + <dt><code>"x86-64"</code></dt> + <dd>表示平台基于 x86 64-bit 架构.</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.PlatformArch")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#type-PlatformArch"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformos/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformos/index.html new file mode 100644 index 0000000000..6c32d46b6f --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/platformos/index.html @@ -0,0 +1,76 @@ +--- +title: 获取当前操作系统 - runtime.PlatformOs +slug: Mozilla/Add-ons/WebExtensions/API/runtime/PlatformOs +tags: + - 获取当前操作系统 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/PlatformOs +--- +<div>{{AddonSidebar()}}</div> + +<p>获取当前浏览器运行所在的操作系统.</p> + +<h2 id="值类型">值类型</h2> + +<p>该值的类型是字符串. 可能的值如下:</p> + +<dl> + <dt><code>"mac"</code></dt> + <dd>表示底层操作系统是 Mac OS X.</dd> + <dt><code>"win"</code></dt> + <dd>表示底层操作系统是 Windows.</dd> + <dt><code>"android"</code></dt> + <dd>表示底层操作系统是 Android.</dd> + <dt><code>"cros"</code></dt> + <dd>表示底层操作系统是 Chrome OS.</dd> + <dt><code>"linux"</code></dt> + <dd>表示底层操作系统是 Linux.</dd> + <dt><code>"openbsd"</code></dt> + <dd>表示底层操作系统是 Open/FreeBSD.</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.PlatformOs")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#type-PlatformOs"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendmessage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendmessage/index.html new file mode 100644 index 0000000000..86ec753075 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendmessage/index.html @@ -0,0 +1,157 @@ +--- +title: runtime.sendMessage() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage +--- +<div>{{AddonSidebar()}}</div> + +<div>向你的扩展或其他扩展发送单条消息。</div> + +<div> </div> + +<div>如果想发给你自己的扩展，则省略 <code>extensionId</code> 参数。扩展中所有页面的{{WebExtAPIRef('runtime.onMessage')}}将会被触发，除了调用<code>runtime.sendMessage的页面。</code></div> + +<p> </p> + +<p>如果发送给其他扩展，则将参数 <code>extensionId</code> 设置为其他扩展的ID。其他扩展的 {{WebExtAPIRef('runtime.onMessageExternal')}} 将会被触发。</p> + +<p>此接口不能给 content script 发消息，如果要给 content script 发消息，请使用 {{WebExtAPIRef('tabs.sendMessage')}}。</p> + +<p>这是个异步方法，将返回一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>。</p> + +<p>Syntax</p> + +<pre class="syntaxbox brush:js">var sending = browser.runtime.sendMessage( + extensionId, // optional string + message, // any + options // optional object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>extensionId</code>{{optional_inline}}</dt> + <dd><code>string</code>. 若你想要发给不同的扩展，这里传入接收方的扩展ID。The ID of the extension to send the message to. Include this to send the message to a different extension. If the intended recipient has set an ID explicitly using the <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> key in manifest.json, then <code>extensionId</code> should have this value. Otherwise it should be have the ID that was generated for the intended recipient.</dd> + <dd>若此省略此参数，则发送给自己的扩展。</dd> + <dt><code>message</code></dt> + <dd><code>any</code>. 任何可以序列化成JSON的东西。</dd> + <dt><code>options</code>{{optional_inline}}</dt> + <dd><code>object</code>. + <dl class="reference-values"> + <dt><code>includeTlsChannelId</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. Whether the TLS channel ID will be passed into {{WebExtAPIRef('runtime.onMessageExternal')}} for processes that are listening for the connection event.</dd> + <dt><code>toProxyScript{{optional_inline}}</code></dt> + <dd><code>boolean</code>. Must be True if the message is intended for a PAC file loaded using the {{WebExtAPIRef("proxy")}} API.</dd> + </dl> + </dd> +</dl> + +<p>根据给出的参数不同，API遵循如下规则：</p> + +<ul> + <li><strong>只有1个参数：</strong>将会被当做 message 发送给自己的扩展。</li> + <li><strong>有2个参数：</strong> + <ul> + <li>若第二个参数符合下面的规则，将会被当做 <code>(message, options)</code>，将消息发送给自己的扩展： + <ol> + <li>一个合法的配置对象（也就是说这个对象只包含options参数支持的属性）</li> + <li>null</li> + <li>undefined</li> + </ol> + </li> + <li>否则，将会被当做 <code>(extensionId, message)。</code>消息将会给发送给 <code>extensionId</code> 指定ID的扩展</li> + </ul> + </li> + <li><strong>有3个参数：</strong>将会被当做 <code>(extensionId, message, options)</code>. 消息将会给发送给 <code>extensionId</code> 指定ID的扩展</li> +</ul> + +<div class="note"> +<p>在Firefox 55之前，只给出2个参数时，规则会有所不同：<br> + Under the old rules, if the first argument was a string, it was treated as the <code>extensionId</code>, with the message as the second argument. This meant that if you called <code>sendMessage()</code> with arguments like <code>("my-message", {})</code>, then it would send an empty message to the extension identified by "my-message". Under the new rules, with these arguments you would send the message "my-message" internally, with an empty options object.</p> +</div> + +<h3 id="Return_value">Return value</h3> + +<p>返回一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>。若接收方响应，Promise将会变为 fulfilled 并且返回接收方响应的JSON对象（数字、字符串、数组、true/false都是合法的JSON对象）。否则，Promise会变为 fulfilled 但是不返回任何参数。如果发生了连接错误，Promise将会变为 rejected 并返回一个错误消息。</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.runtime.sendMessage")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>Here's a content script that sends a message to the background script when the user clicks the content window. The message payload is <code>{greeting: "Greeting from the content script"}</code>, and the sender also expects to get a response, which is handled in the <code>handleResponse</code> function:</p> + +<pre class="brush: js">// content-script.js + +function handleResponse(message) { + console.log(`Message from the background script: ${message.response}`); +} + +function handleError(error) { + console.log(`Error: ${error}`); +} + +function notifyBackgroundPage(e) { + var sending = browser.runtime.sendMessage({ + greeting: "Greeting from the content script" + }); + sending.then(handleResponse, handleError); +} + +window.addEventListener("click", notifyBackgroundPage);</pre> + +<p>The corresponding background script looks like this:</p> + +<pre class="brush: js">// background-script.js + +function handleMessage(request, sender, sendResponse) { + console.log("Message from the content script: " + + request.greeting); + sendResponse({response: "Response from background script"}); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime#method-sendMessage"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendnativemessage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendnativemessage/index.html new file mode 100644 index 0000000000..349b7a06d0 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/runtime/sendnativemessage/index.html @@ -0,0 +1,109 @@ +--- +title: runtime.sendNativeMessage() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/sendNativeMessage +tags: + - sendNativeMessage + - 扩展 + - 附加组件 + - 非标准 +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/sendNativeMessage +--- +<div>{{AddonSidebar()}}</div> + +<p>从 WebExtension 发送单条消息到 native application。</p> + +<p>它需要两个强制的参数：native application 的名字和要发送给它的JSON对象。浏览器将会加载 native application 然后发送这个消息。</p> + +<p>这是一个异步函数，返回一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>对象。native application 发送的第一条消息将被当作<code>sendNativeMessage()</code> 的回复，并且 promise 将这个消息作为参数.。注意你不能使用 {{WebExtAPIRef("runtime.onMessage")}} 从应用获取回复：你必须使用回调函数来替代。</p> + +<p>每次调用 <code>runtime.sendNativeMessage()</code>都会生成一个新的实例。浏览器将会在收到回复后结束这个 native application。为了结束这个 native application，浏览器将会关闭 pipe，并给进程几秒的时间优雅的退出，如果它没有关闭就杀死它。</p> + +<p>更对信息，参考 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">Native messaging</a>。</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var sending = browser.runtime.sendNativeMessage( + application, // string + message // object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>application</code></dt> + <dd><code>字符串类型。</code>native application的名字。它必须和 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging#App_manifest">native application's manifest file</a>中的‘name’字段一致。</dd> + <dt><code>message</code></dt> + <dd><code>对象类型。一个将要发送给</code> native application的JSON对象。</dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>对象。如果native application发送了一个回复，它将会填充回复的JSON对象作为参数。否则它不会填充参数。如果在native application连接期间发生了错误，promise将会被一个错误的消息拒绝。</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">这个页面的兼容性表从结构性数据生成的。如果你想提供数据，请访问 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 然后提交请求。</p> + +<p>{{Compat("webextensions.api.runtime.sendNativeMessage")}}</p> + +<h2 id="示例">示例</h2> + +<p>这是一个 background script ，当使用者点击浏览器的browser action时，它会发送 "ping" 消息到 "ping_pong" 应用并且把回复记录下来：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">onResponse</span><span class="punctuation token">(</span>response<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">`Received ${</span>response}<span class="punctuation token">`)</span><span class="punctuation token">;</span> +<span class="punctuation token">} + +</span></code>function onError(error) { + console.log(`Error: ${error}`); +}<code class="language-js"> + +<span class="comment token">/* +On a click on the browser action, send the app a message. +*/</span> +browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="operator token">=</span><span class="operator token">></span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">"Sending: ping"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + var sending = browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span><span class="function token">sendNativeMessage</span><span class="punctuation token">(</span><span class="string token">"ping_pong"</span><span class="punctuation token">,</span> <span class="string token">"ping"</span><span class="punctuation token">)</span><span class="punctuation token">; + sending.then(onResponse, onError);</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>这个API 基于 Chromium 的 <a href="https://developer.chrome.com/extensions/runtime#method-sendNativeMessage"><code>chrome.runtime</code></a> API。 本文来自 Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> 。</p> + +<p>微软 Edge 的兼容性数据由 Microsoft Corporation 提供，并且包含在这里基于 Creative Commons Attribution 3.0 United States License。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/search/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/search/index.html new file mode 100644 index 0000000000..4a8c5e320b --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/search/index.html @@ -0,0 +1,34 @@ +--- +title: search +slug: Mozilla/Add-ons/WebExtensions/API/search +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Reference + - Search + - Search Engines + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/search +--- +<div>{{AddonSidebar}}</div> + +<p>Retrieves search engines and executes a search with a specific search engine.</p> + +<p>To use this API you need to have the <code>"search"</code> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("search.get()")}}</dt> + <dd>Retrieve all search engines.</dd> + <dt>{{WebExtAPIRef("search.search()")}}</dt> + <dd>Search using the specified search engine.</dd> + <dt> + <h2 id="Browser_compatibility">Browser compatibility</h2> + </dt> +</dl> + +<p>{{Compat("webextensions.api.search", 1, 1)}} {{WebExtExamples("h2")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/search/search/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/search/search/index.html new file mode 100644 index 0000000000..bb3a122a64 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/search/search/index.html @@ -0,0 +1,93 @@ +--- +title: search.search() +slug: Mozilla/Add-ons/WebExtensions/API/search/search +translation_of: Mozilla/Add-ons/WebExtensions/API/search/search +--- +<div>{{AddonSidebar()}}</div> + +<p>使用指定的搜索引擎或默认搜索引擎进行搜索。</p> + +<p>结果将显示在一个新的选项卡中，或者如果给出了tabId参数，则显示在由此标识的选项卡中。</p> + +<p>要在扩展程序中使用此功能，您必须要求<code>"search"</code> <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">有明确许可</a>.</p> + +<p>获取安装的搜索引擎, 请使用 {{WebExtAPIRef("search.get()")}}.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js notranslate">browser.search.search( + searchProperties // object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl class="reference-values"> + <dt><code>searchProperties</code></dt> + <dd> + <p><code>object</code>. 拥有以下属性的对象:</p> + + <dl class="reference-values"> + <dt><code>query</code></dt> + <dd><code>字符串</code>. 进行查询的内容。</dd> + <dt><code>engine</code>{{optional_inline}}</dt> + <dd> + <p><code>字符串。</code>.搜索引擎的名称。 如果指定的搜索引擎名称不存在，该函数将引发错误。 如果省略此属性，则使用默认的搜索引擎。</p> + </dd> + <dt><code>tabId</code>{{optional_inline}}</dt> + <dd> + <p><font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">整型。</span></font>用于显示搜索结果的选项卡。如果省略此属性，搜索结果将显示在新选项卡中。</p> + </dd> + </dl> + </dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>无.</p> + +<h2 id="浏览器兼容">浏览器兼容</h2> + +<p class="hidden">此页面中的兼容性表是根据结构化数据生成的。 如果您想贡献数据，请查看<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> ，并向我们发送请求请求。</p> + +<p>{{Compat("webextensions.api.search.search", 10)}}</p> + +<h2 id="例子">例子</h2> + +<p>使用默认搜索引擎进行搜索。 结果显示在新选项卡中：</p> + +<pre class="brush: js no-line-numbers notranslate">function search() { + browser.search.search({ + query: "styracosaurus" + }); +} + +browser.browserAction.onClicked.addListener(search); +</pre> + +<p>使用维基百科进行搜索。 结果显示在新选项卡中：</p> + +<pre class="brush: js no-line-numbers notranslate">function search() { + browser.search.search({ + query: "styracosaurus", + engine: "Wikipedia (en)" + }); +} + +browser.browserAction.onClicked.addListener(search); +</pre> + +<p>使用维基百科进行搜索。 结果将显示在活动选项卡中：</p> + +<pre class="brush: js no-line-numbers notranslate">function search(tab) { + browser.search.search({ + query: "styracosaurus", + engine: "Wikipedia (en)", + tabId: tab.id + }); +} + +browser.browserAction.onClicked.addListener(search); +</pre> + +<p>{{WebExtExamples}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/index.html new file mode 100644 index 0000000000..65afc6692b --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/index.html @@ -0,0 +1,136 @@ +--- +title: sessions +slug: Mozilla/Add-ons/WebExtensions/API/sessions +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - sessions +translation_of: Mozilla/Add-ons/WebExtensions/API/sessions +--- +<div>{{AddonSidebar}}</div> + +<p>Use the sessions API to list, and restore, tabs and windows that have been closed while the browser has been running.</p> + +<p>The {{WebExtAPIRef("sessions.getRecentlyClosed()")}} function returns an array of {{WebExtAPIRef("tabs.Tab")}} and {{WebExtAPIRef("windows.Window")}} objects, representing tabs and windows that have been closed since the browser was running, up to the maximum defined in {{WebExtAPIRef("sessions.MAX_SESSION_RESULTS")}}.</p> + +<p>You can then restore a window or tab using the {{WebExtAPIRef("sessions.restore()")}} function. Restoring doesn't just reopen the tab: it also restores the tab's navigation history so the back/forward buttons will work.</p> + +<p>This API also provides a group of functions that enable an extension to store additional state associated with a tab or a window. Then, if the tab or window is closed and subsequently restored, the extension can retrieve the state. For example, a tab grouping extension might use this to remember which group a tab is in, so as to restore it into the right group if the user restores the tab.</p> + +<p>To use the sessions API you must have the "sessions" <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a>.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("sessions.Filter")}}</dt> + <dd>Enables you to restrict the number of {{WebExtAPIRef("sessions.Session", "Session")}} objects returned by a call to {{WebExtAPIRef("sessions.getRecentlyClosed()")}}.</dd> + <dt>{{WebExtAPIRef("sessions.Session")}}</dt> + <dd> + <p>Represents a tab or window that the user has closed in the current browsing session.</p> + </dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("sessions.MAX_SESSION_RESULTS")}}</dt> + <dd>The maximum number of sessions that will be returned by a call to <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sessions/getRecentlyClosed" title="Returns an array Session objects, representing windows and tabs that were closed in the current browsing session (that is: the time since the browser was started)."><code>sessions.getRecentlyClosed()</code></a>.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("sessions.forgetClosedTab()")}}</dt> + <dd>Removes a closed tab from the browser's list of recently closed tabs.</dd> + <dt>{{WebExtAPIRef("sessions.forgetClosedWindow()")}}</dt> + <dd>Removes a closed window from the browser's list of recently closed windows.</dd> + <dt>{{WebExtAPIRef("sessions.getRecentlyClosed()")}}</dt> + <dd>Returns an array of {{WebExtAPIRef("sessions.Session", "Session")}} objects, representing windows and tabs that were closed in the current browsing session (that is: the time since the browser was started).</dd> + <dt>{{WebExtAPIRef("sessions.restore()")}}</dt> + <dd> + <p>Restores a closed tab or window.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.setTabValue()")}}</dt> + <dd> + <p>Store a key/value pair associated with a given tab.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.getTabValue()")}}</dt> + <dd> + <p>Retrieve a previously stored value for a given tab, given its key.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.removeTabValue()")}}</dt> + <dd> + <p>Remove a key/value pair from a given tab.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.setWindowValue()")}}</dt> + <dd> + <p>Store a key/value pair associated with a given window.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.getWindowValue()")}}</dt> + <dd> + <p>Retrieve a previously stored value for a given window, given its key.</p> + </dd> + <dt>{{WebExtAPIRef("sessions.removeWindowValue()")}}</dt> + <dd> + <p>Remove a key/value pair from a given window.</p> + </dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("sessions.onChanged")}}</dt> + <dd> + <p>Fired when a tab or window is closed.</p> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.sessions")}}</p> + +<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/sessions"><code>chrome.sessions</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/session/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/session/index.html new file mode 100644 index 0000000000..8b0c86204d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/sessions/session/index.html @@ -0,0 +1,78 @@ +--- +title: sessions.Session +slug: Mozilla/Add-ons/WebExtensions/API/sessions/Session +translation_of: Mozilla/Add-ons/WebExtensions/API/sessions/Session +--- +<div><font><font>{{AddonSidebar()}}</font></font></div> + +<p><font><font>该</font></font><code>Session</code><font><font>对象表示用户在当前浏览会话中已关闭的选项卡或窗口。</font></font></p> + +<p><font><font>如果关闭了选项卡但未关闭其窗口，则会话以{{WebExtAPIRef("tabs.Tab", "Tab")}}对象表示：例如，因为用户单击了“关闭选项卡”按钮，并且此选项卡不是其窗口中的唯一选项卡。</font></font></p> + +<p><font><font>如果关闭窗口，则会话表示为{{WebExtAPIRef("windows.Window", "Window")}}对象：例如，由于用户单击“关闭窗口”按钮，或关闭了窗口中唯一打开的选项卡。</font></font></p> + +<p><font><font>请注意，不同的浏览器可能对会话何时为Tab和何时为Window有不同的想法。</font><font>例如：</font></font></p> + +<ul> + <li><font><font>在Chrome中，如果用户关闭包含多个标签的窗口，则会话将记录为“窗口”。</font><font>如果用户关闭了仅包含一个选项卡的窗口，则该窗口将记录为一个选项卡。</font></font></li> + <li><font><font>在Firefox中，如果用户关闭窗口（或该窗口中最后一个选项卡的选项卡），则将会话记录为窗口，如果用户关闭窗口中最后一个选项卡中的选项卡，则将会话记录为一个Tab。</font></font></li> +</ul> + +<p><font><font>打开的选项卡的Tab对象没有</font></font><code>sessionId</code><font><font>。</font><font>关闭选项卡时，它将具有一个</font></font><code>sessionId</code><font><font>但没有选项卡</font></font><code>id</code><font><font>。</font><font>如果恢复了该标签页，它将获得一个新的标签页，</font></font><code>id</code><font><font>并且会丢失</font></font><code>sessionId</code><font><font>。</font></font></p> + +<h2 id="类型"><font><font>类型</font></font></h2> + +<p><font><font>此类型的值是对象。</font><font>它们包含以下属性：</font></font></p> + +<dl class="reference-values"> + <dt><code>lastModified</code></dt> + <dd><code>number</code><font><font>。</font><font>选项卡或窗口关闭的时间，</font></font><a href="https://en.wikipedia.org/wiki/Unix_time"><font><font>自epoch以来的毫秒数</font></font></a><font><font>。</font></font></dd> + <dt><code>tab</code><font><font>{{optional_inline}}</font></font></dt> + <dd><code>object</code><font><font>。</font><font>如果对象表示关闭的选项卡，则此属性存在，并且将是{{WebExtAPIRef("tabs.Tab")}}对象。</font><font>仅当扩展名具有“ tabs” </font><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions"><font>许可</font></a><font>权时</font></font><code>url</code><font><font>，</font><font>它才会包含</font></font><code>title</code><font><font>和</font><font>。</font></font><code>favIconUrl</code></dd> + <dt><code>window</code><font><font>{{optional_inline}}</font></font></dt> + <dd><code>object</code><font><font>。</font><font>如果对象表示一个关闭的窗口，则此属性存在并且将是{{WebExtAPIRef("windows.Window")}}对象。</font></font></dd> +</dl> + +<h2 id="浏览器兼容性"><font><font>浏览器兼容性</font></font></h2> + +<p class="hidden"><font><font>此页面中的兼容性表是根据结构化数据生成的。</font><font>如果您想提供数据，请查看</font></font><a href="https://github.com/mdn/browser-compat-data"><font><font>https://github.com/mdn/browser-compat-data</font></font></a><font><font>并向我们发送请求请求。</font></font></p> + +<p><font><font>{{Compat("webextensions.api.sessions.Session")}}</font></font></p> + +<div class="note"><strong><font><font>致谢</font></font></strong> + +<p><font><font>该API基于Chromium的</font></font><a href="https://developer.chrome.com/extensions/sessions"><code>chrome.sessions</code></a><font><font>API。</font></font></p> + +<p><font><font>Microsoft Edge兼容性数据由Microsoft Corporation提供，并在此处包含在Creative Commons Attribution 3.0美国许可证下。</font></font></p> +</div> + +<div class="hidden"> +<pre class="notranslate"><font><font>//版权所有2015 The Chromium Authors。</font><font>版权所有。</font></font><font><font> +//</font></font><font><font> +//以或不以源代码和二进制格式重新分发和使用</font></font><font><font> +//修改，只要满足以下条件</font></font><font><font> +//遇到：</font></font><font><font> +//</font></font><font><font> +// *重新分发源代码必须保留上述版权</font></font><font><font> +//注意，此条件列表和以下免责声明。</font></font><font><font> +// *二进制形式的重新分发必须重现上述内容</font></font><font><font> +//版权声明，此条件列表和以下免责声明</font></font><font><font> +//在随附的文档和/或其他材料中</font></font><font><font> +//分配。</font></font><font><font> +// *无论是Google Inc.的名称还是Google Inc.的名称</font></font><font><font> +//贡献者可用于认可或宣传由</font></font><font><font> +//此软件未经事先特别书面许可。</font></font><font><font> +//</font></font><font><font> +//此软件由版权所有者和贡献者提供</font></font><font><font> +//“按原样”以及任何明示或暗示的保证，包括但不限于</font></font><font><font> +//仅限于对产品的适销性和适用性的默示担保</font></font><font><font> +//不提供特殊用途。</font><font>在任何情况下，版权</font></font><font><font> +//所有者或贡献者对任何直接，间接，偶然的，</font></font><font><font> +//特殊，示范性或后果性损害（包括但不包括）</font></font><font><font> +//仅限于，购买替代商品或服务；</font><font>使用损失，</font></font><font><font> +//数据或利润；</font><font>或业务中断）</font></font><font><font> +//责任理论，无论是合同形式，严格责任还是侵权行为</font></font><font><font> +//（包括疏忽大意或其他原因）出于使用目的的任何方式</font></font><font><font> +//即使已告知可能发生此类损坏，也可以使用本软件。</font></font> +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/storage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/storage/index.html new file mode 100644 index 0000000000..2dc4dd3131 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/storage/index.html @@ -0,0 +1,103 @@ +--- +title: storage +slug: Mozilla/Add-ons/WebExtensions/API/storage +tags: + - Add-ons + - Extensions + - Strorage +translation_of: Mozilla/Add-ons/WebExtensions/API/storage +--- +<div>{{AddonSidebar}}</div> + +<div>使浏览器扩展能够储存及获取数据，以及监听储存的数据的变化。</div> + +<div></div> + +<p>此存储系统API基于 <a href="/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a>, 并有少许不同。</p> + +<p>为了使用该API，您需要在<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>文件包含"storage"<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/manifest.json/permissions">权限</a>。每一个浏览器扩展有自己的储存<font face="Consolas, Liberation Mono, Courier, monospace">区域</font>，每一个储存<font face="Consolas, Liberation Mono, Courier, monospace">区域</font>又分为几种不同的存储类型。</p> + +<p>虽然此API类似于{{domxref("Window.localStorage")}}，但仍建议您不要在插件中使用<code>Window.localStorage。当用户由于隐私原因清除历史浏览记录及数据时，火狐会将在浏览器扩展使用</code> localStorage API存储的数据一并清除。而使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/local">storage.local</a>API存储的数据将会恰当保留。</code></p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea")}}</dt> + <dd>代表存储<font face="Consolas, Liberation Mono, Courier, monospace">区域</font>的对象</dd> + <dt>{{WebExtAPIRef("storage.StorageChange")}}</dt> + <dd>代表改变一个储存<font face="Consolas, Liberation Mono, Courier, monospace">区域</font>的对象</dd> +</dl> + +<h2 id="属性">属性</h2> + +<p><font face="Consolas, Liberation Mono, Courier, monospace">storage有3个属性，每一个代表不同的存储区域。</font></p> + +<dl> + <dt>{{WebExtAPIRef("storage.sync")}}</dt> + <dd>表示一个同步的储存区域。在此区域的数据通过浏览器进行同步，用户可通过登录使用不同的设备访问到浏览器所有可用的实例对象。</dd> + <dt>{{WebExtAPIRef("storage.local")}}</dt> + <dd>表示一个本地的存储区域。此区域的数据属于其所在的插件。</dd> + <dt>{{WebExtAPIRef("storage.managed")}}</dt> + <dd>表示管理的存储区域。此区域的数据由本域名下的管理员设置且对该插件是只读的。试图修改此区域数据会得到一个错误。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.onChanged")}}</dt> + <dd>当storage有数据变化时，此事件将被触发。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.storage")}}</p> + +<div class="hidden note"> +<p>"Chrome不兼容"这部分来源于 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> 使用<a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>如果需要更新这部分，请编辑 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, 然后刷新页面即可看见所做更改。</p> +</div> + +<h3 id="在Edge中的不兼容">在Edge中的不兼容</h3> + +<p>Promises在Edge中不被支持，使用callbacks代替。</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>这个API基于Chromium的 <a href="https://developer.chrome.com/extensions/storage"><code>chrome.storage</code></a> API. 这篇文档也来源于Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a>.</p> + +<p>Microsoft Edge的适配数据由Microsoft Corporation提供并且被包含在Creative Commons Attribution 3.0 United States License许可证下.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/create/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/create/index.html new file mode 100644 index 0000000000..82921cc3ea --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/create/index.html @@ -0,0 +1,137 @@ +--- +title: tabs.create() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/create +tags: + - API + - 扩展 + - 方法 + - 标签页 + - 页面扩展 +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/create +--- +<div>{{AddonSidebar()}}</div> + +<p>新建一个 tab.</p> + +<p>这是一个异步函数,返回 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var creating = browser.tabs.create( + createProperties // object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>createProperties</code></dt> + <dd><code>object</code>. Properties to give the new tab. To learn more about these properties, see the {{WebExtAPIRef("tabs.Tab")}} documentation.</dd> + <dd> + <dl class="reference-values"> + <dt><code>active</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see {{WebExtAPIRef('windows.update')}}). Defaults to <code>true</code>.</dd> + <dt><code>cookieStoreId</code> {{optional_inline}}</dt> + <dd><code>string</code>. Use this to create a tab whose cookie store ID is <code>cookieStoreId</code>. This option is only available if the extension has the <code>"cookies"</code> <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</dd> + <dt><code>index</code>{{optional_inline}}</dt> + <dd><code>integer</code>. The position the tab should take in the window. The provided value will be clamped to between zero and the number of tabs in the window.</dd> + <dt><code>openerTabId</code>{{optional_inline}}</dt> + <dd><code>integer</code>. The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as the newly created tab.</dd> + <dt><code>openInReaderMode</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. If <code>true</code>, open this tab in <a href="/en-US/Add-ons/WebExtensions/API/tabs/toggleReaderMode">Reader Mode</a>. Defaults to <code>false</code>.</dd> + <dt><code>pinned</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. Whether the tab should be pinned. Defaults to <code>false</code>.</dd> + <dt><code>selected</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. Whether the tab should become the selected tab in the window. Defaults to <code>true</code>. + <div class="warning">This property is deprecated, and is not supported in Firefox. Use <code>active</code> instead.</div> + </dd> + <dt><code>url</code>{{optional_inline}}</dt> + <dd><code>string</code>. The URL to navigate the tab to initially. Defaults to the New Tab Page.</dd> + <dd>Fully-qualified URLs must include a scheme (i.e. 'http://www.google.com', not 'www.google.com').</dd> + <dd>For security reasons, in Firefox, this may not be a privileged URL. So passing any of the following URLs will fail:</dd> + <dd> + <ul> + <li>chrome: URLs</li> + <li>javascript: URLs</li> + <li>data: URLs</li> + <li>file: URLs (i.e., files on the filesystem. However, to use a file packaged inside the extension, see below)</li> + <li>privileged about: URLs (for example, <code>about:config</code>, <code>about:addons</code>, <code>about:debugging</code>)<span style="display: none;"> </span>. Non-privileged URLs (e.g., <code>about:blank</code>) are allowed.</li> + <li>The New Tab page (<code>about:newtab</code>) can be opened if no value for URL is provided.</li> + </ul> + + <p>To load a page that's packaged with your extension, specify an absolute URL starting at the extension's manifest.json file. For example: '/path/to/my-page.html'. If you omit the leading '/', the URL is treated as a relative URL, and different browsers may construct different absolute URLs.</p> + </dd> + <dt><code>windowId</code>{{optional_inline}}</dt> + <dd><code>integer</code>. The window to create the new tab in. Defaults to the current window.</dd> + </dl> + </dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with a {{WebExtAPIRef('tabs.Tab')}} object containing details about the created tab. If the tab could not be created (for example, because <code>url</code> used a privileged scheme) the promise will be rejected with an error message.</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.create", 10)}}</p> + +<h2 id="实例">实例</h2> + +<p>在新标签页打开 "https://example.org" :</p> + +<pre class="brush: js">function onCreated(tab) { + console.log(`Created new tab: ${tab.id}`) +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.browserAction.onClicked.addListener(function() { + var creating = browser.tabs.create({ + url:"https://example.org" + }); + creating.then(onCreated, onError); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#method-create"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/discard/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/discard/index.html new file mode 100644 index 0000000000..d988e6682d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/discard/index.html @@ -0,0 +1,108 @@ +--- +title: tabs.discard() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/discard +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/discard +--- +<div>{{AddonSidebar()}}</div> + +<p>丢弃一个或多个标签页。</p> + +<p>一些浏览器会自动“丢弃”它们认为近期不再被用户所需要的标签页。这些标签页会在标签栏中保持可见，浏览器会记住它们的状态，所以，如果用户选中了被丢弃的标签页，它会立即还原到被丢弃之前的状态。</p> + +<p>对于不同的浏览器，被丢弃内容的详细内容是有所不同的，但是从大体上来说，丢弃一个标签页允许浏览器释放一些该标签页所占用的内存。</p> + +<p>The {{WebExtAPIRef("tabs.discard()")}} API enables an extension to discard one or more tabs. It's not possible to discard the currently active tab, or a tab whose document contains a <code><a href="/en-US/docs/Web/Events/beforeunload">beforeunload</a></code> listener that would display a prompt.</p> + +<p>This is an asynchronous function that returns a <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var discarding = browser.tabs.discard( + tabIds // integer or integer array +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>tabIds</code></dt> + <dd><code><code>integer</code></code> or <code><code>array</code></code> of <code><code><code>integer</code></code></code>. The IDs of the tab or tabs to discard.</dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with no arguments when all the specified tabs have been discarded. If any error occurs (for example, invalid tab IDs), the promise will be rejected with an error message.</p> + +<p>If the ID of the active tab is passed in, it will not be discarded, but the promise will be fulfilled and any other tabs passed in will be discarded.</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.discard", 10)}}</p> + +<h2 id="示例">示例</h2> + +<p>丢弃一个标签页：</p> + +<pre class="brush: js">function onDiscarded() { + console.log(`Discarded`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var discarding = browser.tabs.discard(2); +discarding.then(onDiscarded, onError);</pre> + +<p>丢弃多个标签页：</p> + +<pre class="brush: js">function onDiscarded() { + console.log(`Discarded`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var discarding = browser.tabs.discard([15, 14, 1]); +discarding.then(onDiscarded, onError);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#method-discard"><code>chrome.tabs</code></a> API.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/executescript/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/executescript/index.html new file mode 100644 index 0000000000..f32dd6cfc6 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/executescript/index.html @@ -0,0 +1,173 @@ +--- +title: tabs.executeScript() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/executeScript +tags: + - Chrome Extensions + - Extensions + - Plugins + - WebExtensions + - executeScript + - tabs.executeScript() +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/executeScript +--- +<div>{{AddonSidebar()}}</div> + +<p>将 JavaScript 代码注入页面。</p> + +<p>You can inject code into pages whose URL can be expressed using a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match pattern</a>: meaning, its scheme must be one of "http", "https", "file", "ftp". To do this you must have the permission for the page's URL, either explicitly as a <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission</a>, or via the <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">activeTab permission</a>.</p> + +<p>You can also inject code into pages packaged with your own extension:</p> + +<pre class="brush: js">browser.tabs.create({url: "/my-page.html"}).then(() => { + browser.tabs.executeScript({ + code: `console.log('location:', window.location.href);` + }); +});</pre> + +<p>You don't need any special permissions to do this.</p> + +<p>You <em>can't</em> inject code into any of the browser's built-in pages, such as about:debugging, about:addons, or the page that opens when you open a new empty tab.</p> + +<p>The scripts you inject are called content scripts. <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">Learn more about content scripts</a>.</p> + +<p>This is an asynchronous function that returns a <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">var executing = browser.tabs.executeScript( + tabId, // optional integer + details // object +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>tabId</code> {{optional_inline}}</dt> + <dd><code>integer</code>. The ID of the tab in which to run the script. Defaults to the active tab of the current window.</dd> + <dt><code>details</code></dt> + <dd>An object describing the script to run. It contains the following properties:</dd> + <dd> + <dl class="reference-values"> + <dt><code>allFrames</code> {{optional_inline}}</dt> + <dd><code>boolean</code>. If <code>true</code>, the code will be injected into all frames of the current page. If <code>true</code> and <code>frameId</code> is set, then it will raise an error, frameId and allFrames are mutually exclusive. If it is <code>false</code>, code is only injected into the top frame. Defaults to <code>false</code>.</dd> + <dt><code>code</code> {{optional_inline}}</dt> + <dd><code>string</code>. Code to inject, as a text string. <strong>Warning:</strong> Don’t use this property to interpolate untrusted data into JavaScript, as this could lead to a security issue.</dd> + <dt><code>file</code> {{optional_inline}}</dt> + <dd><code>string</code>. Path to a file containing the code to inject. In Firefox, relative URLs not starting at the extension root are resolved relative to the current page URL. In Chrome, these URLs are resolved relative to the extension's base URL. To work cross-browser, you can specify the path as a relative URL, starting at the extension's root, like this: <code>"/path/to/script.js"</code>.</dd> + <dt><code>frameId</code> {{optional_inline}}</dt> + <dd><code>integer</code>. The frame where the code should be injected. Defaults to <code>0</code> (the top-level frame).</dd> + <dt><code>matchAboutBlank</code> {{optional_inline}}</dt> + <dd><code>boolean</code>. If <code>true</code>, the code will be injected into embedded "about:blank" and "about:srcdoc" frames if your extension has access to their parent document. The code cannot be inserted in top-level about: frames. Defaults to <code>false</code>.</dd> + <dt><code>runAt</code> {{optional_inline}}</dt> + <dd>{{WebExtAPIRef('extensionTypes.RunAt')}}. The soonest that the code will be injected into the tab. Defaults to "document_idle".</dd> + </dl> + </dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with an array of objects, representing the result of the script in every injected frame.</p> + +<p>The result of the script is the last evaluated statement, which is similar to what would be output (the results, not any <code>console.log()</code> output) if you executed the script in the <a href="/en-US/docs/Tools/Web_Console">Web Console</a>. For example, consider a script like this:</p> + +<pre class="brush: js">var foo='my result';foo;</pre> + +<p>Here the results array will contain the the string "<code>my result</code>" as an element. The result values must be <a href="/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">structured clonable</a>.</p> + +<p>If any error occurs the promise will be rejected with an error message.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.executeScript")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>This example executes a one-line code snippet in the currently active tab:</p> + +<pre class="brush: js">function onExecuted(result) { + console.log(`We made it green`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var makeItGreen = 'document.body.style.border = "5px solid green"'; + +var executing = browser.tabs.executeScript({ + code: makeItGreen +}); +executing.then(onExecuted, onError);</pre> + +<p>This example executes a script from a file, packaged with the extension, called "content-script.js". The script is executed in the currently active tab. The script is executed in subframes as well as the main document:</p> + +<pre class="brush: js">function onExecuted(result) { + console.log(`We executed in all subframes`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var executing = browser.tabs.executeScript({ + file: "/content-script.js", + allFrames: true +}); +executing.then(onExecuted, onError);</pre> + +<p>This example executes a script from a file, packaged with the extension, called "content-script.js". The script is executed in the tab with an ID of 2:</p> + +<pre class="brush: js">function onExecuted(result) { + console.log(`We executed in tab 2`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +var executing = browser.tabs.executeScript( + 2, { + file: "/content-script.js" +}); +executing.then(onExecuted, onError);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#method-executeScript"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/index.html new file mode 100644 index 0000000000..868b3e1238 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/index.html @@ -0,0 +1,192 @@ +--- +title: tabs +slug: Mozilla/Add-ons/WebExtensions/API/tabs +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - tabs +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs +--- +<div>{{AddonSidebar}}</div> + +<p>与浏览器标签系统进行交互。</p> + +<p>你可以使用该API获取一个已打开标签的列表并且使用各种标准过滤标签，并进行 打开， 刷新，移动，重载，移除操作。该API不能直接访问标签中的主机内容，但是你可以使用 {{WebExtAPIRef("tabs.executeScript()")}} 或者 {{WebExtAPIRef("tabs.insertCSS()")}} APIs，来插入javascript和CSS。</p> + +<p>你可以在不需要任何特殊权限的情况下使用该APIS的大部分， 除了:</p> + +<ul> + <li>获取 <code>Tab.url</code>, <code>Tab.title</code>, and <code>Tab.favIconUrl</code>, 你需要拥有 "tabs" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>. 在火狐，这也意味着你需要 "tabs" ，来通过URL使用 {{WebExtAPIRef("tabs.query", "query")}}。</li> + <li>使用 {{WebExtAPIRef("tabs.executeScript()")}} 或者 {{WebExtAPIRef("tabs.insertCSS()")}} 你必须在目标标签拥有 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission</a> 。</li> +</ul> + +<p>或者你可以仅仅只为当前的活动标签临时的获取这些权限并且仅仅只响应一个显示的用户行为，请查看 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">"activeTab" permission</a>.</p> + +<h2 id="枚举值">枚举值</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.MutedInfoReason")}}</dt> + <dd>确定一个标签静音与否的原因（用户修改，扩展修改）。</dd> + <dt>{{WebExtAPIRef("tabs.MutedInfo")}}</dt> + <dd>该对象包含一个布尔值只是该标签是否静音，以及最近一次静音的原因。</dd> + <dt>{{WebExtAPIRef("tabs.Tab")}}</dt> + <dd>该值包含了一个标签的信息。</dd> + <dt>{{WebExtAPIRef("tabs.TabStatus")}}</dt> + <dd>指示某个标签是否已经加载完成</dd> + <dt>{{WebExtAPIRef("tabs.WindowType")}}</dt> + <dd>包含该标签的窗口类型。</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettingsMode")}}</dt> + <dd>定义缩放由浏览器控制或是扩展，或者禁用。</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettingsScope")}}</dt> + <dd>定义缩放将对某个网址持续生效，或者仅仅只针对该标签。</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettings")}}</dt> + <dd>定义缩放设置。 {{WebExtAPIRef("tabs.ZoomSettingsMode", "mode")}}, {{WebExtAPIRef("tabs.ZoomSettingsScope", "scope")}}, 和默认缩放比例。</dd> +</dl> + +<h2 id="属性">属性</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.TAB_ID_NONE")}}</dt> + <dd>给予非浏览器标签的一个特殊ID值 （比如，在开发工具中的标签）。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.connect()")}}</dt> + <dd>在运行于该标签的任何 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts </a> 和该扩展的后台脚本（或者其他的比如弹出菜单脚本或者设置页面脚本）间创建一个消息连接。</dd> + <dt>{{WebExtAPIRef("tabs.create()")}}</dt> + <dd>创建一个新标签。</dd> + <dt>{{WebExtAPIRef("tabs.captureVisibleTab()")}}</dt> + <dd>创意一个数据统一资源标识符解码在规定窗口中当前活动标签的可视区域重的一个图片。</dd> + <dt>{{WebExtAPIRef("tabs.detectLanguage()")}}</dt> + <dd>检查在一个标签中的主要语言。</dd> + <dt>{{WebExtAPIRef("tabs.duplicate()")}}</dt> + <dd>复制一个标签</dd> + <dt>{{WebExtAPIRef("tabs.executeScript()")}}</dt> + <dd>向一个页面注入脚本。</dd> + <dt>{{WebExtAPIRef("tabs.get()")}}</dt> + <dd>取回制定标签的详细信息。</dd> + <dt>{{WebExtAPIRef("tabs.getAllInWindow()")}} {{deprecated_inline}}</dt> + <dd>获取指定窗口所有标签的详细信息。</dd> + <dt>{{WebExtAPIRef("tabs.getCurrent()")}}</dt> + <dd>返回一个 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Tabs/Tab" title="This type contains information about a tab."><code>tabs.Tab</code></a> 对象包含了该脚本当前的宿主标签的信息。</dd> + <dt>{{WebExtAPIRef("tabs.getSelected()")}} {{deprecated_inline}}</dt> + <dd>获取在指定窗口被选定的标签。</dd> + <dt>{{WebExtAPIRef("tabs.getZoom()")}}</dt> + <dd>获取制定标签的缩放系数。</dd> + <dt>{{WebExtAPIRef("tabs.getZoomSettings()")}}</dt> + <dd>获取指定标签的缩放设置。</dd> + <dt>{{WebExtAPIRef("tabs.highlight()")}}</dt> + <dd>高亮显示一个或多个标签。</dd> + <dt>{{WebExtAPIRef("tabs.insertCSS()")}}</dt> + <dd>向一个页面注入CSS。</dd> + <dt>{{WebExtAPIRef("tabs.removeCSS()")}}</dt> + <dd>移除之前调用{{WebExtAPIRef("tabs.insertCSS()")}} 注入的一个css。</dd> + <dt>{{WebExtAPIRef("tabs.move()")}}</dt> + <dd>移动一个或多个标签页到同一窗口的一个新的位置或是到不同窗口。</dd> + <dt>{{WebExtAPIRef("tabs.query()")}}</dt> + <dd>获取所有包含指定属性的标签，如果没有属性则获取所有标签。</dd> + <dt>{{WebExtAPIRef("tabs.reload()")}}</dt> + <dd>重在一个标签，可选的可以绕过本地缓存。</dd> + <dt>{{WebExtAPIRef("tabs.remove()")}}</dt> + <dd>关闭一个或多个标签。</dd> + <dt>{{WebExtAPIRef("tabs.sendMessage()")}}</dt> + <dd>向一个指定标签的content script 发送单个消息。</dd> + <dt>{{WebExtAPIRef("tabs.sendRequest()")}} {{deprecated_inline}}</dt> + <dd>向一个指定标签的content script 发送一个单一请求。 <strong>过时</strong>: 请使用 {{WebExtAPIRef("tabs.sendMessage()")}} 替代。</dd> + <dt>{{WebExtAPIRef("tabs.setZoom()")}}</dt> + <dd>缩放指定标签。</dd> + <dt>{{WebExtAPIRef("tabs.setZoomSettings()")}}</dt> + <dd>为一个制定标签设置缩放选项。</dd> + <dt>{{WebExtAPIRef("tabs.update()")}}</dt> + <dd>导航一个标签到新的地址，或是修改其它的属性。</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.onActivated")}}</dt> + <dd>当窗口活动标签改变时触发，注意当该消息触发时，标签地址可能没有被设置。</dd> + <dt>{{WebExtAPIRef("tabs.onActiveChanged")}} {{deprecated_inline}}</dt> + <dd> <strong>已过时:</strong> 请使用 {{WebExtAPIRef("tabs.onActivated")}} 代替。</dd> + <dt>{{WebExtAPIRef("tabs.onAttached")}}</dt> + <dd>当一个标签被附加到一个窗口时触发，因为他可能在窗口间移动。</dd> + <dt>{{WebExtAPIRef("tabs.onCreated")}}</dt> + <dd>当一个标签被创建时触发，注意当该事件触发时可能没有设置地址。</dd> + <dt>{{WebExtAPIRef("tabs.onDetached")}}</dt> + <dd>当一个标签脱离一个窗口时被触发。</dd> + <dt>{{WebExtAPIRef("tabs.onHighlightChanged")}} {{deprecated_inline}}</dt> + <dd><strong>过时:</strong> 请使用 {{WebExtAPIRef("tabs.onHighlighted")}} 代替。</dd> + <dt>{{WebExtAPIRef("tabs.onHighlighted")}}</dt> + <dd>当一个标签被高亮显示或是被选中时触发。</dd> + <dt>{{WebExtAPIRef("tabs.onMoved")}}</dt> + <dd>当一个标签在一个窗口内移动时被触发。</dd> + <dt>{{WebExtAPIRef("tabs.onRemoved")}}</dt> + <dd>当一个标签关闭时被处罚。</dd> + <dt>{{WebExtAPIRef("tabs.onReplaced")}}</dt> + <dd>当一个标签因为预载取代另一个标签时被触发。</dd> + <dt>{{WebExtAPIRef("tabs.onSelectionChanged")}} {{deprecated_inline}}</dt> + <dd> <strong>以过时:</strong> 请使用 {{WebExtAPIRef("tabs.onActivated")}} 代替。</dd> + <dt>{{WebExtAPIRef("tabs.onUpdated")}}</dt> + <dd>当一个标签被更新时触发。</dd> + <dt>{{WebExtAPIRef("tabs.onZoomChange")}}</dt> + <dd>当一个标签被缩放时触发</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.tabs")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<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/tabs"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/insertcss/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/insertcss/index.html new file mode 100644 index 0000000000..5ea7d5205c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/insertcss/index.html @@ -0,0 +1,129 @@ +--- +title: tabs.insertCSS() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS +tags: + - 注入CSS +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS +--- +<div>{{AddonSidebar()}}</div> + +<p>向一个页面注入CSS</p> + +<p>使用该API前你必须拥有目标页面的权限, 可以是 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">主机权限</a>, 或者使用 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">activeTab 权限</a>.</p> + +<p>你只能向符合 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match pattern </a>的网页注入CSS: 其形式必定是 "http", "https", "file", "ftp" 之一. 你不能向任何浏览器内置页面注入CSS， 比如 about:debugging, about:addons, 或者你打开的一个新的空白页。</p> + +<p>当再次调用{{WebExtAPIRef("tabs.removeCSS()")}} 时，已经注入的CSS可能会被清除。</p> + +<p>这是一个返回<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> 的异步函数。</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">var inserting = browser.tabs.insertCSS( + tabId, // optional integer + details // extensionTypes.InjectDetails +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>tabId</code> {{optional_inline}}</dt> + <dd><code>integer，</code> 将要注入css的标签ID。默认为当前窗口的活动标签。</dd> + <dt><code>details</code></dt> + <dd>{{WebExtAPIRef('extensionTypes.InjectDetails')}}. 对注入的描述，包含以下属性：</dd> + <dd> + <dl class="reference-values"> + <dt><code>allFrames</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. 如果为真，该CSS会被注入到该页面的所有框架，如果为假，Css只会注入到最顶层框架，默认为假。</dd> + <dt><code>code</code>{{optional_inline}}</dt> + <dd><code>string</code>. 将要注入的代码。</dd> + <dt><code>file</code>{{optional_inline}}</dt> + <dd><code>string</code>. 包含将要注入代码的文件路径，在Firefox中，相对URLs 决定于当前页面的URL，在Chrome中，决定于扩展的基础URL。为了跨浏览器工作，你应该使用一个从扩展根目录开始的绝对路径，比如 : <code>"/path/to/stylesheet.css"</code>.</dd> + <dt><code>frameId</code>{{optional_inline}}</dt> + <dd><code>integer</code>. CSS应该被注入的框架. 默认为 <code>0</code> (顶层框架).</dd> + <dt><code>matchAboutBlank</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. If <code>true</code>, the code will be injected into embedded "about:blank" and "about:srcdoc" frames if your add-on has access to their parent document. The code cannot be inserted in top-level about: frames. Defaults to <code>false</code>.</dd> + <dt><code>runAt</code>{{optional_inline}}</dt> + <dd>{{WebExtAPIRef('extensionTypes.RunAt')}}. The soonest that the code will be injected into the tab. Defaults to "document_idle".</dd> + </dl> + </dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p> <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> 将会在CSS成功注入时 被填充，如果有任何错误发生，promise将会被注入一个错误消息。</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.insertCSS")}}</p> + +<h2 id="例子">例子</h2> + +<p>下面例子将通过字符串变量形式向当前活动标签注入一段CSS代码</p> + +<pre class="brush: js">var css = "body { border: 20px dotted pink; }"; + +browser.browserAction.onClicked.addListener(() => { + + function onError(error) { + console.log(`Error: ${error}`); + } + + var insertingCSS = browser.tabs.insertCSS({code: css}); + insertingCSS.then(null, onError); +});</pre> + +<p>下面例子将以通过加载文件形式向页面注入CSS。CSS被注入在ID为2的tab中。</p> + +<pre class="brush: js">browser.browserAction.onClicked.addListener(() => { + + function onError(error) { + console.log(`Error: ${error}`); + } + + var insertingCSS = browser.tabs.insertCSS(2, {file: "content-style.css"}); + insertingCSS.then(null, onError); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致谢</strong> + +<p>本页 API 以谷歌 Chromium的 <a href="https://developer.chrome.com/extensions/tabs#method-insertCSS"><code>chrome.tabs</code></a> API为基础. 该篇文档由Chromium 代码 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a>衍变而来.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/onactivated/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/onactivated/index.html new file mode 100644 index 0000000000..0ce8758760 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/onactivated/index.html @@ -0,0 +1,110 @@ +--- +title: tabs.onActivated +slug: Mozilla/Add-ons/WebExtensions/API/tabs/onActivated +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/onActivated +--- +<div>{{AddonSidebar()}}</div> + +<div>当窗体的活动标签变化时触发。请注意事件触发时标签的 URL 可能尚未设置，但是你可以通过监听 {{WebExtAPIRef("tabs.onUpdated")}} 事件在 URL 被设置后得到通知。</div> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">browser.tabs.onActivated.addListener(listener) +browser.tabs.onActivated.removeListener(listener) +browser.tabs.onActivated.hasListener(listener) +</pre> + +<p>此事件有三个方法:</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>向此事件添加一个监听。</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>停止监听此事件。 <code>listener</code> 参数是将要移除的监听。</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>检查 <code>listener</code> 是否在此事件中注册。如果正在监听返回 <code>true</code> ，否则 <code>false。</code></dd> +</dl> + +<h2 id="addListener_语法">addListener 语法</h2> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>callback</code></dt> + <dd> + <p>事件发生时被执行的方法。以下参数会被传递至该方法：</p> + + <dl class="reference-values"> + <dt><code>activeInfo</code></dt> + <dd><a href="#activeInfo"><code>object</code></a>. 被激活标签的ID , 以及它的窗体的 ID 。</dd> + </dl> + </dd> +</dl> + +<h2 id="额外的对象">额外的对象</h2> + +<h3 id="activeInfo">activeInfo</h3> + +<dl class="reference-values"> + <dt><code>tabId</code></dt> + <dd><code>integer</code>. 被激活的标签的ID。</dd> + <dt><code>windowId</code></dt> + <dd><code>integer</code>. 此标签的窗体的ID。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.onActivated")}}</p> + +<h2 id="示例">示例</h2> + +<p>监听并记录标签激活事件:</p> + +<pre class="brush: js">function handleActivated(activeInfo) { + console.log("Tab " + activeInfo.tabId + + " was activated"); +} + +browser.tabs.onActivated.addListener(handleActivated);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#event-onActivated"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/sendmessage/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/sendmessage/index.html new file mode 100644 index 0000000000..8e968a2b1b --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/sendmessage/index.html @@ -0,0 +1,129 @@ +--- +title: tabs.sendMessage() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage +--- +<div>{{AddonSidebar()}}</div> + +<p>从background scripts中发送单个消息 (or other privileged scripts, such as popup scripts or options page scripts) 到任何content scripts that belong to the extension and are running in the specified tab.</p> + +<p>这个消息将被content scripts中 {{WebExtAPIRef("runtime.onMessage")}} 事件的所有监听者收到，然后它们可以选择通过使用 <code>sendResponse</code> 这个方法发送一个response到background scripts。</p> + +<p>This is an asynchronous function that returns a <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">var sending = browser.tabs.sendMessage( + tabId, // integer + message, // any + options // optional object +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>tabId</code></dt> + <dd><code>integer</code>. ID of the tab whose content scripts we want to send a message to.</dd> + <dt><code>message</code></dt> + <dd><code>any</code>. An object that can be serialized to JSON.</dd> + <dt><code>options</code>{{optional_inline}}</dt> + <dd><code>object</code>.</dd> + <dd> + <dl class="reference-values"> + <dt><code>frameId</code>{{optional_inline}}</dt> + <dd><code>integer</code>. Sends the message to a specific frame identified by <code>frameId</code> instead of all frames in the tab. Whether the content script is executed in all frames depends on the <code>all_frames</code> setting in the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/content_scripts"><code>content_scripts</code></a> section of manifest.json.</dd> + </dl> + </dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with the JSON response object sent by the handler of the message in the content script, or with no arguments if the content script did not send a response. If an error occurs while connecting to the specified tab or any other error occurs, the promise will be rejected with an error message. If several frames response to the message, the promise is resolved to one of answers.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.sendMessage")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>Here's an example of a background script that sends a message to the content scripts running in the active tab when the user clicks the browser action. The background script also expects the content script to send a response:</p> + +<pre class="brush: js">// background-script.js +"use strict"; + +function onError(error) { + console.error(`Error: ${error}`); +} + +function sendMessageToTabs(tabs) { + for (let tab of tabs) { + browser.tabs.sendMessage( + tab.id, + {greeting: "Hi from background script"} + ).then(response => { + console.log("Message from the content script:"); + console.log(response.response); + }).catch(onError); + } +} + +browser.browserAction.onClicked.addListener(() => { + browser.tabs.query({ + currentWindow: true, + active: true + }).then(sendMessageToTabs).catch(onError); +});</pre> + +<p>Here's the corresponding content script:</p> + +<pre class="brush: js">// content-script.js +"use strict"; + +browser.runtime.onMessage.addListener(request => { + console.log("Message from the background script:"); + console.log(request.greeting); + return Promise.resolve({response: "Hi from content script"}); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#method-sendMessage"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/tab/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/tab/index.html new file mode 100644 index 0000000000..2fed2e8dd7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/tab/index.html @@ -0,0 +1,117 @@ +--- +title: tabs.Tab +slug: Mozilla/Add-ons/WebExtensions/API/tabs/Tab +tags: + - 扩展 + - 标签 + - 标签页 + - 类型 + - 非标准 + - 页面扩展 +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/Tab +--- +<div>{{AddonSidebar()}}</div> + +<p> <strong><code>tabs.Tab</code></strong> 包含有关标签页的信息 . 这样可以访问有关标签页中的内容，内容有多大，特殊状态或限制有效的信息等等。</p> + +<h2 id="类型">类型</h2> + +<p>这种类型的值是对象。它包含以下属性：</p> + +<dl class="reference-values"> + <dt><code>active</code></dt> + <dd><code>boolean</code>. 该标签页是否在其窗口中处于活动状态。即使标签的窗口当前没有被关注，也可能是true。</dd> + <dt><code>audible</code> {{optional_inline}}</dt> + <dd><code>boolean</code>. 如果标签页没有静音：标签页是否正在发出声音。如果标签页被静音：如果没有静音标签页是否会发出声音。</dd> + <dt><code>autoDiscardable</code> {{optional_inline}}</dt> + <dd><code>boolean</code>. 资源不足时浏览器是否可以自动丢弃该标签页。</dd> + <dt><code>cookieStoreId</code> {{optional_inline}}</dt> + <dd><code>string</code>. 该标签页的Cookie存储. 如果不同的标签可以有不同的cookie存储 (例如, 支持 <a href="https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers">contextual identity</a>), you can pass this as the <code>storeId</code> option into various methods of the {{WebExtAPIRef("cookies")}} API, 设置和获取与此标签页的Cookie存储关联的Cookie。 只有在扩展名具有“cookies”<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权</a></dd> + <dd><code>string</code>. 该标签页的Cookie存储. 如果不同的标签可以有不同的cookie存储 (例如, 支持 <a href="https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers">contextual identity</a>), 你可以将此作为 <code>storeId</code> 选项传递给 {{WebExtAPIRef("cookies")}} API的各种方法, 设置和获取与此标签页的Cookie存储关联的Cookie。 只有在扩展具有“cookies”<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>的情况下才会出现.</dd> + <dt><code>discarded</code> {{optional_inline}}</dt> + <dd><code>boolean</code>. 是否丢弃的标签页。被丢弃的标签页是其内容已经从内存中卸载的标签页，但在标签页条中仍可见。它的内容在下一次被激活时被重新加载。</dd> + <dt><code>favIconUrl</code> {{optional_inline}}</dt> + <dd><code>string</code>. 该标签的图标的网址。 只有在扩展具有“cookies”<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>的情况下才会出现. 如果标签页正在加载中,该值可以为空字符串</dd> + <dt><code>height</code> {{optional_inline}}</dt> + <dd><code>integer</code>. 标签页的像素单位高度。</dd> + <dt><code>highlighted</code></dt> + <dd><code>boolean</code>. 标签页是否突出显示。</dd> + <dt><code>id</code> {{optional_inline}}</dt> + <dd><code>integer</code>. 标签页的ID. 标签 ID在浏览器的会话中是唯一的 。 在浏览器窗口中不包含内容的标签页 (例如, devtools 窗口),标签 ID 也可以设置为 {{WebExtAPIRef('tabs.TAB_ID_NONE')}} 。</dd> + <dt><code>incognito</code></dt> + <dd><code>boolean</code>. 该标签页是否在隐私浏览窗口中。</dd> + <dt><code>index</code></dt> + <dd><code>integer</code>. 窗口中的标签页从零开始的索引。</dd> + <dt><code>isArticle</code></dt> + <dd><code>boolean</code>. 如果标签页可以在<a href="/en-US/Add-ons/WebExtensions/API/tabs/toggleReaderMode"> Reader模式下呈现</a>，则返回true，否则返回false。</dd> + <dt><code>isInReaderMode</code></dt> + <dd><code>boolean</code>. 如果标签页正在<a href="/en-US/Add-ons/WebExtensions/API/tabs/toggleReaderMode"> Reader模式下呈现</a>，则返回true，否则返回false。</dd> + <dt><code>lastAccessed</code></dt> + <dd><code>double</code>. 上次访问该标签页的时间 , 参考 <a class="external external-icon" href="https://en.wikipedia.org/wiki/Unix_time">milliseconds since the epoch</a>.</dd> + <dt><code>mutedInfo</code> {{optional_inline}}</dt> + <dd>{{WebExtAPIRef('tabs.MutedInfo')}}.标签页的当前静音状态以及上次状态更改的原因。</dd> + <dt><code>openerTabId</code> {{optional_inline}}</dt> + <dd><code>integer</code>. 打开此标签页的标签页ID（如果有）。如果开启者标签页仍然存在，该属性才会出现。</dd> + <dt><code>pinned</code></dt> + <dd><code>boolean</code>. 标签页是否被固定</dd> + <dt><code>selected</code> {{deprecated_inline}}</dt> + <dd><code>boolean</code>.标签页是否被选中</dd> + <dt><code>sessionId</code> {{optional_inline}}</dt> + <dd><code>string</code>. 从{{WebExtAPIRef('sessions')}} API 获取的标签页的唯一标识会话ID.</dd> + <dt><code>status</code> {{optional_inline}}</dt> + <dd><code>string</code>.<em>加载</em> 或 <em>完成</em>.</dd> + <dt><code>title</code> {{optional_inline}}</dt> + <dd><code>string</code>. 标签页的标题. 只有当扩展具有 <code>"tabs"</code> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a> 时才会出现.</dd> + <dt><code>url</code> {{optional_inline}}</dt> + <dd><code>string</code>. 该选项卡正在显示的文档的URL。只有当扩展具有 <code>"tabs"</code> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a> 时才会出现.</dd> + <dt><code>width</code> {{optional_inline}}</dt> + <dd><code>integer</code>. 标签页的像素单位宽度。</dd> + <dt><code>windowId</code></dt> + <dd><code>integer</code>. 包含此标签页的窗口ID。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.Tab", 10)}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>感谢</strong> + +<p>此 API 基于 Chromium的 <a href="https://developer.chrome.com/extensions/tabs#type-Tab"><code>chrome.tabs</code></a> API. 本文档来源于Chromium 代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a>.</p> + +<p>Microsoft Edge兼容性数据由Microsoft Corporation提供，并包含在Creative Commons Attribution 3.0美国许可证下。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/查询/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/查询/index.html new file mode 100644 index 0000000000..9afe6e80a8 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/tabs/查询/index.html @@ -0,0 +1,179 @@ +--- +title: 选项卡. 查询 （） +slug: Mozilla/Add-ons/WebExtensions/API/tabs/查询 +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/query +--- +<div>[阿登侧边栏（）]</div> + +<p>获取具有指定属性的所有选项卡，如果未指定任何属性，则获取所有选项卡。</p> + +<p><font>这是返回 的异步函数。</font><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js notranslate">let querying = browser.tabs.query(<var>queryObj</var>) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code><var>queryObj</var></code></dt> + <dd> + <p><code>object</code><font>.函数将仅获取其属性与此处包含的属性匹配的选项卡。</font><code>query()</code></p> + + <p>请参阅 \WebExtAPIRef（"选项卡"）。Tab"）=文档以了解有关这些属性的详细信息。</p> + + <dl class="reference-values"> + <dt><code>active</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否在窗口中处于活动状态。</font></dd> + <dt><code>audible</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.标签是否可听见。</font></dd> + <dt><code>autoDiscardable</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.当资源不足时，浏览器是否可以自动丢弃选项卡。</font></dd> + <dt><code>cookieStoreId</code><font>[optional_inline]</font></dt> + <dd><code>string</code><font>.使用此仅返回其 Cookie 存储 ID 为 的选项卡。此选项仅在加载项具有权限时<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">才可用</a>。</font><code>cookieStoreId</code><code>"cookies"</code></dd> + <dt><code>currentWindow</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否在当前窗口中。</font></dd> + <dt><code>discarded</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.是否丢弃选项卡。丢弃的选项卡是其内容已从内存中卸载，但仍在选项卡条中可见的选项卡。下次激活时，其内容将重新加载。</font></dd> + <dt><code>hidden</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否隐藏。</font></dd> + <dt><code>highlighted</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否突出显示。</font></dd> + <dt><code>index</code><font>[optional_inline]</font></dt> + <dd><code>integer</code><font>.选项卡在其窗口中的位置。</font></dd> + <dt><code>muted</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否为静音。</font></dd> + <dt><code>lastFocusedWindow</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否在上一个焦点窗口中。</font></dd> + <dt><code>pinned</code><font>[optional_inline]</font></dt> + <dd><code>boolean</code><font>.选项卡是否固定。</font></dd> + <dt><code>status</code><font>[optional_inline]</font></dt> + <dd>{WebExtAPIRef（'选项卡。TabStatus '）=。选项卡是否已完成加载。</dd> + <dt><code>title</code><font>[optional_inline]</font></dt> + <dd><code>string</code><font>.将页面标题与图案匹配。</font></dd> + <dt><code>url</code><font>[optional_inline]</font></dt> + <dd><code><code>string</code></code><font>或。将选项卡与一个或多个匹配<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">模式匹配</a>。请注意，片段标识符不匹配。</font><code><code>array</code> of <code><code>string</code></code></code></dd> + <dt><code>windowId</code><font>{{optional_inline}}</font></dt> + <dd><code>integer</code><font>. The of the parent window, or {{WebExtAPIRef('windows.WINDOW_ID_CURRENT')}} for the current window.</font><code>id</code></dd> + <dt><code>windowType</code><font>{{optional_inline}}</font></dt> + <dd>{{WebExtAPIRef('tabs.WindowType')}}. The type of window the tabs are in.</dd> + </dl> + </dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p><font>A that will be fulfilled with an of objects, containing information about each matching tab.</font><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code><code>array</code><code>{{WebExtAPIRef('tabs.Tab')}}</code></p> + +<p>If any error occurs, the promise will be rejected with an error message.</p> + +<h2 id="Examples">Examples</h2> + +<p>Get all tabs:</p> + +<pre class="brush: js notranslate">function logTabs(tabs) { + for (let tab of tabs) { + // tab.url requires the `tabs` permission + console.log(tab.url); + } +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +let querying = browser.tabs.query({}); +querying.then(logTabs, onError);</pre> + +<p>Get all tabs in the current window:</p> + +<pre class="brush: js notranslate">function logTabs(tabs) { + for (let tab of tabs) { + // tab.url requires the `tabs` permission + console.log(tab.url); + } +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +let querying = browser.tabs.query({currentWindow: true}); +querying.then(logTabs, onError);</pre> + +<p>Get the active tab in the current window:</p> + +<pre class="brush: js notranslate">function logTabs(tabs) { + // tabs[0].url requires the `tabs` permission + console.log(tabs[0].url); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +let querying = browser.tabs.query({currentWindow: true, active: true}); +querying.then(logTabs, onError);</pre> + +<p><font>Get tabs for all HTTP and HTTPS URLs under or any of its subdomains:</font><code>"mozilla.org"</code></p> + +<pre class="brush: js notranslate">function logTabs(tabs) { + for (let tab of tabs) { + // tab.url requires the `tabs` permission + console.log(tab.url); + } +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +let querying = browser.tabs.query({url: "*://*.mozilla.org/*"}); +querying.then(logTabs, onError);</pre> + +<p>{{WebExtExamples}}</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("webextensions.api.tabs.query")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs#method-query"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/index.html new file mode 100644 index 0000000000..46641d4f60 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/index.html @@ -0,0 +1,85 @@ +--- +title: BrowserSetting +slug: Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting +tags: + - API + - Add-ons + - BrowserSetting + - Extensions + - NeedsTranslation + - Reference + - TopicStub + - Type + - Types + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting +--- +<div>{{AddonSidebar()}}</div> + +<p>A <code>BrowserSetting</code> is an object representing a browser setting.</p> + +<p>It provides methods to set and get the setting's underlying value, to clear any change you've made to it, and to listen for changes to its value.</p> + +<p>Note that while this object is based on the <a href="https://developer.chrome.com/extensions/types#type-ChromeSetting">ChromeSetting</a> type, this object does not distinguish between setting the value in normal browsing windows and in private browsing windows. This means that all parts of the API relating to private browsing (such as the <code>scope</code> option to <code>ChromeSetting.set()</code>) are not implemented.</p> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{WebExtAPIRef("types.BrowserSetting.get()")}}</dt> + <dd>Get the current value of the setting, and an enumeration representing how the setting is currently controlled.</dd> + <dt>{{WebExtAPIRef("types.BrowserSetting.set()")}}</dt> + <dd>Set the setting to a new value.</dd> + <dt>{{WebExtAPIRef("types.BrowserSetting.clear()")}}</dt> + <dd>Clear any change made to the setting by this extension.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("types.BrowserSetting.onChange")}}</dt> + <dd>Fired when the setting's value changes.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("webextensions.api.types.BrowserSetting")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/types"><code>chrome.types</code></a> API.</p> +</div> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.html new file mode 100644 index 0000000000..fc85b194bb --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.html @@ -0,0 +1,118 @@ +--- +title: set() +slug: Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting/set +translation_of: Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting/set +--- +<div>{{AddonSidebar()}}</div> + +<p>Use <code>BrowserSetting.set()</code> to change the browser setting to a new value.</p> + +<p>There are some rules that can restrict when extensions are able to change settings:</p> + +<ul> + <li>some settings are locked, so they can't be changed by extensions at all</li> + <li>if multiple extensions try to modify the same setting, then extensions are given a precedence ordering based on when they were installed. More-recently installed extensions have precedence over less-recently installed extension.</li> +</ul> + +<p>This means that if extension X tries to change a setting:</p> + +<ol> + <li>If the setting is locked, then the setting is not changed. However, X's change is remembered, and it is stored in a queue, ordered by X's precedence relative to any other extensions that tried to change the setting. If the setting becomes unlocked later on, the first extension in the queue gets to change the setting.</li> + <li>Otherwise, if no other extension has already changed the setting, then X succeeds in changing the setting, and is then said to "control" the setting.</li> + <li>Otherwise, if a lower-precedence extension Y has already changed the setting, then X succeeds in changing the setting, and now controls the setting. However, Y's change is remembered, and is stored in a queue in precedence order. If X subsequently clears its value, or if X is disabled or uninstalled, the first extension in the queue gets to make its change to the setting.</li> + <li>Otherwise, if a higher-precedence extension Z has already changed the setting, then X does not succeed in changing the setting, but its change is queued. If Z subsequently clears its value, or if Z is disabled or uninstalled, the first extension in the queue gets to make its change to the setting.</li> +</ol> + +<p>An extension can find out which of these scenarios applies by examining the "<code>levelOfControl</code>" property returned from a call to <code><a href="/en-US/Add-ons/WebExtensions/API/privacy/BrowserSetting/get">BrowserSetting.get()</a></code>.</p> + +<p>The <code><a href="/en-US/Add-ons/WebExtensions/API/privacy/BrowserSetting/set">BrowserSetting.set()</a></code> method returns a Promise that resolves to a boolean: if an attempt to change a setting actually results in the setting being changed (scenarios 2 and 3 above) the boolean is <code>true</code>: otherwise it is <code>false</code>.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js notranslate">var setting = setting.set( + details // object +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>details</code></dt> + <dd>An object that must contain the following property:</dd> + <dd> + <dl class="reference-values"> + <dt><code>value</code></dt> + <dd><code>any</code>. The value you want to change the setting to. Its type depends on the particular setting.</dd> + </dl> + </dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with a <code>boolean</code>: <code>true</code> if the setting was modified, <code>false</code> otherwise (for example, because the extension did not control the setting).</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>See {{WebExtAPIRef("types.BrowserSetting")}}.</p> + +<h2 id="Example">Example</h2> + +<p>Modify the <code>hyperlinkAuditingEnabled</code> setting (this requires the "privacy" permission):</p> + +<pre class="brush: js notranslate">function onSet(result) { + if (result) { + console.log("Value was updated"); + } else { + console.log("Value was not updated"); + } +} + +browser.browserAction.onClicked.addListener(() => { + + var setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({ + value: false + }); + setting.then(onSet); + +}); +</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/types"><code>chrome.types</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/types/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/types/index.html new file mode 100644 index 0000000000..2e35b1d6e0 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/types/index.html @@ -0,0 +1,66 @@ +--- +title: types +slug: Mozilla/Add-ons/WebExtensions/API/types +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Reference + - TopicStub + - Types + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/types +--- +<div>{{AddonSidebar}}</div> + +<p>Defines the <code>BrowserSetting</code> type, which is used to represent a browser setting.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("types.BrowserSetting")}}</dt> + <dd>Represents a browser setting.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<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/types"><code>chrome.types</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/index.html new file mode 100644 index 0000000000..6bb5b935e5 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/index.html @@ -0,0 +1,155 @@ +--- +title: webNavigation +slug: Mozilla/Add-ons/WebExtensions/API/webNavigation +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - webNavigation +translation_of: Mozilla/Add-ons/WebExtensions/API/webNavigation +--- +<div>{{AddonSidebar}}</div> + +<p>Add event listeners for the various stages of a navigation. A navigation consists of a frame in the browser transitioning from one URL to another, usually (but not always) in response to a user action like clicking a link or entering a URL in the location bar.</p> + +<p>Compared with the {{WebExtAPIRef("webRequest")}} API: navigations usually result in the browser making web requests, but the webRequest API is concerned with the lower-level view from the HTTP layer, while the webNavigation API is more concerned with the view from the browser UI itself.</p> + +<p>Each event corresponds to a particular stage in the navigation. The sequence of events is like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13374/we-flow.png" style="display: block; height: 562px; margin-left: auto; margin-right: auto; width: 745px;"></p> + +<ul> + <li>The primary flow is: + <ul> + <li><code>{{WebExtAPIRef("webNavigation.onBeforeNavigate", "onBeforeNavigate")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onCommitted", "onCommitted")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onDOMContentLoaded", "onDOMContentLoaded")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onCompleted", "onCompleted")}}</code>.</li> + </ul> + </li> + <li>Additionally: + <ul> + <li><code>{{WebExtAPIRef("webNavigation.onCreatedNavigationTarget", "onCreatedNavigationTarget")}}</code> is fired before <code>onBeforeNavigate</code> if the browser needed to create a new tab or window for the navigation (for example, because the user opened a link in a new tab).</li> + <li>{{WebExtAPIRef("webNavigation.onHistoryStateUpdated", "onHistoryStateUpdated")}} is fired if a page uses the <a href="http://diveintohtml5.info/history.html">history API</a> to update the URL displayed in the browser's location bar.</li> + <li>{{WebExtAPIRef("webNavigation.onReferenceFragmentUpdated", "onReferenceFragmentUpdated")}} is fired if the <a href="https://en.wikipedia.org/wiki/Fragment_identifier">fragment identifier</a> for a page is changed.</li> + <li>{{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} can be fired at any point.</li> + </ul> + </li> +</ul> + +<p>Each navigation is a URL transition in a particular browser frame. The browser frame is identified by a tab ID and a frame ID. The frame may be the top-level browsing context in the tab, or may be a nested browsing context implemented as an <a href="/en-US/docs/Web/HTML/Element/iframe">iframe</a>.</p> + +<p>Each event's <code>addListener()</code> call accepts an optional filter parameter. The filter will specify one or more URL patterns, and the event will then only be fired for navigations in which the target URL matches one of the patterns.</p> + +<p>The <code>onCommitted</code> event listener is passed two additional properties: a {{WebExtAPIRef("webNavigation.TransitionType","TransitionType")}} indicating the cause of the navigation (for example, because the user clicked a link, or because the user selected a bookmark), and a {{WebExtAPIRef("webNavigation.TransitionQualifier","TransitionQualifier")}} providing further information about the navigation.</p> + +<p>To use this API you need to have the "webNavigation" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.TransitionType")}}</dt> + <dd>Cause of the navigation: for example, the user clicked a link, or typed an address, or clicked a bookmark.</dd> + <dt>{{WebExtAPIRef("webNavigation.TransitionQualifier")}}</dt> + <dd> + <div>Extra information about a transition.</div> + </dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.getFrame()")}}</dt> + <dd>Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe">iframe</a>, and is uniquely identified by a tab ID and a frame ID.</dd> + <dt>{{WebExtAPIRef("webNavigation.getAllFrames()")}}</dt> + <dd> + <p>Given a tab ID, retrieves information about all the frames it contains.</p> + </dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.onBeforeNavigate")}}</dt> + <dd> + <p>Fired when the browser is about to start a navigation event.</p> + </dd> + <dt>{{WebExtAPIRef("webNavigation.onCommitted")}}</dt> + <dd>Fired when a navigation is committed. At least part of the new document has been received from the server and the browser has decided to switch to the new document.</dd> + <dt>{{WebExtAPIRef("webNavigation.onDOMContentLoaded")}}</dt> + <dd>Fired when the <a href="https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> event is fired in the page.</dd> + <dt>{{WebExtAPIRef("webNavigation.onCompleted")}}</dt> + <dd>Fired when a document, including the resources it refers to, is completely loaded and initialized. This is equivalent to the DOM <code><a href="https://developer.mozilla.org/en-US/docs/Web/Events/load">load</a></code> event.</dd> + <dt>{{WebExtAPIRef("webNavigation.onErrorOccurred")}}</dt> + <dd>Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.</dd> + <dt>{{WebExtAPIRef("webNavigation.onCreatedNavigationTarget")}}</dt> + <dd>Fired when a new window, or a new tab in an existing window, is created to host a navigation: for example, if the user opens a link in a new tab.</dd> + <dt>{{WebExtAPIRef("webNavigation.onReferenceFragmentUpdated")}}</dt> + <dd>Fired if the <a class="external-icon external" href="https://en.wikipedia.org/wiki/Fragment_identifier">fragment identifier</a> for a page is changed.</dd> + <dt>{{WebExtAPIRef("webNavigation.onTabReplaced")}}</dt> + <dd> + <p>Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.</p> + </dd> + <dt>{{WebExtAPIRef("webNavigation.onHistoryStateUpdated")}}</dt> + <dd>Fired when the page used the <a class="external external-icon" href="http://diveintohtml5.info/history.html">history API</a> to update the URL displayed in the browser's location bar.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.webNavigation")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<h3 id="Edge_incompatibilities">Edge incompatibilities</h3> + +<p>Promises are not supported in Edge. Use callbacks instead.</p> + +<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/webNavigation"><code>chrome.webNavigation</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/web_navigation.json"><code>web_navigation.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.html new file mode 100644 index 0000000000..41a103dc8c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.html @@ -0,0 +1,137 @@ +--- +title: webNavigation.onDOMContentLoaded +slug: Mozilla/Add-ons/WebExtensions/API/webNavigation/onDOMContentLoaded +tags: + - API + - onDOMContentLoaded + - webNavigation + - webNavigation.onDOMContentLoaded +translation_of: Mozilla/Add-ons/WebExtensions/API/webNavigation/onDOMContentLoaded +--- +<div>{{AddonSidebar()}}</div> + +<p>在页面中触发<a href="/en-US/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> 事件时触发。此时，文档被加载和解析，并且DOM被完全构造，但链接的资源（例如图像，样式表和子框架（subframes））可能尚未被加载。</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">browser.webNavigation.onDOMContentLoaded.addListener( + listener, // function + filter // optional object +) +browser.webNavigation.onDOMContentLoaded.removeListener(listener) +browser.webNavigation.onDOMContentLoaded.hasListener(listener) +</pre> + +<p>事件有三个方法:</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>为此事件添加监听方法.</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>停止监听此事件. <code>listener</code> 参数为需要移出的监听方法.</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>检测是否有 <code>listener</code> 被注册在事件上. 如果有返回 <code>true</code> , 否则返回<code>false</code> .</dd> +</dl> + +<h2 id="addListener_syntax">addListener syntax</h2> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>callback</code></dt> + <dd> + <p>为当此事件发生是需要被调用的函数. 该函数将传递以下参数:</p> + + <dl class="reference-values"> + <dt><code>details</code></dt> + <dd><a href="#details"><code>object</code></a>. 有关导航（navigation）事件的详细信息.</dd> + </dl> + </dd> + <dt><code>filter</code>{{optional_inline}}</dt> + <dd> + <p><code>object</code>. 包含单个属性 <code>url</code> 的对象, 这是一个 {{WebExtAPIRef("events.UrlFilter")}} <font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">数组</span></font>对象. 如果包含此参数，则该事件将仅触发转换为与数组中至少一个<code>UrlFilter</code>匹配的URL。 在数组中。如果您省略此参数，则该事件将触发所有转换。</p> + </dd> +</dl> + +<h2 id="Additional_objects">Additional objects</h2> + +<h3 id="details">details</h3> + +<dl class="reference-values"> + <dt><code>tabId</code></dt> + <dd><code>integer</code>. The ID of the tab in which the navigation has occurred.</dd> + <dt><code>url</code></dt> + <dd><code>string</code>. The URL to which the given frame has navigated.</dd> + <dt><code>processId</code></dt> + <dd><code>integer</code>. The ID of the process in which this tab is being rendered.</dd> + <dt><code>frameId</code></dt> + <dd><code>integer</code>. Frame in which the navigation is occurring. 0 indicates that navigation happens in the tab's top-level browsing context, not in a nested <a href="/en-US/docs/Web/HTML/Element/iframe">iframe</a>. A positive value indicates that navigation happens in a nested iframe. Frame IDs are unique for a given tab and process.</dd> + <dt><code>timeStamp</code></dt> + <dd><code>number</code>. The time at which <code>DOMContentLoaded</code> was fired, in <a href="https://en.wikipedia.org/wiki/Unix_time">milliseconds since the epoch</a>.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.webNavigation.onDOMContentLoaded")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>Logs the target URLs for <code>onDOMContentLoaded</code>, if the target URL's hostname contains "example.com" or starts with "developer".</p> + +<pre class="brush: js">var filter = { + url: + [ + {hostContains: "example.com"}, + {hostPrefix: "developer"} + ] +} + +function logOnDOMContentLoaded(details) { + console.log("onDOMContentLoaded: " + details.url); +} + +browser.webNavigation.<code>onDOMContentLoaded</code>.addListener(logOnDOMContentLoaded, filter); + +</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/webNavigation#event-onBeforeNavigate"><code>chrome.webNavigation</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/web_navigation.json"><code>web_navigation.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/index.html new file mode 100644 index 0000000000..03b5823878 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/index.html @@ -0,0 +1,186 @@ +--- +title: webRequest +slug: Mozilla/Add-ons/WebExtensions/API/webRequest +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - webRequest +translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest +--- +<div>{{AddonSidebar}}</div> + +<div>为发出的HTTP请求在不同阶段添加事件监听器。事件监听器可以接收到请求的详细信息，也可以修改或取消请求。</div> + +<h2 id="概况">概况</h2> + +<p>每个事件都会在请求的特定阶段触发。事件的顺序大概是这样的：</p> + +<p>在请求过程中的任意时间，{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} 可以被触发。虽然有时候触发的事件顺序不同，举个例子，在火狐浏览器中的HSTS过程，在onBeforeRequest事件执行后，onBeforeRedirect 事件会被立即触发。</p> + +<p>所有的事件，接受<code>onErrorOccurred事件</code>, <code>addListener()</code>有三个参数 :</p> + +<ul> + <li>监听本身</li> + <li>一个{{WebExtAPIRef("webRequest.RequestFilter", "filter")}} 对象, 所以你仅可以被特定请求或特定的资源类型提醒</li> + <li>一个可选的<code>extraInfoSpec</code>对象. 你可以使用这个对象添加特定的事件命令</li> +</ul> + +<p>这个监听函数接收一个<code>details</code>对象，这个对象包含这个请求的信息。他包含一个请求ID, 在插件中这个ID可以关联唯一个请求事件. 这个ID是浏览器会话和插件上下文中唯一的。他始终在同一个请求中，贯穿着转发和授权等事件中。</p> + +<p>在一个给定的主机上使用webRequest API, 你必须有这个主机的相关权限，包括"webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> 和 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission</a>. 为了使用 "blocking" 特性，你必须有 "webRequestBlocking" API 权限。</p> + +<p>这个webRequest API不能让你进入一些安全敏感的请求，比如<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1279371">update checks and OCSP checks</a>.</p> + +<h3 id="Modifying_requests">Modifying requests</h3> + +<p>在下边这些事件中，你可以修改请求. 比如一些特别的操作:</p> + +<ul> + <li>取消请求: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li> + <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</li> + <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li> + </ul> + </li> + <li>重定向请求: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li> + <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li> + </ul> + </li> + <li>修改请求头: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</li> + </ul> + </li> + <li>修改响应头: + <ul> + <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li> + </ul> + </li> + <li>加入认证功能: + <ul> + <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li> + </ul> + </li> +</ul> + +<p>为了完成这些操作，你需要在<code>extraInfoSpec</code>参数中添加"blocking"的值到事件的<code>addListener()</code>。这将使得监听器变成同步执行。在监听器中，你可以返回一个表明需要作修改的{{WebExtAPIRef("webRequest.BlockingResponse", "BlockingResponse")}}对象：比如说，你想要发送的修改后的请求头。</p> + +<p>从Firefox 52开始，监听器会返回一个<code>resolve(BlockingResponse)</code> 的 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>，而不是直接返回一个<code>BlockingResponse</code>。这使得监听器可以异步地处理请求。</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.ResourceType")}}</dt> + <dd>Represents a particular kind of resource fetched in a web request.</dd> + <dt>{{WebExtAPIRef("webRequest.RequestFilter")}}</dt> + <dd>An object describing filters to apply to webRequest events.</dd> + <dt>{{WebExtAPIRef("webRequest.HttpHeaders")}}</dt> + <dd>An array of HTTP headers. Each header is represented as an object with two properties: <code>name</code> and either <code>value</code> or <code>binaryValue</code>.</dd> + <dt>{{WebExtAPIRef("webRequest.BlockingResponse")}}</dt> + <dd> + <p>An object of this type is returned by event listeners that have set <code>"blocking"</code> in their <code>extraInfoSpec</code> argument. By setting particular properties in <code>BlockingResponse</code>, the listener can modify network requests.</p> + </dd> + <dt>{{WebExtAPIRef("webRequest.UploadData")}}</dt> + <dd>Contains data uploaded in a URL request.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES")}}</dt> + <dd>The maximum number of times that <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/WebRequest/handlerBehaviorChanged" title="Suppose an add-on's job is to block web requests against a pattern, and the following scenario happens:"><code>handlerBehaviorChanged()</code></a></code> can be called in a 10 minute period.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.handlerBehaviorChanged()")}}</dt> + <dd>This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.onBeforeRequest")}}</dt> + <dd>Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.</dd> + <dt>{{WebExtAPIRef("webRequest.onBeforeSendHeaders")}}</dt> + <dd>Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.</dd> + <dt>{{WebExtAPIRef("webRequest.onSendHeaders")}}</dt> + <dd>Fired just before sending headers. If your add-on or some other add-on modified headers in <code>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</code>, you'll see the modified version here.</dd> + <dt>{{WebExtAPIRef("webRequest.onHeadersReceived")}}</dt> + <dd>Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.</dd> + <dt>{{WebExtAPIRef("webRequest.onAuthRequired")}}</dt> + <dd>Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.</dd> + <dt>{{WebExtAPIRef("webRequest.onResponseStarted")}}</dt> + <dd>Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.</dd> + <dt>{{WebExtAPIRef("webRequest.onBeforeRedirect")}}</dt> + <dd>Fired when a server-initiated redirect is about to occur.</dd> + <dt>{{WebExtAPIRef("webRequest.onCompleted")}}</dt> + <dd>Fired when a request is completed.</dd> + <dt>{{WebExtAPIRef("webRequest.onErrorOccurred")}}</dt> + <dd>Fired when an error occurs.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.webRequest")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<h3 id="Edge_incompatibilities">Edge incompatibilities</h3> + +<p>Promises are not supported in Edge. Use callbacks instead.</p> + +<p>{{Compat("webextensions.api.webRequest")}} {{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/webRequest"><code>chrome.webRequest</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.html new file mode 100644 index 0000000000..6ac538c374 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.html @@ -0,0 +1,71 @@ +--- +title: webRequest.RequestFilter +slug: Mozilla/Add-ons/WebExtensions/API/webRequest/RequestFilter +tags: + - webRequest +translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest/RequestFilter +--- +<div>{{AddonSidebar()}}</div> + +<p>webRequest事件参数</p> + +<h2 id="Type">Type</h2> + +<p>该参数值是一个对象，包括以下属性：</p> + +<dl class="reference-values"> + <dt><code>urls</code></dt> + <dd><font face="Consolas, Liberation Mono, Courier, monospace">字符串数组类型，数组内的每个字符串为<a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Match_patterns">模式匹配</a>格式。当请求地址符合给定模式时，事件监听器才会响应。需注意的是，仅支持http和HTTPS协议的参数地址，其他协议即使与该给定模式匹配也不会响应。</font></dd> + <dt><code>types</code>{{optional_inline}}</dt> + <dd>webRequest.ResourceType类型的数组，表示资源类型列表。例如：stylesheets、images、scripts。事件监听器仅响应出现在该指定列表的资源类型。</dd> + <dt><code>tabId</code>{{optional_inline}}</dt> + <dd><font face="Consolas, Liberation Mono, Courier, monospace">数值类型，与</font>{{WebExtAPIRef("tabs.Tab", "tab")}}关联，事件监听器仅响应指定了该tabId的请求。</dd> + <dt><code>windowId</code>{{optional_inline}}</dt> + <dd><font face="Consolas, Liberation Mono, Courier, monospace">数值类型，与</font>{{WebExtAPIRef("windows.Window", "window")}}关联，事件监听器仅响应指定了该<code>windowId</code>的请求。</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.webRequest.RequestFilter")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>告知信息</strong> + +<p>该API基于Chromium的 <a href="https://developer.chrome.com/extensions/webRequest#type-RequestFilter"><code>chrome.webRequest</code></a> API. 该文档来源于Chromium代码中的 <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> 。</p> + +<p>Microsoft Edge兼容性数据由Microsoft Corporation提供，并包含在Creative Commons Attribution 3.0 United States License下。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/windows/create/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/create/index.html new file mode 100644 index 0000000000..7673eadc83 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/create/index.html @@ -0,0 +1,169 @@ +--- +title: windows.create() +slug: Mozilla/Add-ons/WebExtensions/API/windows/create +translation_of: Mozilla/Add-ons/WebExtensions/API/windows/create +--- +<div>{{AddonSidebar()}}</div> + +<p>创建一个新的窗口.</p> + +<p>当你创建一个窗口时，你可以:</p> + +<ul> + <li>加载一个或多个新的标签到该窗口中.</li> + <li>将一个现有窗口的.标签移动到新的窗口中</li> + <li>设置窗口的大小和位置</li> + <li>创建一个面板样式的窗口，它没有浏览器的默认样式（地址栏，工具栏等）</li> + <li>设置窗口的多种属性, 像是获得焦点或是为隐私窗口.</li> +</ul> + +<p>这是一个异步的方法返回一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">var creating = browser.windows.create( + createData // optional object +) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>createData</code>{{optional_inline}}</dt> + <dd><code>object</code>.</dd> + <dd> + <dl class="reference-values"> + <dt><code>url</code>{{optional_inline}}</dt> + <dd><code><code>字符串或字符串数组</code></code>. 一个URL或都URL数组要在该窗口中打开成标签页的. 完整的需要包括scheme (像. <code>http://www.google.com</code>, not <code>www.google.com</code>). 相对路径将相对于该拓展中的当前页. 默认为打开新标签页.</dd> + <dt><code>tabId</code>{{optional_inline}}</dt> + <dd><code>integer</code>. 如果设置了该值，将该tab从一个现有的窗口中移到新窗口中.</dd> + <dt><code>left</code>{{optional_inline}}</dt> + <dd><code>integer</code>. 窗口左边到屏幕左边缘的距离.如果没有设定，新窗口将按上一个焦点窗口定位水平位置. 对于panel样式窗口，该值不起作用.</dd> + <dt><code>top</code>{{optional_inline}}</dt> + <dd>窗口顶部到屏幕的顶部距离.如果没有设定，新窗口将按上一个焦点窗口定位垂直位置. 对于panel样式窗口，该值不起作用.</dd> + <dt><code>width</code>{{optional_inline}}</dt> + <dd><code>integer</code>. 新窗口的宽度, 包含框架. 未设定则使用默认宽度。.</dd> + <dt><code>height</code>{{optional_inline}}</dt> + <dd><code>integer</code>. 新窗口的高度, 包含框架. 未设定则使用默认高度。.</dd> + <dt><code>focused</code>{{optional_inline}}</dt> + <dd><code>boolean</code>.如果 为<code>true</code>, 新窗口将获取焦点. 否则新窗口当在后台打开并且当前焦点窗口继续保持焦点.。.默认为true</dd> + <dt><code>incognito</code>{{optional_inline}}</dt> + <dd><code>boolean</code>. 是否打开为一个隐私窗口. <code>如果设定为隐私窗口并且引入了tabId</code>, 则tabId对应的标签必须是一个隐私标签— 即不能把一个不是隐私标签的标签页移动到隐私窗口中。</dd> + <dt><code>type</code>{{optional_inline}}</dt> + <dd>一{{WebExtAPIRef('windows.CreateType')}} 值，表示创建窗口的类型. <code>panel</code> 或者<code>popup</code> 样式将打开一个没有默认浏览器样式的窗口 (地址栏，工具栏等）。</dd> + <dt><code>state</code>{{optional_inline}}</dt> + <dd>一个 {{WebExtAPIRef('windows.WindowState')}} 值， 窗口的祲状态。 最小化、最大化、全屏状态不能与<code>left</code>, <code>top</code>, <code>width</code>, or <code>height</code>属性一起使用。</dd> + </dl> + </dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> 其中传入一个包含新窗口细节的 {{WebExtAPIRef('windows.Window')}} 对象。 这个{{WebExtAPIRef('windows.Window')}} 有自己的tabs属性集 ,而不像 {{WebExtAPIRef("windows.get()")}}返回的窗口对象和相似的API, 如果传递了populate项其仅仅包含tabs. 如果发生了错误 promise will be rejected with an error message.</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">这个页面中的兼容性表是从结构化数据生成的。如果你想为数据，请参照 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 并且给我们发请求</p> + +<p>{{Compat("webextensions.api.windows.create", 10)}}</p> + +<h2 id="示例">示例</h2> + +<p>打开一个包含两个标签的窗口</p> + +<pre class="brush: js">function onCreated(windowInfo) { + console.log(`Created window: ${windowInfo.id}`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.browserAction.onClicked.addListener((tab) => { + var creating = browser.windows.create({ + url: ["https://developer.mozilla.org", + "https://addons.mozilla.org"] + }); + creating.then(onCreated, onError); +});</pre> + +<p>当用户点击一个browser action打开一个窗口，并且将当前活跃的标签移动其中</p> + +<pre class="brush: js">function onCreated(windowInfo) { + console.log(`Created window: ${windowInfo.id}`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.browserAction.onClicked.addListener((tab) => { + var creating = browser.windows.create({ + tabId: tab.id + }); + creating.then(onCreated, onError); +});</pre> + +<p>打开一个小面板样式的窗口，并且加载一个本地包中的文件到其中</p> + +<pre class="brush: js">function onCreated(windowInfo) { + console.log(`Created window: ${windowInfo.id}`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.browserAction.onClicked.addListener((tab) => { + + var popupURL = browser.extension.getURL("popup/popup.html"); + + var creating = browser.windows.create({ + url: popupURL, + type: "popup", + height: 200, + width: 200 + }); + creating.then(onCreated, onError); + +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/windows#method-create"><code>chrome.windows</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code>windows.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/windows/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/index.html new file mode 100644 index 0000000000..b923176e30 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/index.html @@ -0,0 +1,116 @@ +--- +title: windows +slug: Mozilla/Add-ons/WebExtensions/API/windows +translation_of: Mozilla/Add-ons/WebExtensions/API/windows +--- +<div>{{AddonSidebar}}</div> + +<p>与浏览器窗口互动。您可以使用此 API 获取有关已打开窗口的信息，以及打开、修改和关闭窗口。您也可以监听窗口的打开、关闭和其激活事件。</p> + +<h2 id="类型">类型</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.WindowType")}}</dt> + <dd>浏览器窗口的类型。</dd> + <dt>{{WebExtAPIRef("windows.WindowState")}}</dt> + <dd>浏览器窗口的状态。</dd> + <dt>{{WebExtAPIRef("windows.Window")}}</dt> + <dd>有关一个浏览器窗口的信息。</dd> + <dt>{{WebExtAPIRef("windows.CreateType")}}</dt> + <dd>指定要创建的浏览器窗口的类型。</dd> +</dl> + +<h2 id="属性">属性</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.WINDOW_ID_NONE")}}</dt> + <dd><code>windowId</code> 值表示不存在浏览器窗口。</dd> + <dt>{{WebExtAPIRef("windows.WINDOW_ID_CURRENT")}}</dt> + <dd><code>windowId</code> 值表示当前窗口。</dd> +</dl> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.get()")}}</dt> + <dd>指定其 ID，获取一个窗口的细节。</dd> + <dt>{{WebExtAPIRef("windows.getCurrent()")}}</dt> + <dd>获取当前窗口。</dd> + <dt>{{WebExtAPIRef("windows.getLastFocused()")}}</dt> + <dd>获取最近获得焦点的窗口，通常它是“顶部”的窗口。</dd> + <dt>{{WebExtAPIRef("windows.getAll()")}}</dt> + <dd>获取所有窗口。</dd> + <dt>{{WebExtAPIRef("windows.create()")}}</dt> + <dd> + <p>创建新窗口。</p> + </dd> + <dt>{{WebExtAPIRef("windows.update()")}}</dt> + <dd>更新一个窗口的属性。使用此项对移动、调整大小、聚焦/取消聚焦等。</dd> + <dt>{{WebExtAPIRef("windows.remove()")}}</dt> + <dd>关闭一个窗口及其所有标签页。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.onCreated")}}</dt> + <dd>一个窗口创建时触发。</dd> + <dt>{{WebExtAPIRef("windows.onRemoved")}}</dt> + <dd>一个窗口关闭时触发。</dd> + <dt>{{WebExtAPIRef("windows.onFocusChanged")}}</dt> + <dd>当前有焦点的窗口改变时触发。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.windows")}}</p> + +<div class="hidden note"> +<p>Chrome 的不兼容 部分列在 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>，为采用 <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> 宏。</p> + +<p>如果您需要更新此内容，编辑 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>，然后按住Shift并刷新此页面以查看您的变更。</p> +</div> + +<h3 id="Edge_的不兼容">Edge 的不兼容</h3> + +<p>Edge 中不支持 Promises。需使用回调。</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>声明</strong> + +<p>此 API 基于 Chromium 的 <a href="https://developer.chrome.com/extensions/windows"><code>chrome.windows</code></a> API。此文档基于 Chromium 代码中的<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code> windows.json</code></a>。</p> + +<p>Microsoft Edge 兼容性数据由微软公司提供，并包含在创作共用 署名 3.0美国许可证下。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowstate/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowstate/index.html new file mode 100644 index 0000000000..605f2cf071 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowstate/index.html @@ -0,0 +1,66 @@ +--- +title: windows.WindowState +slug: Mozilla/Add-ons/WebExtensions/API/windows/WindowState +translation_of: Mozilla/Add-ons/WebExtensions/API/windows/WindowState +--- +<div>{{AddonSidebar()}}</div> + +<p>浏览器窗口的状态。</p> + +<h2 id="类型">类型</h2> + +<p>类型的值是字符串类型。 可能的值如下:</p> + +<ul> + <li><code>"normal"</code></li> + <li><code>"minimized"</code></li> + <li><code>"maximized"</code></li> + <li><code>"fullscreen"</code></li> + <li><code>"docked"</code></li> +</ul> + +<h2 id="浏览器适配">浏览器适配</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.windows.WindowState")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致谢</strong> + +<p>此API基于谷歌浏览器 <a href="https://developer.chrome.com/extensions/windows#type-WindowState"><code>chrome.windows</code></a> API。此文档源于谷歌源码 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code>windows.json</code></a> .</p> + +<p>微软Edge浏览器兼容性数据由微软公司提供，并包含在美国Creative Commons Attribution 3.0许可证下。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowtype/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowtype/index.html new file mode 100644 index 0000000000..6f9e5572b2 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/windows/windowtype/index.html @@ -0,0 +1,65 @@ +--- +title: windows.WindowType +slug: Mozilla/Add-ons/WebExtensions/API/windows/WindowType +translation_of: Mozilla/Add-ons/WebExtensions/API/windows/WindowType +--- +<div>{{AddonSidebar()}}</div> + +<p>浏览器窗口的类型。</p> + +<h2 id="Type">Type</h2> + +<p>类型的值是字符串类型。 可能的值如下:</p> + +<ul> + <li><code>"normal"</code></li> + <li><code>"popup"</code></li> + <li><code>"panel"</code></li> + <li><code>"devtools"</code></li> +</ul> + +<h2 id="浏览器适配">浏览器适配</h2> + + + +<p>{{Compat("webextensions.api.windows.WindowType")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/windows#type-WindowType"><code>chrome.windows</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code>windows.json</code></a> in the Chromium code.</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> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/index.html new file mode 100644 index 0000000000..5fecb4334f --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/index.html @@ -0,0 +1,36 @@ +--- +title: clipboard +slug: Mozilla/Add-ons/WebExtensions/API/剪切板 +tags: + - 剪切板 + - 扩展 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/API/clipboard +--- +<div>{{AddonSidebar}}</div> + +<p>WebExtention 的 <code>clipboard</code> API 增加了一个将图像复制到剪贴板的函数。目前，这个 API 仅支持复制图像，但我们期望它未来支持复制文本和 HTML（译者注：原文如此，可能是指被支持复制富内容之后的标准剪贴板 API 取代）。</p> + +<p>这个 WebExtension API 之所以存在，主要是因为标准的 Web 剪贴板 API <a href="/zh-CN/docs/Web/API/Clipboard_API">Clipboard API</a> 不支持将图像写入剪贴板。一旦标准剪贴板 API 对非文本剪贴板内容的支持进入通用状态，则此 API 可能会被弃用。</p> + +<p>Reading from the clipboard is not supported by this API, because the clipboard can already be read using the standard web platform APIs. See <a href="https://wiki.developer.mozilla.org/en-US/Add-ons/WebExtensions/Interact_with_the_clipboard#Reading_from_the_clipboard">Interacting with the clipboard</a>.</p> + +<p>This API is based on Chrome's <code><a class="external external-icon" href="https://developer.chrome.com/apps/clipboard">clipboard</a></code> API, but that API is only available for Chrome apps, not extensions.</p> + +<p>To use this API you need the <code>"clipboardWrite"</code> extension <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="函数">函数</h2> + +<dl> + <dt>{{WebExtAPIRef("clipboard.setImageData()")}}</dt> + <dd>复制图像到剪切板。</dd> +</dl> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.api.clipboard")}} {{WebExtExamples("h2")}}</p> + +<div class="note"><strong>说明</strong> + +<p> 此 API 基于 Chromium 的 <a href="https://developer.chrome.com/apps/clipboard"><code>chrome.clipboard</code></a> API.</p> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/setimagedata/index.html b/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/setimagedata/index.html new file mode 100644 index 0000000000..3cdaf45b08 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/api/剪切板/setimagedata/index.html @@ -0,0 +1,79 @@ +--- +title: clipboard.setImageData() +slug: Mozilla/Add-ons/WebExtensions/API/剪切板/setImageData +tags: + - API + - Clipboard + - 剪贴板 + - 参考 + - 拓展 + - 方法 +translation_of: Mozilla/Add-ons/WebExtensions/API/clipboard/setImageData +--- +<div>{{AddonSidebar()}}</div> + +<p>将图像复制到剪贴板。在将图像写入剪贴板之前，会对图像进行重新编码。如果图像无效，则不会修改剪贴板。</p> + +<p>图像被作为包含经过编码的图像的 <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer">ArrayBuffer</a></code> 提供。支持 JPEG 和 PNG 格式。</p> + +<p>基于 Chrome 的 <code><a href="https://developer.chrome.com/apps/clipboard" rel="noopener">clipboard.setImageData()</a></code> API，但存在一些差异：</p> + +<ul> + <li>Chrome API 仅适用于应用，不适用于扩展程序。</li> + <li>此API需要 <code>"clipboardWrite"</code> 权限，Chrome 版本需要 <code>"clipboard"</code> 权限。</li> + <li>Chrome 的 API 使用回调，此 API 使用 Promise。</li> + <li>此 API 不支持 <code>additionalItems</code> 参数。</li> +</ul> + +<p>这是一个返回 <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> 的异步函数。</p> + +<h2 id="语法">语法</h2> + +<pre class="syntaxbox brush:js">browser.clipboard.setImageData(<em>imageData</em>, <em>imageType</em>) +</pre> + +<h3 id="参数">参数</h3> + +<dl> + <dt><code>imageData</code></dt> + <dd>An <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer">ArrayBuffer</a></code> containing the encoded image data to copy to the clipboard.</dd> + <dt><code>imageType</code></dt> + <dd>A {{domxref("DOMString")}} indicating the type of image contained in <code>imageData</code>: <code>"png"</code> or <code>"jpeg"</code>.</dd> +</dl> + +<h3 id="返回值">返回值</h3> + +<p>A <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be resolved with no arguments if the operation succeeded, or rejected if there was an error (for example, because the data did not represent a valid image).</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.clipboard.setImageData", 10)}}</p> + +<h2 id="示例">示例</h2> + +<p>Copy a remote image:</p> + +<pre class="brush: js" id="ct-71"><span class="quote">// requires: +// * the host permission for "<a href="https://cdn.mdn.mozilla.net/" rel="nofollow">https://cdn.mdn.mozilla.net/</a>*" +// * the API permission "clipboardWrite" + +fetch('<a href="https://cdn.mdn.mozilla.net/static/img/favicon144.png" rel="nofollow">https://cdn.mdn.mozilla.net/static/img/favicon144.png</a>') +.then(response => response.arrayBuffer()) +.then(buffer => browser.clipboard.setImageData(buffer, 'png'));</span></pre> + +<p><span class="quote">Copy an image that was bundled with the extension:</span></p> + +<pre class="brush: js" id="ct-70">// requires <span class="quote">the API permission </span>"clipboardWrite" + +fetch(browser.runtime.getURL('image.png')) +.then(response => response.arrayBuffer()) +.then(buffer => browser.clipboard.setImageData(buffer, 'png'));</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>说明</strong> + +<p> 此 API 基于 Chromium 的 <a href="https://developer.chrome.com/apps/clipboard"><code>chrome.clipboard</code></a> API.</p> +</div> |