diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/webextensions')
116 files changed, 15553 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html b/files/zh-cn/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html new file mode 100644 index 0000000000..64ec49a146 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html @@ -0,0 +1,220 @@ +--- +title: Add a button to the toolbar +slug: Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar +translation_of: Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar +--- +<div>{{AddonSidebar}}</div> + +<div>工具栏按钮是webextensions的一种主要UI组件，它在浏览器的工具栏中作为图标显示。当用户点击图标时，就会发生下面两种事件中的一样：</div> + +<ul> + <li>如果按钮有弹出菜单，则显示该弹出。 弹出菜单是一个临时对话，它必须使用HTML，CSS，JavaScript语言表示。</li> + <li>如果没有弹出菜单, 则生成一个单击事件, 你可以在代码中监听该事件并执行其他响应。</li> +</ul> + +<p>在WebExtensions中这种按钮被称为浏览器行为按钮，它们可以像下面这样生成：</p> + +<ul> + <li>manifest.json 文件中的键 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 被用来定义按钮。</li> + <li>JavaScript 接口 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> 被用来监听单击和更改按钮，或通过代码执行操作。</li> +</ul> + +<h2 id="一个简单的按钮">一个简单的按钮</h2> + +<p>在这一节中我们将创建一个工具栏按钮的 WebExtension 。当用户单击按钮时，会打开一个<a href="https://developer.mozilla.org">https://developer.mozilla.org</a> 的新标签页.</p> + +<p>首先，新建名为 "button"的文件夹, 在该文件夹下创建名为"manifest.json" 的文件，内容如下:</p> + +<pre class="brush: json">{ + + "description": "Demonstrating toolbar buttons", + "manifest_version": 2, + "name": "button-demo", + "version": "1.0", + + "background": { + "scripts": ["background.js"] + }, + + "browser_action": { + "default_icon": { + "16": "icons/page-16.png", + "32": "icons/page-32.png" + } + } + +}</pre> + +<p>上面内容显示有一个名为“ background .js ”后台脚本，以及在“ icons ”文件夹下的浏览器行为按钮图标。</p> + +<div class="pull-aside"> +<div class="moreinfo">These icons are from the <a href="https://www.iconfinder.com/iconsets/bitsies">bitsies!</a> iconset created by Recep Kütük.</div> +</div> + +<p>接下来，在"buttons" 文件夹下创建 "icons" 文件夹，在该文件夹下存放下面的图标文件 ：</p> + +<ul> + <li>"page-16.png" (<img alt="" src="https://mdn.mozillademos.org/files/13476/page-16.png" style="height: 16px; width: 16px;">)</li> + <li>"page-32.png" (<img alt="" src="https://mdn.mozillademos.org/files/13478/page-32.png" style="height: 32px; width: 32px;">).</li> +</ul> + +<div style=""> </div> + +<p>我们有两个图标，大图标用于在高分辨率状态下显示。浏览器会自动选择合适的图标。</p> + +<p>接着,在附加组件的根目录下创建 "background.js"文件 , 内容如下：</p> + +<pre class="brush: js">function openPage() { + browser.tabs.create({ + url: "https://developer.mozilla.org" + }); +} + +browser.browserAction.onClicked.addListener(openPage);</pre> + +<p>该文件用来监听浏览器单击事件。当单击事件发生时运行 <code>openPage()</code> 函数，这个函数通过使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs">tabs</a></code> 接口加载指定的页面。</p> + +<p>现在完整的附加组件看上去应该像下面这样：</p> + +<pre class="line-numbers language-html"><code class="language-html">button/ + icons/ + page-16.png + page-32.png + background.js + manifest.json</code></pre> + +<p>安装这个<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">WebExtension</a> ，然后单击按钮：</p> + +<p>{{EmbedYouTube("kwwTowgT-Ys")}}</p> + +<h2 id="添加一个弹出菜单">添加一个弹出菜单</h2> + +<p>尝试在按钮上添加一个弹出菜单。 修改 "manifest.json"如下:</p> + +<pre class="brush: json">{ + + "description": "Demonstrating toolbar buttons", + "manifest_version": 2, + "name": "button-demo", + "version": "1.0", + + "browser_action": { + "browser_style": true, + "default_popup": "popup/choose_page.html", + "default_icon": { + "16": "icons/page-16.png", + "32": "icons/page-32.png" + } + } + +}</pre> + +<p>我们把原文件做了三处改变:</p> + +<ul> + <li>我们不需要引用“ background.js ”文件，因为会在弹出菜单的脚本中处理该行为 (你也可以使用“background.js“来运行一个弹出窗口，只是现在我们不需要这么做).</li> + <li>我们添加了<code>"browser_style": true</code>, 使弹出样式看上去更像是浏览器的一部分。</li> + <li>最后，我们添加 <code>"default_popup": "popup/choose_page.html"</code>, 告诉浏览器按钮被单击时弹出菜单，菜单的内容则在"popup/choose_page.html"页面中.</li> +</ul> + +<p>现在我们要创建弹出菜单。新建名为 "popup" 的文件夹，然后在文件夹内创建"choose_page.html" 文件，该文件内容如下：</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_page.css"/> + </head> + +<body> + <div class="page-choice">developer.mozilla.org</div> + <div class="page-choice">support.mozilla.org</div> + <div class="page-choice">addons.mozilla.org</div> + <script src="choose_page.js"></script> +</body> + +</html></pre> + +<p>你会发现这是一个普通的HTML页面，它包含三个 {{htmlelement("div")}}元素，在每个元素中有一个Mozilla页面地址。另外还包括一个 CSS文件和一个JavaScript文件，我们会在后面添加它们。</p> + +<p>在 "popup" 文件夹下，创建名为 "choose_page.css" 的文件，内容如下：</p> + +<pre class="brush: css">html, body { + width: 300px; +} + +.page-choice { + width: 100%; + padding: 4px; + font-size: 1.5em; + text-align: center; + cursor: pointer; +} + +.page-choice:hover { + background-color: #CFF2F2; +}</pre> + +<p>这是我们弹出菜单的部分样式。</p> + +<p>接着，在 "popup" 文件夹下，创建名为 "choose_page.js" 的文件，内容如下：</p> + +<pre class="brush: js">document.addEventListener("click", function(e) { + if (!e.target.classList.contains("page-choice")) { + return; + } + + var chosenPage = "https://" + e.target.textContent; + browser.tabs.create({ + url: chosenPage + }); + +});</pre> + +<p>在我们的脚本中，我们会监听单击的弹出项。首先检查单击的对象是否在给出的页面选择项中，如果不在，则不做任何处理；如果在，则从单击的页面选择项中获取URL地址，然后打开一个对应页面的新标签页。注意：我们在弹出脚本中使用WebExtension接口，和在后台脚本中使用接口一样。</p> + +<p>附加组件的结构最后看上去应该像下面这样：</p> + +<pre>button/ + icons/ + page-16.png + page-32.png + popup/ + choose_page.css + choose_page.html + choose_page.js + manifest.json</pre> + +<p>重新加载附加组件，再次单击按钮，并尝试在弹出菜单中单击某个选择项：</p> + +<p>{{EmbedYouTube("QPEh1L1xq0Y")}}</p> + +<h2 id="页面行为">页面行为</h2> + +<p>页面行为<a href="/en-US/Add-ons/WebExtensions/User_interface_components#Page_actions">（Page actions）</a> 类似浏览器行为，只是页面行为仅针对特定页面，而浏览器行为则全局有效。</p> + +<p>由于浏览器行为总是发生，而页面行为只在特定页面显示。所以页面行为按钮在URL地址栏中显示，而浏览器行为按钮则在浏览器工具栏中显示。</p> + +<h2 id="了解更多">了解更多</h2> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API</li> + <li>Browser action examples: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/bookmark-it">Bookmark it!</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/inpage-toolbar-ui">inpage-toolbar-ui</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/open-my-page-button">open-my-page-button</a></li> + </ul> + </li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a></code> API</li> + <li>Page action examples: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a></li> + </ul> + </li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html b/files/zh-cn/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html new file mode 100644 index 0000000000..a405ac2f87 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html @@ -0,0 +1,148 @@ +--- +title: 剖析拓展 +slug: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +tags: + - WebExtension + - 拓展 + - 拓展开发 +translation_of: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>拓展是指一个包含若干文件的安装包，可直接分发至用户。本文中，我们快速地介绍一遍安装包内可能出现的文件。</p> + +<h2 id="manifest.json">manifest.json</h2> + +<p>这是唯一一个在每个 WebExtension 里面必须存在的文件。它包含了关于这个扩展插件基本的元数据（metadata），比如它的名字、版本和所需权限。并且，它也对 WebExtension 中其他文件进行了链接。</p> + +<p>这个 manifest 文件还可以指向其它一些类型的文件：</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background pages</a>: 执行一个长时间运行的逻辑</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">content scripts</a>: 与网页进行交互（注意：这与JavaScript在页面中的 {{HTMLElement("script")}} 元素不一样）</li> + <li><a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Browser_actions_2">browser action files</a>: 在工具栏中添加按钮</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Page_actions">page action files</a>: 在地址栏添加按钮</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Options_pages">options pages</a>: 为用户定义一个可浏览的UI界面，可以改变插件的设置</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Web_accessible_resources">web-accessible resources</a>: 使打包好的内容可用于网页与目录脚本</li> +</ul> + +<p><img alt="" src="https://mdn.mozillademos.org/files/12954/webextension-anatomy.svg" style="display: block; height: 581px; margin-left: auto; margin-right: auto; width: 600px;"></p> + +<p>浏览其他的详细信息请到 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 。</p> + +<p>除了这些 manifest 引用的文件之外，扩展也可以携带额外的 <a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Extension_pages">Extension pages</a> 。</p> + +<h2 id="后台脚本">后台脚本</h2> + +<p>扩展常常需要独立于任何浏览器窗口或特定网页来维持一种长期的状态或者执行长期的操作。这就是后台脚本（background scripts）的职责。</p> + +<p>后台脚本将在拓展加载完毕后开始运行，直到拓展被禁用或卸载。只要获得了相应的<a href="/zh-CN/Add-ons/WebExtensions/manifest.json/permissions">权限</a>，你就可以在脚本中使用任何 <a href="/zh-CN/Add-ons/WebExtensions/API">WebExtension API</a>。</p> + +<h3 id="指定后台脚本">指定后台脚本</h3> + +<p>你可以通过在 manifest.json 中添加关键字 <code>background</code> 来引入后台脚本：</p> + +<pre class="brush: json">// manifest.json + +"background": { + "scripts": ["background-script.js"] +}</pre> + +<p>可以添加多份后台脚本：而且，就像同一个网页中的多个脚本一样，它们将会运行在同一上下文环境中。</p> + +<p> </p> + +<p>与此同时，你也可以先引入一个后台页面，再在后台页面中引入脚本。这样做能为后台脚本添加 ES 6 模块支持，算是一个优势。</p> + +<p style="margin-bottom: 0em;"><strong>manifest.json</strong></p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="comment token">// manifest.json</span> + +<span class="key token">"background":</span> <span class="punctuation token">{</span> + <span class="key token">"page":</span> <span class="string token">"background-page.html"</span> +<span class="punctuation token">}</span></code></pre> + +<p style="margin-bottom: 0em;"><strong>background-page.html</strong></p> + +<pre class="brush: html line-numbers language-html"><code class="language-html"><span class="doctype token"><!DOCTYPE html></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"><</span>html</span> <span class="attr-name token">lang</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"zh-CN</span><span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>head</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>meta</span> <span class="attr-name token">charset</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>utf-8<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>script</span> <span class="attr-name token">type</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>module<span class="punctuation token">"</span></span> <span class="attr-name token">src</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>background-script.js<span class="punctuation token">"</span></span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"></</span>script</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>head</span><span class="punctuation token">></span></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>html</span><span class="punctuation token">></span></span></code></pre> + +<p> </p> + +<h3 id="后台脚本的运行环境">后台脚本的运行环境</h3> + +<h4 id="DOM_API">DOM API</h4> + +<p>后台脚本在一个被称为后台页面的特殊页面的上下文环境中运行。此环境为其提供了全局变量 <code><a href="/zh-CN/docs/Web/API/Window">window</a></code> ，也提供了所有的标准 DOM API。</p> + +<h4 id="WebExtension_API">WebExtension API</h4> + +<p>只要扩展获得了必要的<a href="/zh-CN/Add-ons/WebExtensions/manifest.json/permissions">权限</a>，后台脚本就可以使用所有的 <a href="/zh-CN/Add-ons/WebExtensions/API">WebExtension API</a>。</p> + +<h4 id="跨域访问">跨域访问</h4> + +<p>后台脚本可以向任何拥有<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#%E4%B8%BB%E6%9C%BA%E6%9D%83%E9%99%90">主机权限</a>的主机发送 XHR 请求。</p> + +<h4 id="网页内容">网页内容</h4> + +<p>后台脚本没有直接访问页面的权限。不过，他们可以在页面中加载<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">内容脚本</a>（content scripts），并且可以<a href="/zh-CN/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">通过 message-passing API 与内容脚本通信</a>。</p> + +<h4 id="内容安全策略">内容安全策略</h4> + +<p>根据一个内容安全策略（Content Security Policy），后台脚本不能执行一些可能有危险的操作，例如使用 <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>。 详情请参考<a href="/zh-CN/Add-ons/WebExtensions/Content_Security_Policy">内容安全策略</a>。</p> + +<h2 id="侧边栏，弹出窗口，选项页面">侧边栏，弹出窗口，选项页面</h2> + +<p>您的扩展程序可以包含各种用户界面组件，其内容通过 HTML 文件来定义：</p> + +<ul> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">侧边栏</a>是一个窗格，它被显示在浏览器窗口左侧，就在网页旁边</li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">弹出窗口</a>是一个对话框，可以在用户单击<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">工具栏按钮</a>或<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">地址栏按钮</a>时显示该对话框</li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">选项页面</a>是当用户访问拓展在拓展管理器内置的拓展选项页面时内嵌显示的页面。</li> +</ul> + +<p>对于这些组件，你可以创建一个 HTML 文件，并使用 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 中的特定属性指向它。HTML 文件可以引用 CSS 和 JavaScript 文件，就像普通的网页一样。</p> + +<p>所有这些都是<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">扩展页面</a>的一种，与普通网页不同的是，你可以在其 JavaScript 中使用所有有权限使用的 WebExtension API。 它们甚至可以通过 {{WebExtAPIRef("runtime.getBackgroundPage()")}} 直接访问后台页面中的变量。</p> + +<h2 id="扩展页面">扩展页面</h2> + +<p>您也可以在扩展中包含HTML文档，这些文档不附加到某个预定义的用户界面组件。与您可能为侧边栏，弹出窗口或选项页面提供的文档不同，它们在manifest.json中没有条目。但是，他们也可以访问所有与您的后台脚本相同的特权WebExtension API。</p> + +<p>你通常可以使用 {{WebExtAPIRef("windows.create()")}} 或 {{WebExtAPIRef("tabs.create()")}}加载一个页面.</p> + +<p>若想了解更多，请参考 <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">扩展页面</a>。</p> + +<h2 id="内容脚本">内容脚本</h2> + +<p>一般使用内容脚本来访问和操作页面。内容脚本会被加载到页面中并运行在页面的特定环境下。</p> + +<p>内容脚本是由扩展提供的脚本，与页面本身的脚本以及 {{HTMLElement("script")}} 标签中的脚本是不同的。</p> + +<p>内容脚本可以像普通脚本一样获取、操作页面的 DOM。</p> + +<p>与普通的页面内脚本不同，Content scripts可以：</p> + +<ul> + <li>执行跨域访问</li> + <li>使用 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API">WebExtension APIs </a>的子集</li> + <li>通过与后台脚本交换信息的方式，间接地使用所有<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API">WebExtension APIs </a></li> +</ul> + +<p>内容脚本无法直接访问普通网页中的脚本，但是可以通过 <code><a href="/zh-CN/docs/Web/API/Window/postMessage">window.postMessage()</a></code> API 来与之传递信息。</p> + +<p>通常情况下，当我们讨论内容脚本时，是在指（一类）使用 JavaScript 编写的脚本，但是你也可以用同样的机制来注入 CSS 文件。（译者注：不讨论含有编译器的情况。例如，若你事先引入了可编译 TypeScript 的 JavaScript 内容脚本，不论性能问题，你也很可能可以引入使用 TypeScript 编写的内容脚本：类似这样的情况，在此不计。）</p> + +<p>若想了解更多，请参考<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">内容脚本</a>。</p> + +<h2 id="Web_accessible_resources">Web accessible resources</h2> + +<p>Web accessible resources 是指像图片、HTML、CSS 和 JavaScript 之类的、被引入插件并且想要获得访问权限的内容脚本和页面脚本。这些 web-accessible 的资源可以在页面脚本和内容脚本中通过使用特定的URL方案来引用。<br> + 举个例子来说，如果一个内容脚本想要把一些图片插入网页，你可以在插件中引入它们并且使他们成为web-accseeible。接下来内容脚本就可以创建并追加包含 <code>src</code> 属性的 <a href="/zh-CN/docs/Web/HTML/Element/img">img</a> 标签了。</p> + +<p>若想了解更多，请参考 manifest.json key 的文档：<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a>。</p> 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> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html b/files/zh-cn/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html new file mode 100644 index 0000000000..f2ba32173b --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html @@ -0,0 +1,17 @@ +--- +title: Browser support for JavaScript APIs +slug: Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs +tags: + - WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs +--- +<div>{{AddonSidebar}}</div> + +<div>{{WebExtAllCompatTables}}</div> + +<p class="hidden">此页面的兼容性表格由结构化的数据生成。如果你想为这份数据出一些力，请看看 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 并发给我们一个 pull request。</p> + +<div class="note"><strong>致谢</strong> + +<p>Microsoft Edge 的兼容性数据由 Microsoft 公司提供，依照知识共享署名 3.0 美国协议授权。</p> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html b/files/zh-cn/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html new file mode 100644 index 0000000000..8cc71470f9 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html @@ -0,0 +1,154 @@ +--- +title: Chrome 不兼容情况 +slug: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +--- +<div>{{AddonSidebar}}</div> + +<p>使用WebExtension API构建的扩展旨在与Chrome和Opera扩展兼容：尽可能为这些浏览器编写的扩展应该在Firefox上运行，并且只需进行极少的更改。</p> + +<p>但是，Firefox目前仅支持Chrome和Opera支持的有限功能和API。 我们正在努力增加更多的支持，但许多功能尚未得到支持，我们可能永远不会支持某些功能。</p> + +<h2 id="JavaScript_APIs">JavaScript APIs</h2> + +<h3 id="回调与_chrome.*_命名空间">回调与 chrome.* 命名空间</h3> + +<p>在 Chrome 中，扩展通过使用 <code>chrome</code> 命名空间来访问私有 JavaScript API：</p> + +<pre class="brush: js line-numbers language-js">chrome.browserAction.setIcon({path: "path/to/icon.png"});</pre> + +<p>WebExtensions 通过使用 <code>browser</code> 命名空间来访问等价的 API：</p> + +<pre class="brush: js line-numbers language-js">browser.browserAction.setIcon({path: "path/to/icon.png"});</pre> + +<p>许多 API 是异步的。在 Chrome 中，异步的 API 使用回调来返回值，使用 {{WebExtAPIRef("runtime.lastError")}} 来与传达错误：</p> + +<pre class="brush: js line-numbers language-js">function logCookie(c) { + if (chrome.extension.lastError) { + console.error(chrome.extension.lastError); + } else { + console.log(c); + } +} + +chrome.cookies.set( + {url: "https://developer.mozilla.org/"}, + logCookie +);</pre> + +<p>在 WebExtensions 中应使用 <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">promises</a> 来访问等价的 API：</p> + +<pre class="brush: 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); +</pre> + +<h3 id="Firefox_支持_chrome_和_browser_命名空间">Firefox 支持 <code>chrome</code> 和 <code>browser</code> 命名空间</h3> + +<p>为了帮助移植，Firefox 的 WebExtension 实现支持 <code>chrome</code> 与回调和 <code>browser</code> 与 promise。这意味着许多 Chrome 扩展无须修改就能在 Firefox 上运行。然而并不是 WebExtension 标准的一部分，也许不会被所有兼容 WebExtension的浏览器支持。</p> + +<p>如果你在编写 WebExtension 时确实要用到 <code>browser</code> 和 promise，我们也开发了polyfill 来保证扩展可以在 Chrome 里运行：<a href="https://github.com/mozilla/webextension-polyfill">https://github.com/mozilla/webextension-polyfill</a>.</p> + +<h3 id="部分受支持的_API">部分受支持的 API</h3> + +<p>页面 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">JavaScript API 的浏览器支持情况</a> 包含了介绍受 Firefox 任意程度支持的 API 的兼容性表格。若对 API 的支持存在须要注意的事项，并标有星号“*”，且在 API 的参考页面会介绍注意事项。</p> + +<p>这些表格由 <a href="https://github.com/mdn/browser-compat-data">在 GitHub 上以 JSON 文件存储的兼容性数据</a>生成。</p> + +<p>本节剩余部分介绍了表格未涵盖的兼容性问题。</p> + +<h4 id="notifications"><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications">notifications</a></h4> + +<ul> + <li>For <code>notifications.create(), with the "basic"</code> <code><a href="/en-US/Add-ons/WebExtensions/API/notifications/TemplateType">type</a></code>, <code>iconUrl</code> is optional in Firefox. It is required in Chrome.</li> + <li>Notifications are cleared immediately when the user clicks on them. This is not the case in Chrome.</li> + <li>If you call <code>notifications.create()</code> more than once in rapid succession, Firefox may end up not displaying any notification at all. Waiting to make subsequent calls until within the <code>chrome.notifications.create() callback</code> function is not a sufficiently long delay to prevent this from happening.</li> +</ul> + +<h4 id="proxy"><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/proxy">proxy</a></h4> + +<ul> + <li>This API is completely different to the design of the Chrome API. With Chrome's API an extension can register a PAC file, but can also define explicit proxying rules. Since this is also possible using the extended PAC files, this API only supports the PAC file approach. Because this API is incompatible with the Chrome <code>proxy</code> API, this API is only available through the <code>browser</code> namespace.</li> +</ul> + +<h4 id="tabs"><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs">tabs</a></h4> + +<ul> + <li> + <p>In Firefox, relative URLs passed into <code>tabs.executeScript()</code> or <code>tabs.insertCSS()</code> are resolved relative to the current page URL. In Chrome, these URLs are resolved relative to the add-on's base URL. To work cross-browser, you can specify the path as an absolute URL, starting at the add-on's root, like this:</p> + + <pre class="brush: html">/path/to/script.js</pre> + </li> + <li>在 Firefox 中，用 <code>tabs.query() </code>根据 URL 查询标签页需要有<code>"tabs"</code> 权限。在 Chrome 中，没有<code>"tabs"</code>权限也可以，但结果将限制在 URL 匹配主机权限的标签页。</li> +</ul> + +<h4 id="webRequest"><a href="/en-US/Add-ons/WebExtensions/API/webRequest">webRequest</a></h4> + +<ul> + <li>在Firefx中，只有原网址使用 <code>http:</code> <code>或 https:</code> 协议时所请求的重定向才有效。</li> + <li>In Firefox, events are not fired for system requests (for example, extension upgrades or searchbar suggestions). From Firefox 57 onwards, Firefox makes an exception for extensions that need to intercept {{WebExtAPIRef("webRequest.onAuthRequired")}} for proxy authorization. See the documentation for {{WebExtAPIRef("webRequest.onAuthRequired")}}.</li> + <li>In Firefox, if an extension wants to redirect a public (e.g. HTTPS) URL to an <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">extension page</a>, the extension's manifest.json file must contain a <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a> key that lists the URL for the extension page. Note that any website may then link or redirect to that url, and extensions should treat any input (POST data, for examples) as if it came from an untrusted source, just as a normal web page should.</li> +</ul> + +<h4 id="windows"><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows">windows</a></h4> + +<ul> + <li>Firefox 中 <code>onFocusChanged</code> 对于指定的焦点变化将触发多次。</li> +</ul> + +<h3 id="其他不兼容情况">其他不兼容情况</h3> + +<h4 id="CSS_中的_URL">CSS 中的 URL</h4> + +<p>Firefox 解析 CSS 中嵌入的 URL 时，若 URL 时相对地址，将是相对 CSS 文件，而不是被嵌入的网页文件。</p> + +<h4 id="更多不兼容情况">更多不兼容情况</h4> + +<p>Firefox 不支持从后台标签页使用 <code><a href="/en-US/docs/Web/API/Window/alert">alert()、</a><a href="/en-US/docs/Web/API/Window/confirm">confirm()</a></code> 或<code><a href="/en-US/docs/Web/API/Window/prompt"> prompt()</a></code>。</p> + +<h4 id="web_accessible_resources">web_accessible_resources</h4> + +<p>在 Chrome 中，若资源在 web_accessible_resources 中列出，即可通过 chrome-extension://<your-extension-id>/<path/to/resource> 访问。每个扩展的 ID 都是固定的。</p> + +<p>Firefox 以不同方式进行实现。它使用一个随机的 UUID，在每个 Firefox 实例中都不同：moz-extension://<random-UUID>/<path/to/resource>。这一随机性可能会让你无法实现某些东西，例如你无法将特定扩展的 URL 添加到另一个域名的 CSP 策略中。</p> + +<h4 id="Manifest_key_属性">Manifest "key" 属性</h4> + +<p>对于解包了的扩展，Chrome 允许将 <a href="https://developer.chrome.com/extensions/manifest/key">"key" 属性</a>添加到 manifest，以确保在不同机器上的扩展 ID 不变。这主要在使用 web_accessible_resources 时有用。鉴于 Firefox 为 web_accessible_resources 使用随机的 UUID，此属性不受支持。</p> + +<h4 id="Content_script_requests_happen_in_the_context_of_extension_not_content_page">Content script requests happen in the context of extension, not content page</h4> + +<p>In Chrome when request is called (for example, using <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch">fetch()</a></code>) to relative URL like <code>/api</code> from content script, it will be sent to <code>https://example.com/api</code>. In Firefox you have to provide absolute URLs. </p> + +<h2 id="manifest.json_键">manifest.json 键</h2> + +<p>The main <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> page includes a table describing browser support for manifest.json keys. Where there are caveats around support for a given key, this is indicated in the table with an asterisk "*" and in the reference page for the key, the caveats are explained.</p> + +<p>These tables are generated from compatibility data stored as <a href="https://github.com/mdn/browser-compat-data">JSON files in GitHub</a>.</p> + +<h2 id="Native_messaging">Native messaging</h2> + +<h3 id="Command-line_arguments">Command-line arguments</h3> + +<p>On Linux and Mac, Chrome passes one argument to the native app, which is the origin of the extension that started it, in the form: <code>chrome-extension://[extensionID]</code>. This enables the app to identify the extension.</p> + +<p>On Windows, Chrome passes two arguments: the first is the origin of the extension, and the second is a handle to the Chrome native window that started the app.</p> + +<h3 id="allowed_extensions">allowed_extensions</h3> + +<p>In Chrome, the <code>allowed_extensions</code> key in the app manifest is called <code>allowed_origins</code> instead.</p> + +<h3 id="App_manifest_location">App manifest location</h3> + +<p>Chrome expects to find the app manifest in a different place. See <a href="https://developer.chrome.com/extensions/nativeMessaging#native-messaging-host-location">Native messaging host location</a> in the Chrome docs. </p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/content_scripts/index.html b/files/zh-cn/mozilla/add-ons/webextensions/content_scripts/index.html new file mode 100644 index 0000000000..4fe6a88055 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/content_scripts/index.html @@ -0,0 +1,575 @@ +--- +title: Content scripts +slug: Mozilla/Add-ons/WebExtensions/Content_scripts +translation_of: Mozilla/Add-ons/WebExtensions/Content_scripts +--- +<div>{{AddonSidebar}}</div> + +<p>Content script 是你扩展的一部分，运行于一个特定的网页环境（而并不是后台脚本，后台脚本是扩展的一部分，也不是该网页利用 {{HTMLElement("script")}} 加载的一个脚本，{{HTMLElement("script")}} 加载的脚本是网页的一部分）。</p> + +<p>后台脚本可以访问所有WebExtension JavaScript APIS，但是他们不能直接访问网页的内容，所以如果你需要Content Scripts来做到这点。</p> + +<p>就像通常的网页加载的脚本一样，Content Scripts 可以使用standard DOM APIS 读取和修改页面内容。</p> + +<p>Content Script 只能访问WebExtension APIS 的一个小的子集，但是它们可以使用通信系统与后台脚本进行通信，从而间接的访问WebExtension APIS。</p> + +<div class="note"> +<p>注意content scripts 在addons.mozilla.org现在已被禁止，如果你在这个域名尝试插入一个Content script将会失败而这个页面会LOG一个CSP错误。</p> +</div> + +<h2 id="加载Content_scripts">加载Content scripts</h2> + +<p>你可以通过两种方法之一在一个页面加载Content script：</p> + +<ul> + <li><strong>声明式</strong>: 在你的manifest.json中使用content_scripts关键字，你可以要求浏览器每当加载一个与指定正则表达式匹配的网页时加载一个Content Script。</li> + <li><strong>程序式</strong>: 使用 <code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/executeScript">tabs.executeScript()</a></code> API, 你可以在任何你想要的时候加载一个Content script 到一个指定的标签：比如，作为用户点击事件的回应。</li> +</ul> + +<p>在每一个extension的每一个frame中，只有一个全局作用域。所以在一个content script中的变量可以被另外的content script访问到，而与content script如何被加载无关。</p> + +<h2 id="Content_script_环境">Content script 环境</h2> + +<h3 id="DOM_访问">DOM 访问</h3> + +<p>Content scripts 可以访问和修改页面的DOM，就像普通的页面脚本一样。他们也可以察觉页面脚本对页面做出的任何修改。</p> + +<p>不过，content scripts 得到的是一个“干净的DOM视图”，这意味着：</p> + +<ul> + <li>content scripts 不能看见页面脚本定义的javascript 变量。</li> + <li>如果一个页面脚本重定义了一个DOM内置属性，content scripts将获取到这个属性的原始版本，而不是重定义版本。</li> +</ul> + +<p>在 Gecko（译者注：Gecko是由 Mozilla 工程开发出的布局引擎的名字）, 这种行为被称为射线视觉。</p> + +<p>举个例子，考虑一个网页如下：</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8" /> + </head> + + <body> + <script src="page-scripts/page-script.js"></script> + </body> +</html></pre> + +<p>脚本文件“page-script.js”如下：</p> + +<pre class="brush: js">// page-script.js + +// add a new element to the DOM +var p = document.createElement("p"); +p.textContent = "This paragraph was added by a page script."; +p.setAttribute("id", "page-script-para"); +document.body.appendChild(p); + +// define a new property on the window +window.foo = "This global variable was added by a page script"; + +// redefine the built-in window.confirm() function +window.confirm = function() { + alert("The page script has also redefined 'confirm'"); +}</pre> + +<p>现在一个扩展插入一个content script 如下:</p> + +<pre class="brush: js">// content-script.js + +// can access and modify the DOM +var pageScriptPara = document.getElementById("page-script-para"); +pageScriptPara.style.backgroundColor = "blue"; + +// can't see page-script-added properties +console.log(window.foo); // undefined + +// sees the original form of redefined properties +window.confirm("Are you sure?"); // calls the original window.confirm()</pre> + +<p>相反的情况也是成立的：页面脚本不能察觉到通过content scripts 添加的JavaScript 属性。</p> + +<p>这意味着content script 可以依靠DOM属性获取可预期的行为</p> + +<p>这种行为造成的一个结果是content script不能获取任何通过页面加载的Javascript 库。所以，如果这个页面包含JQuery，content script 将不会在意它。</p> + +<p>如果一个content script 想要使用Javascript库，这个库本身就必须像一个content script一样在这个content script旁被插入:</p> + +<pre class="brush: json">"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["jquery.js", "content-script.js"] + } +]</pre> + +<h3 id="WebExtension_APIs">WebExtension APIs</h3> + +<p>除了standard DOM APIS，content script还能使用以下WebExtension APIS:</p> + +<p>From <code><a href="/en-US/Add-ons/WebExtensions/API/extension">extension</a></code>:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/extension#getURL()">getURL()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/extension#inIncognitoContext">inIncognitoContext</a></code></li> +</ul> + +<p>From <code><a href="/en-US/Add-ons/WebExtensions/API/runtime">runtime</a></code>:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#connect()">connect()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#getManifest()">getManifest()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#getURL()">getURL()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onConnect">onConnect</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onMessage">onMessage</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#sendMessage()">sendMessage()</a></code></li> +</ul> + +<p>From <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a></code>:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage">getMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getAcceptLanguages">getAcceptLanguages()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getUILanguage">getUILanguage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/detectLanguage">detectLanguage()</a></code></li> +</ul> + +<p>所有 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code>.</p> + +<h3 id="跨域名权限">跨域名权限</h3> + +<p>content scripts 拥有与扩展剩余部分一致的权限：所以如果这个扩展已在manifest.json文件中使用permission关键字请求跨域权限，其content script将能很好获取某些跨域权限。</p> + +<h2 id="后台脚本通信">后台脚本通信</h2> + +<p>尽管content scripts 不能直接使用大部分WebExtension APIS，但他们可以通过使用messaging APIS 与扩展的后台脚本通信，然后便能够间接地调用所有的后台脚本能够调用的APIS。</p> + +<p>在background script和content script中有两种基本的通讯方式：你可以发送带有可选回复的一次性的消息，或者在两者之间建立一个长期活动的连接并用这个连接来进行信息交换。</p> + +<h3 id="一次性消息">一次性消息</h3> + +<p>为了发送一个带有可选回复选项的一次性消息，你能使用以下APIS:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"> </th> + <th scope="col">In content script</th> + <th scope="col">In background script</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Send a message</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#sendMessage()">browser.runtime.sendMessage()</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/sendMessage">browser.tabs.sendMessage()</a></code></td> + </tr> + <tr> + <th scope="row">Receive a message</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onMessage">browser.runtime.onMessage</a></code></td> + </tr> + </tbody> +</table> + +<p>举例，这里是一个监听点击事件的content script，如果点击发生在一个链接上，他将会将该链接的地址发送给后台脚本:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("click", notifyExtension); + +function notifyExtension(e) { + if (e.target.tagName != "A") { + return; + } + browser.runtime.sendMessage({"url": e.target.href}); +}</pre> + +<p>后台脚本监听这个消息然后使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications">notifications</a></code> API 显示一个通知:</p> + +<pre class="brush: js">// background-script.js + +browser.runtime.onMessage.addListener(notify); + +function notify(message) { + browser.notifications.create({ + "type": "basic", + "iconUrl": browser.extension.getURL("link.png"), + "title": "You clicked a link!", + "message": message.url + }); +} +</pre> + +<p>这个示范代码从Github上的 <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 例子 修改而来.</p> + +<h3 id="Connection-based_messaging">Connection-based messaging</h3> + +<p>如果你将在一个content script 和 后台脚本间交换大量的消息，一次性消息会变得笨重而缓慢。所以一个更好的方案是在两个脚本间建立一个长久连接，然后使用该连接交换消息。</p> + +<p>每个脚本都有一个 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> 对象用以交换消息。</p> + +<p>建立过程：:</p> + +<ul> + <li> + <p>在一个脚本中使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code> 监听连接</p> + </li> + <li>另一个脚本中调用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/connect">tabs.connect()</a></code> (如果连接 content script) or <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/connect">runtime.connect()</a></code> (如果连接后台脚本). 这会返回一个 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> 对象.</li> + <li> <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code> 传递它自己的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> 对象.</li> +</ul> + +<p>每个脚本都拥有一个port，两个脚本可以使用runtime.Port.postMessage()来发送消息，runtime.Port.onMessage 来接收消息</p> + +<p>比如，当加载该content script时:</p> + +<ul> + <li>连接到后台脚本，存取Port对象至 <code>myPort</code></li> + <li>监听myPort上的消息，并记录。</li> + <li>当用户点击网页是发送消息至后台脚本。</li> +</ul> + +<pre class="brush: js">// content-script.js + +var myPort = browser.runtime.connect({name:"port-from-cs"}); +myPort.postMessage({greeting: "hello from content script"}); + +myPort.onMessage.addListener(function(m) { + console.log("In content script, received message from background script: "); + console.log(m.greeting); +}); + +document.body.addEventListener("click", function() { + myPort.postMessage({greeting: "they clicked the page!"}); +});</pre> + +<p>对应的后台脚本:</p> + +<ul> + <li>监听content script 的所有连接企图。</li> + <li>当收到连接请求后: + <ul> + <li>存贮Port对象至 <code>portFromCS</code></li> + <li>使用portFromCS发送一个消息到content script</li> + <li>开始监听消息并记录它们。</li> + </ul> + </li> + <li>当用户点击浏览器的某些扩展按钮或动作后，发送一个消息到content script。</li> +</ul> + +<pre class="brush: js">// background-script.js + +var portFromCS; + +function connected(p) { + portFromCS = p; + portFromCS.postMessage({greeting: "hi there content script!"}); + portFromCS.onMessage.addListener(function(m) { + console.log("In background script, received message from content script") + console.log(m.greeting); + }); +} + +browser.runtime.onConnect.addListener(connected); + +browser.browserAction.onClicked.addListener(function() { + portFromCS.postMessage({greeting: "they clicked the button!"}); +}); +</pre> + +<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/inpage-toolbar-ui">inpage-toolbar-ui</a> 例子使用了 connection-based messaging.</p> + +<ul> +</ul> + +<h2 id="网页通信">网页通信</h2> + +<p>尽管content script 通常不能获取由网页脚本创建的对象，但他们可以通过 <code><a href="/en-US/docs/Web/API/Window/postMessage">window.postMessage</a></code> 和 <code><a href="/en-US/docs/Web/API/EventTarget/addEventListener">window.addEventListener</a></code> APIs 与网页脚本进行通信.</p> + +<p>比如:</p> + +<pre class="brush: js">// page-script.js + +var messenger = document.getElementById("from-page-script"); + +messenger.addEventListener("click", messageContentScript); + +function messageContentScript() { + window.postMessage({ + direction: "from-page-script", + message: "Message from the page" + }, "*");</pre> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data.direction && + event.data.direction == "from-page-script") { + alert("Content script received message: \"" + event.data.message + "\""); + } +});</pre> + +<p>完整的例子请访问该链接, <a href="https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html">visit the demo page on GitHub</a> 并且观看以下介绍.</p> + +<div class="warning"> +<p>需要注意的是当你用该方法与一些不被信任的网页进行交互式需要特别小心。WebExtensions拥有高等级权限，而一些恶意页面可以很轻松的获取这些权限。</p> + +<p>做一个微小的示范，假定有如下content script 代码:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data.direction && + event.data.direction == "from-page-script") { + eval(event.data.message); + } +});</pre> + +<p>现在网页脚本可以在content script 权限范围内运行任何代码。</p> +</div> + +<h2 id="与页面脚本共享对象">与页面脚本共享对象</h2> + +<div class="note"> +<p>这个部分的技术描述只适用于49版本后的Firefox</p> +</div> + +<div class="warning"> +<p>作为一个插件开发者你必须考虑脚本运行在任何伺机偷取用户个人隐私，破坏他们的电脑，或者使用其他方式攻击的网页上。</p> + +<p>隔离content script 和 页面脚本 便是为了使恶意网页的攻击变得更加困难。</p> + +<p>这部分的技术打破了这个隔离，它们从根本上是危险的而应该被谨慎使用。</p> +</div> + +<p>我们在 <a href="/en-US/Add-ons/WebExtensions/Content_scripts#DOM_access">DOM access</a> 中看到content scripts不会察觉到通过网页脚本修改的某些属性. 这意味着，如果一个网页加载了一个库比如JQuery，content script 将不会使用它，而不得不加载它自己的一个复制。相反的，网页加载的脚本也不能获知content script的修改。</p> + +<p>然而，Firefox提供了一些APIS 可以使得content script能够:</p> + +<ul> + <li>访问页面脚本创建的Javascript 对象</li> + <li>暴露他们自己的JavaScript对象给页面脚本.</li> +</ul> + +<h3 id="Xray_vision_in_Firefox">Xray vision in Firefox</h3> + +<p>在Firefox中，隔离content script 和页面脚本通过使用一种称为“Xray vision”的功能实现。 当一个处于更高权限的脚本访问一个被定义于一个更低权限版本的域中时，它将只能看见这个对象的原始版本。</p> + +<p>任何 <a href="/en-US/docs/Glossary/Expando">expando</a> 属性都是不可见得, 而且如果对象的任何属性被重定义，他也只能能看见原始的实现而不是重定义的实现。</p> + +<p>这个功能的目的是为了让低权限的脚本不至于因为重定义原始对象属性而使高权限脚本行为异常。</p> + +<p>让我们来举个例子，当一个content script 访问一个页面的 <a href="/en-US/docs/Web/API/Window">window</a> 类,他不会看见任何该页面脚本对这个window 添加的任何属性, 如果页面脚本重定义了任何已存在的属性，content script将只能看见该属性的原始版本。</p> + +<p>更多信心请查看 <a href="/en-US/docs/Mozilla/Tech/Xray_vision">Xray vision</a> 和 <a href="/en-US/docs/Mozilla/Gecko/Script_security">Script security</a>.</p> + +<h3 id="从content_script_中访问_页面脚本对象">从content script 中访问 页面脚本对象</h3> + +<p>在Firefox中，content script中的DOM对象会获得一个额外的属性 wrappedJSObject。这是一个会包含任何由页面脚本所造成修改的”未包裹“对象。</p> + +<p>让我们来看一个简单的例子，假定一个页面载入脚本如下:</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <meta charset="UTF-8"> + </head> + <body> + <script type="text/javascript" src="main.js"></script> + </body> +</html></pre> + +<p><code>这个脚本添加一个全局的属性到全局window</code>:</p> + +<pre class="brush: js">// main.js + +var foo = "I'm defined in a page script!";</pre> + +<p>Xray vision 意味着 如果一个content script 尝试访问foo，它将是未定义的:</p> + +<pre class="brush: js">// content-script.js + +console.log(window.foo); // undefined</pre> + +<p>在Firefox，content script 可以使用window.wrappedJSObject来看见全局属性:</p> + +<pre class="brush: js">// content-script.js + +console.log(window.wrappedJSObject.foo); // "I'm defined in a page script!"</pre> + +<p>注意因为这个原因，你最好不在依赖该对象的任何属性或方法 建立或执行某些操作，你所期望的，它们，甚至setter和getter 都可能被不被信任的代码重定义。</p> + +<p>同时注意unwarapping是及物的:当你使用wrappedJSObject，该未包裹对象的任何属性都是未包裹的（同时都是不可靠的），所以 一个好的建议是只在你需要时获取这个对象，重新包裹他，你能这样做：</p> + +<pre class="bz_comment_text" id="comment_text_38">XPCNativeWrapper(window.wrappedJSObject.foo);</pre> + +<p>查看 <a href="/en-US/docs/Mozilla/Tech/Xray_vision">Xray vision </a> 文档获取更多.</p> + +<h3 id="与页面脚本共享content_script_对象">与页面脚本共享content script 对象</h3> + +<p>Firefox 同样提供APIS允许content scripts 是对象对于页面脚本可用。这里是两个主要的APIS:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/Content_scripts#exportFunction">exportFunction()</a></code>: 导出一个函数至页面脚本</li> + <li><code><a href="/en-US/Add-ons/WebExtensions/Content_scripts#cloneInto">cloneInto()</a></code>: 导出一个对象至页面脚本</li> +</ul> + +<h4 id="exportFunction">exportFunction</h4> + +<p>给予一个定义于content script中的方法，exportFunction（）导出他至页面脚本域，然后脚本可以调用它。</p> + +<p>比如，让我们考虑一个WebExtension有一个后台脚本如下：</p> + +<pre class="brush: js">/* +Execute content script in the active tab. +*/ +function loadContentScript() { + browser.tabs.executeScript({ + file: "/content_scripts/export.js" + }); +} + +/* +Add loadContentScript() as a listener to clicks +on the browser action. +*/ +browser.browserAction.onClicked.addListener(loadContentScript); + +/* +Show a notification when we get messages from +the content script. +*/ +browser.runtime.onMessage.addListener((message) => { + browser.notifications.create({ + type: "basic", + title: "Message from the page", + message: message.content + }); +});</pre> + +<p>该脚本做了两件事:</p> + +<ul> + <li>当用户点击浏览器按钮时，在当前标签执行一个content script 。</li> + <li>监听从content script 传递的消息，并在消息到达时显示一个通知。</li> +</ul> + +<p>content script 如下:</p> + +<pre class="brush: js">/* +Define a function in the content script's scope, then export it +into the page script's scope. +*/ +function notify(message) { + browser.runtime.sendMessage({content: "Function call: " + message}); +} + +exportFunction(notify, window, {defineAs:'notify'});</pre> + +<p>该脚本定义了一个函数notify（）用以发送其参数到后台脚本，而后他导出了这个函数至页面脚本域。现在页面脚本可以调用该函数:</p> + +<pre class="brush: js">window.notify("Message from the page script!");</pre> + +<p>更详细的信息请看, <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.exportFunction">Components.utils.exportFunction</a></code>.</p> + +<h4 id="cloneInto">cloneInto</h4> + +<p>给予一个定义于content script的对象, 该技术可以创建该对象的一个复制到页面脚本域,从而使该复制可以被页面脚本访问.通常使用 <a href="/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">structured clone algorithm</a> 复制对象, 这意味着该对象中的方法不会被复制为了复制方法，需要传递cloneFunction选项.</p> + +<p>比如，这里有一个content script 定义了一个包含方法的对象，然后复制他们至页面脚本域:</p> + +<pre class="brush: js">/* +Create an object that contains functions in +the content script's scope, then clone it +into the page script's scope. + +Because the object contains functions, +the cloneInto call must include +the `cloneFunctions` option. +*/ +var messenger = { + notify: function(message) { + browser.runtime.sendMessage({ + content: "Object method call: " + message + }); + } +}; + +window.wrappedJSObject.messenger = cloneInto( + messenger, + window, + {cloneFunctions: true});</pre> + +<p><code>现在页面脚本将看到新的含有notify方法的属性</code>:</p> + +<pre class="brush: js">window.messenger.notify("Message from the page script!");</pre> + +<p>详情请看 <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.cloneInto">Components.utils.cloneInto</a></code>.</p> + +<h2 id="在content_script中使用_eval()">在content script中使用 eval()</h2> + +<p>在 Chrome中，<code>eval()</code> 总是在content script的上下文环境中运行， 而不是在页面的上下文环境中运行.</p> + +<p>在Firefox中:</p> + +<ul> + <li>如果你调用<code>eval()</code>，它在content script的上下文中运行</li> + <li>如果你调用<code>window.eval()</code>，它在页面的上下文中运行</li> +</ul> + +<p>比如，有一个content script如下:</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">eval</span><span class="punctuation token">(</span><span class="string token">'window.x = 1;'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="function token">eval</span><span class="punctuation token">(</span><span class="string token">'window.y = 2'</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><span class="template-string token"><span class="string token">`In content script, window.x: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>window<span class="punctuation token">.</span>x<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></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><span class="template-string token"><span class="string token">`In content script, window.y: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>window<span class="punctuation token">.</span>y<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +window<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span> + message<span class="punctuation token">:</span> <span class="string token">"check"</span> +<span class="punctuation token">}</span><span class="punctuation token">,</span> <span class="string token">"*"</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>这段代码仅仅通过调用<code>window.eval()</code> 和 <code>eval()</code>创建了变量x和y。然后记录它们的值并通知页面更新.</p> + +<p>接收到消息后页面的脚本记录下这些变量:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">window<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">"message"</span><span class="punctuation token">,</span> <span class="keyword token">function</span><span class="punctuation token">(</span>event<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>event<span class="punctuation token">.</span>source <span class="operator token">===</span> window <span class="operator token">&&</span> event<span class="punctuation token">.</span>data <span class="operator token">&&</span> event<span class="punctuation token">.</span>data<span class="punctuation token">.</span>message <span class="operator token">===</span> <span class="string token">"check"</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><span class="template-string token"><span class="string token">`In page script, window.x: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>window<span class="punctuation token">.</span>x<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></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><span class="template-string token"><span class="string token">`In page script, window.y: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>window<span class="punctuation token">.</span>y<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></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>在Chrome中，输出类似下面所示：</p> + +<pre class="line-numbers language-html"><code class="language-html">In content script, window.x: 1 +In content script, window.y: 2 +In page script, window.x: undefined +In page script, window.y: undefined</code></pre> + +<p>在Firefox中，输出类似下面所示：</p> + +<pre class="line-numbers language-html"><code class="language-html">In content script, window.x: undefined +In content script, window.y: 2 +In page script, window.x: 1 +In page script, window.y: undefined</code></pre> + +<p>上述内容同样适用于 <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout()</a></code>, <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></code>, and <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function()</a></code>.</p> + +<p>当在页面的上下文中运行代码时, 适用于上面所提到的"<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#Sharing_objects_with_page_scripts">Sharing content script objects with page scripts</a>" 这一部分的警告: 页面的环境可能会被恶意的网页所控制，这可能会导致你所交互的对象会有意想不到的行为：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// page.js redefines console.log</span> + +<span class="keyword token">var</span> original <span class="operator token">=</span> console<span class="punctuation token">.</span>log<span class="punctuation token">;</span> + +console<span class="punctuation token">.</span>log <span class="operator token">=</span> <span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="function token">original</span><span class="punctuation token">(</span><span class="keyword token">true</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span></code></pre> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">// content-script.js calls the redefined version</span> + +window<span class="punctuation token">.</span><span class="function token">eval</span><span class="punctuation token">(</span><span class="string token">'console.log(false)'</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/content_security_policy/index.html b/files/zh-cn/mozilla/add-ons/webextensions/content_security_policy/index.html new file mode 100644 index 0000000000..7ea0d2655d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/content_security_policy/index.html @@ -0,0 +1,107 @@ +--- +title: Content Security Policy +slug: Mozilla/Add-ons/WebExtensions/Content_Security_Policy +translation_of: Mozilla/Add-ons/WebExtensions/Content_Security_Policy +--- +<div>{{AddonSidebar}}</div> + +<div class="summary"> +<p>使用WebExtension API 开发的插件默认应用了内容安全策略(Content Security Policy, 缩写CSP)。这限制了可以加载的<strong><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script"> </a></strong><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script"><script></a> 和 <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object"><object></a> 的资源来源，并且禁止了潜在的不安全用法如 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>.</p> + +<p>这篇文章简单地解释了CSP是什么，默认的策略是什么，这对插件来说意味着什么，以及插件如何改变默认CSP。</p> +</div> + +<p><a href="/en-US/docs/Web/HTTP/CSP">Content Security Policy</a> (CSP) 是一种避免网站意外执行包含有恶意的内容的机制。网站通过使用服务端发送的HTTP头指定CSP。CSP主要关注指定各种内容的合法来源，如脚本和嵌入式插件。例如，网站可以使用它来告诉浏览器应该只执行来自网站自身的JavaScript，而不腻执行其他来源的脚本。CSP还可以指导浏览器禁止潜在危险行为，如<code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>的使用。</p> + +<p>和网页一样，插件可以加载其他来源的内容。例如浏览器的弹出窗口可以指定为一个HTML文档，它同样可以包含不同来源的JavaScript和CSS，就像一个普通的网页一样。</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + </head> + + <body> + + <!--Some HTML content here--> + + <!-- + Include a third-party script. + See also https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity. + --> + <script + src="https://code.jquery.com/jquery-2.2.4.js" + integrity="sha256-iT6Q9iMJYuQiMWNd9lDyBUStIq/8PuOW33aOqmvFpqI=" + crossorigin="anonymous"> + </script> + + <!-- Include my popup's own script--> + <script src="popup.js"></script> + </body> + +</html></pre> + +<p>和网站相比，插件可以访问特权API，因此一旦它们被恶意代码破坏，风险就更大。因此：</p> + +<ul> + <li>插件默认运行在一个相当严格的安全策略下。参考 <a href="/en-US/Add-ons/WebExtensions/Content_Security_Policy#Default_content_security_policy">default content security policy</a>.</li> + <li>插件的作者可以通过使用manifest.json中的 <code>content_security_policy</code> 关键词改变这种默认策略，但是允许的策略仍然有一定的限制。参考 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code>.</li> +</ul> + +<h2 id="默认内容安全策略">默认内容安全策略</h2> + +<p>对插件的默认内容安全策略如下：</p> + +<pre>"script-src 'self'; object-src 'self';"</pre> + +<p>这会被应用在任何没有明确在manifest.json中的<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code> 项设置自己的内容安全策略的插件中。它有以下几种效果：</p> + +<ul> + <li> + <p><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_Security_Policy#Location_of_script_and_object_resources">你只能将本地的 <script> 和 <object> 资源加载到插件中。</a></p> + </li> + <li> + <p><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_Security_Policy#eval()_and_friends">插件无法将字符串转换为JavaScript执行。</a></p> + </li> + <li> + <p><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_Security_Policy#Inline_JavaScript">内联JavaScript不会被执行。</a></p> + </li> +</ul> + +<h3 id="script_和_object资源的位置">script 和 object资源的位置</h3> + +<p>在默认CSP下你只能加载相对插件来说本地的 <a href="/en-US/docs/Web/HTML/Element/script"><script></a> 和 <a href="/en-US/docs/Web/HTML/Element/object"><object></a> 资源。例如假设插件文档中存在这样一条语句：</p> + +<pre class="brush: html"> <script src="https://code.jquery.com/jquery-2.2.4.js"></script></pre> + +<p>这不会加载请求的资源：它会安静地失败，并且你所期望看到的任何来自该资源的对象都不会出现。对于这种情况有两种解决办法：</p> + +<ul> + <li> + <p>下载该资源，打包进你的插件，然后引用它。</p> + </li> + <li> + <p>使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code> 允许你所需要的资源。</p> + </li> +</ul> + +<h3 id="eval_和friends">eval() 和friends</h3> + +<p>默认CSP下插件不被允许像JavaScript一样执行字符串。这意味着以下情况都被禁止：</p> + +<pre class="brush: js">eval("console.log('some output');");</pre> + +<pre class="brush: js">window.setTimeout("alert('Hello World!');", 500);</pre> + +<pre class="brush: js">var f = new Function("console.log('foo');");</pre> + +<h3 id="内联_JavaScript">内联 JavaScript</h3> + +<p>默认CSP下内联JavaScript不被执行。这不仅不允许将JavaScript直接放在 <code><script></code> 标签中间，也不允许内联事件句柄。即以下内容被禁止：</p> + +<pre class="brush: html"><script>console.log("foo");</script></pre> + +<pre class="brush: html"><div onclick="console.log('click')">Click me!</div></pre> + +<p>如果你正在使用类似 <code><body onload="main()"></code> 的代码在页面加载时运行你的脚本，请使用监听器监听<a href="/en-US/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> 或者 <a href="/en-US/docs/Web/Events/load">load</a> 代替。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/embedded_webextensions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/embedded_webextensions/index.html new file mode 100644 index 0000000000..834125bb32 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/embedded_webextensions/index.html @@ -0,0 +1,205 @@ +--- +title: Embedded WebExtensions +slug: Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions +translation_of: Archive/Add-ons/Embedded_WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>嵌入一个 WebExtension 需要使用 Firefox 51 或更高版本。在 SDK 附加组件中嵌入一个 WebExtension 还需要 <a href="https://www.npmjs.com/package/jpm">jpm 1.2.0</a>。</p> +</div> + +<p>从 Firefox 51 开始，你可以在传统附加组件类型中嵌入一个 WebExtension。</p> + +<p>传统附加组件可以是经典的<a href="/en-US/docs/Mozilla/Add-ons/Bootstrapped_extensions">自举扩展</a>或者<a href="/en-US/docs/Mozilla/Add-ons/SDK">Add-on SDK</a> 附加组件。嵌入式 WebExtension 的文件打包在传统附加组件中。嵌入式 WebExtension 并不直接与嵌入的附加组件共享范围，但可以使用 {{WebExtAPIRef("runtime")}} API 中定义的消息函数交换消息。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13895/embedded-we.png" style="display: block; height: 522px; margin-left: auto; margin-right: auto; width: 429px;"></p> + +<p>这意味着您可以一次性迁移传统附加组件到 WebExtensions，并且在此期间附加组件的功能完全保留。尤其是它可以让您从旧版附加组件<a href="/en-US/Add-ons/WebExtensions/Embedded_WebExtensions#Migrating_data_from_legacy_add-ons">迁移存储数据</a>到 WebExtension，通过撰写一个中间的混合式附加组件，使用旧版 API 读取数据（例如 <a href="/en-US/docs/Mozilla/Add-ons/SDK/High-Level_APIs/simple-prefs">simple-prefs</a> 或 preferences <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm">服务</a>）并使用 WebExtension API 写入它（例如 {{WebExtAPIRef("storage")}}）。</p> + +<p>连同本指南，我们撰写了两个例子展示如何使用嵌入式 WebExtensions 来帮助从传统附加组件迁移。<a href="https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-bootstrapped">如何从自举式附加组件迁移</a>以及<a href="https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-sdk">如何从 SDK 附加组件迁移</a>。</p> + +<h2 id="嵌入_WebExtension">嵌入 WebExtension</h2> + +<p>如果传统附加组件是一个带有<a href="/en-US/Add-ons/Install_Manifests">install.rdf</a> 的自举式扩展，在该 RDF 中加入 "hasEmbeddedWebExtension" 并设为 "true"：</p> + +<pre><<span class="pl-ent">em</span><span class="pl-ent">:</span><span class="pl-ent">hasEmbeddedWebExtension</span>>true</<span class="pl-ent">em</span><span class="pl-ent">:</span><span class="pl-ent">hasEmbeddedWebExtension</span>></pre> + +<div>如果旧式附加组件是一个 SDK 附加组件，在 package.json 中包含 "hasEmbeddedWebExtension" 并设为 <code>true</code>：</div> + +<div> </div> + +<pre class="brush: json"><span class="pl-s"><span class="pl-pds">"</span>hasEmbeddedWebExtension<span class="pl-pds">"</span></span>: <span class="pl-c1">true</span> +</pre> + +<div>WebExtension 本身放在附加组件中的 "webextension" 顶层目录。例如：</div> + +<div> </div> + +<pre>my-boostrapped-addon/ + chrome/ + webextension/ + manifest.json + background.js + ... + bootstrap.js + chrome.manifest + install.rdf</pre> + +<div> </div> + +<div> +<pre>my-sdk-addon/ + index.js + package.json + webextension/ + manifest.json + background.js + ...</pre> +</div> + +<p>Firefox 不将嵌入式 WebExtension 视为一个独立的附加组件。因此，您不应该为它指定一个<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">附加组件 ID</a>。如果你这样做，那只会被忽略。</p> + +<p>但是，在您完成附加组件的迁移并移除旧式嵌入代码后，您必须添加一个 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> 键，设置 ID 为旧式附加组件的 ID。通过此方式，<a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> 可以识别 WebExtension 是旧式附加组件的一个更新。</p> + +<h2 id="启动_WebExtension">启动 WebExtension</h2> + +<p>嵌入式 WebExtension 必须由被嵌入的附加组件明确启动。</p> + +<p>如果被嵌入的附加组件是一个自举式附加组件，那么传递到自举式扩展的 <code><a href="/en-US/Add-ons/Bootstrapped_extensions#startup">startup()</a></code> 函数的 <code>data</code> 将获得一个明确的 <code>webExtension</code>：</p> + +<pre class="brush: js">// bootstrapped add-on + +<span class="pl-k">function</span> <span class="pl-en">startup</span>({webExtension}) { + +...</pre> + +<p>如果被嵌入的附加组件是一个 SDK 附加组件，它可以使用 <code>sdk/webextension</code> 模块访问一个 WebExtension 对象：</p> + +<pre class="brush: js"><span class="pl-k">// SDK add-on + +const</span> <span class="pl-c1">webExtension</span> <span class="pl-k">=</span> <span class="pl-c1">require</span>(<span class="pl-s"><span class="pl-pds">"</span>sdk/webextension<span class="pl-pds">"</span></span>);</pre> + +<p>无论哪种方式，此对象都有一个 <code>startup()</code> 函数，它返回一个 <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>。该 promise 使用一个 <code>browser</code> 属性解决一个对象：这包括 {{WebExtAPIRef("runtime")}} API，被嵌入的附加组件可以用它来与嵌入式 WebExtension 交换消息：</p> + +<ul> + <li>{{WebExtAPIRef("runtime.onConnect")}}</li> + <li>{{WebExtAPIRef("runtime.onMessage")}}</li> +</ul> + +<p>例如：</p> + +<pre class="brush: js">// bootstrapped add-on + +function startup({webExtension}) { + webExtension.startup().then(api => { + const {browser} = api; + browser.runtime.onMessage.addListener(handleMessage); + }); +}</pre> + +<pre class="brush: js"><span class="pl-k">// SDK add-on</span> + +const webExtension = require("sdk/webextension"); + +webExtension.startup().then(api => { + const {browser} = api; + browser.runtime.onMessage.addListener(handleMessage); +}); +</pre> + +<p>应注意的是，嵌入的附加组件不能启动通信，它可以使用 <code>onMessage</code> 接收（并可选响应）一次性消息，并可以使用 <code>onConnect</code> 接受连接请求。</p> + +<p>如果嵌入式 WebExtension 缺少一个 manifest，或者如果 manifest 无效，该 promise 会被拒绝。这种情况下，您可以在<a href="/en-US/Add-ons/WebExtensions/Debugging#Viewing_log_output">浏览器工具箱的控制台</a>中看到更多细节。</p> + +<h2 id="交换消息">交换消息</h2> + +<p>一旦嵌入式 WebExtension 处在运行，它可以使用 {{WebExtAPIRef("runtime")}} API 的子集与旧式附加组件交换消息：</p> + +<ul> + <li>它可以使用 {{WebExtAPIRef("runtime.sendMessage()")}} 发送一次性消息。</li> + <li>它可以使用 {{WebExtAPIRef("runtime.connect()")}} 建立一个连接。</li> +</ul> + +<h3 id="无需连接的消息">无需连接的消息</h3> + +<p>要发送一条消息，WebExtension 可以使用 {{WebExtAPIRef("runtime.sendMessage()")}}。您可以省略 <code>extensionId</code> 参数，因为浏览器认为嵌入式 WebExtension 是被嵌入附加组件的一部分：</p> + +<pre class="brush: js">browser.runtime.sendMessage("message-from-webextension").then(reply => { + if (reply) { + console.log("response from legacy add-on: " + reply.content); + } +});</pre> + +<p>被嵌入的附加组件可以使用 {{WebExtAPIRef("runtime.onMessage")}} 对象接收消息（并可选响应）：</p> + +<pre class="brush: js">// bootstrapped add-on + +function startup({webExtension}) { + // Start the embedded webextension. + webExtension.startup().then(api => { + const {browser} = api; + browser.runtime.onMessage.addListener((msg, sender, sendReply) => { + if (msg == "message-from-webextension") { + sendReply({ + content: "reply from legacy add-on" + }); + } + }); + }); +}</pre> + +<h3 id="基于连接的消息">基于连接的消息</h3> + +<p>要在 WebExtension 与传统附加组件间设置一个长寿命连接，WebExtension 可以使用 {{WebExtAPIRef("runtime.connect()")}}。</p> + +<pre class="brush: js">var port = browser.runtime.connect({name: "connection-to-legacy"}); + +port.onMessage.addListener(function(message) { + console.log("Message from legacy add-on: " + message.content); +}); +</pre> + +<p>旧式附加组件可以使用 {{WebExtAPIRef("runtime.onConnect")}} 监听连接尝试，双方可以使用得到的 {{webExtAPIRef("runtime.Port")}} 来交换消息：</p> + +<pre class="brush: js">function startup({webExtension}) { + // Start the embedded webextension. + webExtension.startup().then(api => { + const {browser} = api; + browser.runtime.onConnect.addListener((port) => { + port.postMessage({ + content: "content from legacy add-on" + }); + }); + }); +}</pre> + +<h2 id="从传统附加组件迁移数据">从传统附加组件迁移数据</h2> + +<p>嵌入式 WebExtensions 的一项主要用途是迁移附加组件的存储数据。</p> + +<p>人们从旧式附加组件类型迁移的一个主要问题是存储数据，因为旧式附加组件不能使用 WebExtension 存储 API，WebExtensions 也不能使用旧式存储 API。例如，如果一个 SDK 附加组件使用了 SDK 的 <a href="/en-US/docs/Mozilla/Add-ons/SDK/High-Level_APIs/simple-prefs">simple-prefs</a> API 来存储首选项，WebExtension 版本不可能访问这项数据。</p> + +<p>使用嵌入式 WebExtensions，您可以创建一个嵌入了 WebExtension 的附加组件中间版本来迁移数据。中间版本使用旧式 API 读取存储的数据，然后使用 WebExtension API 写入数据。</p> + +<ul> + <li>在初始版本中，基于 SDK 的附加组件使用 <a href="/en-US/docs/Mozilla/Add-ons/SDK/High-Level_APIs/simple-prefs">simple-prefs</a> API 读取和写入附加组件首选项。</li> + <li> + <p>在中间版本中，SDK 附加组件启动嵌入式 WebExtension。WebExtension 要求 SDK 附加组件用 simple-prefs 检索存储的数据。WebExtension 然后使用 {{WebExtAPIRef("storage")}} API 存储数据。</p> + + <div class="note"> + <p>在某些情况下，中间版本必须在初始导入后保持数据同步。例如，<a href="/en-US/Add-ons/WebExtensions/Embedded_WebExtensions#Add-on_preferences_UI">附加组件的首选项界面仍然使用旧系统</a>，所以如果用户在这里修改了设置，它修改的是旧数据。中间的附加组件必须监听这些更改并将新数据发送到嵌入式 WebExtension。</p> + + <p>有个 <a href="https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-sdk">"embedded-webextension-sdk"</a> 示例说明了这一点。</p> + </div> + </li> + <li>在最终版本中，附加组件只是一个 WebExtension，并且只使用存储 API。</li> +</ul> + +<p>我们提供了两个例子说明此模式：<a href="https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-bootstrapped">"embedded-webextension-bootstrapped"</a> 展示了从一个自举式附加组件迁移，而 <a href="https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-sdk">"embedded-webextension-sdk"</a> 展示了从一个 SDK 附加组件迁移。</p> + +<h2 id="限制">限制</h2> + +<h3 id="调试">调试</h3> + +<p>如果您有一个嵌入了 WebExtension 的旧式附加组件，您不能使用新的附加组件调试器来调试它。您必须使用基于浏览器工具箱的<a href="/en-US/Add-ons/WebExtensions/Debugging_(before_Firefox_50)">旧版调试工具</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/examples/index.html b/files/zh-cn/mozilla/add-ons/webextensions/examples/index.html new file mode 100644 index 0000000000..ce413198ea --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/examples/index.html @@ -0,0 +1,31 @@ +--- +title: 扩展示例 +slug: Mozilla/Add-ons/WebExtensions/Examples +tags: + - firefox extension + - firefox 扩展 + - 扩展案例 + - 火狐扩展 +translation_of: Mozilla/Add-ons/WebExtensions/Examples +--- +<div>{{AddonSidebar}}</div> + +<p>为帮助了解如何开发扩展，我们维护了一个包含简单扩展示例的代码仓库在<a href="https://github.com/mdn/webextensions-examples">https://github.com/mdn/webextensions-examples</a>. 本文描述了仓库代码中所使用的 WebExtension APIs。</p> + +<p>这些示例工作在 Firefox Nightly 下: 大部分示例在 Firefox 的早期版本中也能够运行, 请检查扩展 manifest.json 文件中的 <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">strict_min_version</a> 键。</p> + +<p>如果你想尝试这些示例，有下面三个选择：</p> + +<ol> + <li>克隆代码库，通过 <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">"临时载入附加组件"</a> 功能直接从源文件夹中载入扩展组件。再重启浏览器前该扩展将一直存在。</li> + <li>克隆代码库，使用 <a href="/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> 命令行工具运行安装了扩展的 Firefox。</li> + <li>克隆代码库，进入 <a href="https://github.com/mdn/webextensions-examples/tree/master/build">build</a> 文件夹。该文件夹包含所有示例的已构建、带签名版本。你可以在Firefox中打开（菜单栏->文件->打开文件）并且永久安装这些扩展。这些扩展和直接从 <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> 安装的扩展别无二致。</li> +</ol> + +<div class="blockIndicator warning"> +<p><strong>重要</strong>：不要提交这些关于 WebExtension 例子的示例到 AMO (addons.mozilla.org) 上去，你无需为附加组件签名就能运行 WebExtension 的示例。只要按照上面的步骤来就可以了。</p> +</div> + +<p>如果你想对代码仓库贡献，<a href="https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md">给我们发送 pull request！</a></p> + +<p>{{WebExtAllExamples}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html b/files/zh-cn/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html new file mode 100644 index 0000000000..cf44f0de27 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html @@ -0,0 +1,164 @@ +--- +title: 扩展开发人员工具 +slug: Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools +tags: + - Add-ons + - DevTools + - Guide + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>本页介绍了火狐 Firefox 55中存在的开发工具接口（dectools APIs)。 虽然该接口Api基于 Chrome 开发工具Api，仍有许多功能尚未实现在火狐中实现，因此未记录在本页内容中。产看当前缺失的功能，请参阅链接<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Using_the_devtools_APIs#Limitations_of_the_devtools_APIs">开发工具Api的限制.</a></p> +</div> + +<p>您可以使用WebExtensions API扩展浏览器的内置开发人员工具。要创建devtools扩展，请在manifest.json中包含“ devtools_page”键：</p> + +<pre class="brush: json notranslate">"devtools_page": "devtools/devtools-page.html"</pre> + +<p>此项的值是指向与您的扩展程序捆绑在一起的HTML文件的URL。该URL应相对于manifest.json文件本身。</p> + +<p>HTML文件在扩展中定义了一个特殊页面，称为devtools页面。</p> + +<h2 id="devtools页面">devtools页面</h2> + +<p>当打开浏览器devtools时，将加载devtools页面，并在关闭浏览器时将其卸载。请注意，由于devtools窗口与单个选项卡相关联，因此很可能同时存在多个devtools窗口-因此有多个devtools页面。</p> + +<p>devtools页面没有任何可见的DOM，但可以包含使用<script>标记的JavaScript源。源必须与扩展本身捆绑在一起。来源可以访问：:</p> + +<ul> + <li>可通过全局窗口对象访问的普通DOM API</li> + <li>与内容脚本中相同的WebExtension API</li> + <li>The devtools APIs: + <ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow">devtools.inspectedWindow</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.network">devtools.network</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.panels">devtools.panels</a></code></li> + </ul> + </li> +</ul> + +<p>请注意，devtools页面无法访问任何其他WebExtension API，并且后台页面无法访问devtools API。相反，devtools页面和后台页面必须使用运行时消息传递API进行通信。这是一个例子:</p> + +<pre class="brush: html notranslate"><!DOCTYPE html> +<html> + <head> + <meta charset="utf-8"> + </head> + <body> + <script src="devtools.js"></script> + </body> +</html></pre> + +<p>devtools.js文件将保存创建您的dev工具扩展的实际代码。</p> + +<h2 id="创建面板">创建面板</h2> + +<p>devtools窗口中包含许多单独的工具-JavaScript调试器，网络监视器等。顶部的一排标签可让用户在不同的工具之间切换。承载每个工具的用户界面的窗口称为“面板”</p> + +<p>使用devtools.panels.create（）API，可以在devtools窗口中创建自己的面板：</p> + +<pre class="brush: js notranslate">browser.devtools.panels.create( + "My Panel", // title + "icons/star.png", // icon + "devtools/panel/panel.html" // content +).then((newPanel) => { + newPanel.onShown.addListener(initialisePanel); + newPanel.onHidden.addListener(unInitialisePanel); +});</pre> + +<p>这需要三个必选参数：面板的标题，图标和内容。它返回一个Promise，该Promise解析为代表新面板的devtools.panels.ExtensionPanel对象。</p> + +<h2 id="与目标窗口互动">与目标窗口互动</h2> + +<p>开发人员工具始终附加到特定的浏览器选项卡。这称为开发人员工具的“目标”或“检查的窗口”。您可以使用devtools.inspectedWindow API与检查的窗口进行交互。</p> + +<h3 id="Running_code_in_the_target_window">Running code in the target window</h3> + +<p>devtools.inspectedWindow.eval（）提供了一种在检查的窗口中运行代码的方法。</p> + +<p>这有点像使用{{WebExtAPIRef("tabs.executeScript()")}}注入内容脚本，但有一个重要区别：</p> + +<ul> + <li>与内容脚本不同，使用devtools.inspectedWindow.eval（）加载的脚本不会获得“ DOM的清晰视图”：也就是说，它们可以看到页面脚本对页面所做的更改。</li> +</ul> + +<div class="note"> +<p>请注意，DOM的清晰视图是一项安全功能，旨在通过重新定义本机DOM功能的行为来帮助防止恶意页面欺骗扩展。这意味着您需要非常小心地使用eval（），并应尽可能使用普通的内容脚本。</p> +</div> + +<p>devtools.inspectedWindow.eval（）加载的脚本也看不到内容脚本定义的任何JavaScript变量。</p> + +<h3 id="Working_with_content_scripts">Working with content scripts</h3> + +<p>devtools文档无法直接访问{{WebExtAPIRef("tabs.executeScript()")}}，因此，如果需要注入内容脚本，devtools文档必须向后台脚本发送一条消息，要求其注入剧本。 devtools.inspectedWindow.tabId提供目标选项卡的ID：devtools文档可以将其传递给后台脚本，而后台脚本又可以将其传递给{{WebExtAPIRef("tabs.executeScript()")}}：</p> + +<pre class="brush: js notranslate">// devtools-panel.js + +const scriptToAttach = "document.body.innerHTML = 'Hi from the devtools';"; + +window.addEventListener("click", () => { + browser.runtime.sendMessage({ + tabId: browser.devtools.inspectedWindow.tabId, + script: scriptToAttach + }); +});</pre> + +<pre class="brush: js notranslate">// background.js + +function handleMessage(request, sender, sendResponse) { + browser.tabs.executeScript(request.tabId, { + code: request.script + }); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<p>如果您需要在目标窗口中运行的内容脚本和devtools文档之间交换消息，则最好使用{{WebExtAPIRef("runtime.connect()")}}和{{WebExtAPIRef("runtime.onConnect()")}}，以在后台页面和devtools文档之间建立连接。然后，后台页面可以维护选项卡ID和{{WebExtAPIRef("runtime.Port")}}对象之间的映射，并使用此映射在两个作用域之间路由消息。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14923/devtools-content-scripts.png" style="display: block; height: 416px; margin-left: auto; margin-right: auto; width: 600px;"></p> + +<h2 id="devtools_API的局限性">devtools API的局限性</h2> + +<p>这些API基于Chrome devtools API，但与Chrome相比，许多功能仍缺失。本节列出了从Firefox 54开始尚未实现的功能。请注意，devtools API正在积极开发中，我们希望在将来的版本中增加对其中大多数功能的支持。</p> + +<h3 id="devtools.inspectedWindow">devtools.inspectedWindow</h3> + +<p>The following are not supported:</p> + +<ul> + <li><code>inspectedWindow.getResources()</code></li> + <li><code>inspectedWindow.onResourceAdded</code></li> + <li><code>inspectedWindow.onResourceContentCommitted</code></li> +</ul> + +<p>None of the options to <code>inspectedWindow.eval()</code> are supported.</p> + +<p>使用inspectedWindow.eval（）注入的脚本不能使用控制台的所有命令行帮助器功能，但是都支持$ 0和inspect（...）（从Firefox 55开始）。</p> + +<h3 id="devtools.panels">devtools.panels</h3> + +<p>The following are not supported:</p> + +<ul> + <li><code>panels.elements</code></li> + <li><code>panels.sources</code></li> + <li><code>panels.setOpenResourceHandler()</code></li> + <li><code>panels.openResource()</code></li> + <li><code>panels.ExtensionPanel.createStatusBarButton()</code></li> + <li><code>panels.Button</code></li> + <li><code>panels.ElementsPanel</code></li> + <li><code>panels.SourcesPanel</code></li> +</ul> + +<h2 id="Examples">Examples</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo on GitHub, contains several examples of extensions that use devtools panels:</p> + +<ul> + <li> + <p><a href="https://github.com/mdn/webextensions-examples/blob/master/devtools-panels/">devtools-panels</a> use devtools panels:</p> + </li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/index.html new file mode 100644 index 0000000000..cdd473ca78 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/index.html @@ -0,0 +1,122 @@ +--- +title: 浏览器扩展 +slug: Mozilla/Add-ons/WebExtensions +tags: + - WebExtension + - WebExtensions + - firefox add-on + - firefox extensions + - web-extensions + - 发布 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>Extensions「扩展」 可以扩展和修改一个浏览器的能力。用于 Firefox 的 扩展使用 WebExtensions API 「一种开发扩展的跨浏览器系统」构建。该系统与 Google Chrome、Opera 和 <a href="https://browserext.github.io/browserext/">W3C 草案社区组织</a> 所支持的 <a href="https://developer.chrome.com/extensions">扩展 API </a>在很大程度上兼容。大多数情况下为这些浏览器编写的扩展<a href="/zh-CN/Add-ons/WebExtensions/Porting_from_Google_Chrome">只需少许修改</a>即可在 Firefox 或 <a href="https://developer.microsoft.com/zh-CN/microsoft-edge/platform/documentation/extensions/">Microsoft Edge</a> 中运行。这种 API 与也完全兼容 <a href="/zh-CN/Firefox/Multiprocess_Firefox">多进程 Firefox</a>。</p> + +<p>如果你有想法或问题，或者在使用 WebExtensions APIs 迁移旧式附加组件时需要帮助，可以在 <a href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons 邮件列表</a> 或者 <a href="https://wiki.mozilla.org/IRC">IRC</a> 上的 <a href="irc://irc.mozilla.org/extdev">#extdev</a> 与我们联系。</p> + +<div class="row topicpage-table"> +<div class="section"> +<h2 id="新手入门">新手入门</h2> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/What_are_WebExtensions">什么是扩展?</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Your_first_WebExtension">你的第一个扩展</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Your_second_WebExtension">你的第二个扩展</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">扩展解析</a></li> + <li>火狐工作流概述</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Examples">扩展示例</a></li> + <li>下一步</li> +</ul> + +<h2 id="操作方法">操作方法</h2> + +<ul> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests">拦截 HTTP 请求</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page">修改网页</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">在工具栏添加按钮</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">制作一个设置页面</a></li> + <li><a href="/zh-CN//docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard">与剪贴板交互</a></li> + <li>使用页签API</li> + <li>使用书签API</li> +</ul> + +<h2 id="用户界面">用户界面</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface">简介</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">浏览器工具栏按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">有弹出面板的浏览器工具栏按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">地址栏按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">有弹出面板的地址栏按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">上下文菜单项</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">侧边栏</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">选项页面</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">捆绑网页（Bundled web pages）</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">通知</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">地址栏建议</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">开发者工具面板</a></li> +</ul> + +<h2 id="相关概念">相关概念</h2> + +<ul> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Using_the_JavaScript_APIs">使用 JavaScript API</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/User_interface_components">用户界面元素</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Content_scripts">内容脚本</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Match_patterns">模式匹配</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Working_with_files">处理文件</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Internationalization">国际化</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">内容安全政策</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">本地消息</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/User_experience_best_practices">用户体验的最佳实践</a></li> +</ul> + +<h2 id="扩展移植">扩展移植</h2> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Porting_from_Google_Chrome">移植 Google Chrome 扩展</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Porting_a_legacy_Firefox_add-on">移植传统的 Firefox 附加组件</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions">嵌入式 WebExtensions</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">与 Firefox Add-on SDK 的差异</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">与 XUL/XPCOM 的差异</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities">与 Chrome 不兼容的地方</a></li> +</ul> + +<h2 id="Firefox_工作流">Firefox 工作流</h2> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">安装</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Debugging">调试</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">开始使用 web-ext</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference">web-ext 命令参考</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">WebExtensions 与附加组件 ID</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/Add-ons/WebExtensions/Alternative_distribution_options">其他分发选项</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension">发布你的 WebExtension</a></li> +</ul> +</div> + +<div class="section"> +<h2 id="参考资料">参考资料</h2> + +<h3 id="JavaScript_APIs">JavaScript APIs</h3> + +<ul> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API">JavaScript API概况</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">JavaScript API 浏览器兼容性表格</a></li> +</ul> + +<div class="twocolumns">{{ ListSubpages ("/zh-CN/Add-ons/WebExtensions/API") }}</div> + +<h3 id="Manifest_关键信息">Manifest 关键信息</h3> + +<ul> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json 概览</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">manifest.json 的浏览器兼容性</a></li> +</ul> + +<div class="twocolumns">{{ ListSubpages ("/zh-CN/Add-ons/WebExtensions/manifest.json") }}</div> +</div> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.html b/files/zh-cn/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.html new file mode 100644 index 0000000000..092125a9ca --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.html @@ -0,0 +1,157 @@ +--- +title: Interact with the clipboard +slug: Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard +translation_of: Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard +--- +<div>{{AddonSidebar}}</div> + +<p>有两种方式可以让浏览器扩展与系统剪贴板交互: {{domxref("Document.execCommand()")}} 方法以及现代的异步的 <a href="/en-US/docs/Web/API/Clipboard_API">Clipboard API</a>.</p> + +<p>{{domxref("Document.execCommand()")}} 方法常通过以下指令使用:</p> + +<ul> + <li><code>document.execCommand("copy")</code></li> + <li><code>document.execCommand("cut")</code></li> + <li><code>document.execCommand("paste")</code></li> +</ul> + +<p>Clipboard API 提供了异步的连接来直接读写剪贴板内容. 例, 如此从剪贴板读取文本:</p> + +<pre class="brush: js">navigator.clipboard.readText().then(text => outputElem.innerText = text);</pre> + +<p>这将请求剪贴板内容, 并且当接收到响应时存储剪贴板文本到一个元素的 {{domxref("Node.innerText", "innerText")}}.</p> + +<div class="blockIndicator note"> +<p>注意: 异步的 Clipboard API 方法是一个近期新增的规范, 并且这个规范可能不适用于所有浏览器. 请在使用前测试了每一种方法的兼容性, 以确保支持满足您的需求.</p> +</div> + +<h2 id="写入系统粘贴板">写入系统粘贴板</h2> + +<p>有两种向剪贴板写入数据的方法. 你可以使用 {{domxref("Document.execCommand", "document.execCommand()")}} 来触发 "剪切" 和 "复制" 行为, 这将用选择的数据覆盖剪贴板的当前内容. 另一个选项是使用 Clipboard API 的 {{domxref("Clipboard.writeText()")}} 或 {{domxref("Clipboard.write()")}} 方法来用指定数据覆盖剪贴板内容.</p> + +<h3 id="使用_execCommand()">使用 execCommand()</h3> + +<p>{{domxref("Document.execCommand", "document.execCommand()")}} 方法的 <code>"cut"</code> 与 <code>"copy"</code> 命令可以被用于以选中素材代替剪贴板的当前内容. 这些命令无需任何特别的权限就可以使用, 如果你在一个用于用户操作的短生存期的事件处理程序中使用他们(例如, 一次点击事件).</p> + +<p>例如，假设你有一个下面的弹出菜单页面：</p> + +<pre class="brush: html"><input id="input" type="text"/> +<button id="copy">Copy</button> +</pre> + +<p>使 "copy"按钮能复制 "input"中的文本，代码如下：</p> + +<pre class="brush: js">function copy() { + var copyText = document.querySelector("#input"); + copyText.select(); + document.execCommand("Copy"); +} + +document.querySelector("#copy").addEventListener("click", copy);</pre> + +<p>由于<code>execCommand()</code>命令在单击事件中，所以不需要特别的权限。</p> + +<p>此外，如果用警报（alarm）替换上面的命令来触发复制事件：</p> + +<pre class="brush: js">function copy() { + var copyText = document.querySelector("#input"); + copyText.select(); + document.execCommand("Copy"); +} + +browser.alarms.create({ + delayInMinutes: 0.1 +}); + +browser.alarms.onAlarm.addListener(copy);</pre> + +<p>这种触发不一定成功，它取决于浏览器是否支持。Firefox浏览器就不支持该功能，你会在浏览器控制台中看到以下信息：</p> + +<pre>"document.execCommand(‘cut’/‘copy’) was denied because it was not called from inside a short running user-generated event handler."</pre> + +<p>为了能够在这种情形下使用，你需要拥有"clipboardWrite"的权限（ <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>）。 因此，"clipboardWrite"权限能使你不通过临时事件处理程序就可以写入系统粘贴板中。</p> + +<h3 id="使用_Clipboard_API">使用 Clipboard API</h3> + +<p>Clipboard API 更加灵活, 因为你不仅可以将当前选择复制到剪贴板中, 还可以直接指定要放入剪贴板的信息.</p> + +<p>要使用 Clipboard API 需要在你的 <code>manifest.json</code> 文件中申请 <code>clipboardRead</code> 与 <code>clipboardWrite</code> 权限.</p> + +<p>对于页面脚本, 需要权限 API 的 <code>clipboard-write</code> 权限. 你可通过 {{domxref("Permissions.query", "navigator.permissions.query()")}} 来检查这个权限:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">navigator<span class="punctuation token">.</span>permissions<span class="punctuation token">.</span><span class="function token">query</span><span class="punctuation token">(</span><span class="punctuation token">{</span>name<span class="punctuation token">:</span> <span class="string token">"clipboard-write"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>result <span class="operator token">=></span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>result<span class="punctuation token">.</span>state <span class="operator token">==</span> <span class="string token">"granted"</span> <span class="operator token">||</span> result<span class="punctuation token">.</span>state <span class="operator token">==</span> <span class="string token">"prompt"</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token">/* write to the clipboard now */</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>这个函数使用一个字符串作为输入并且用它更新剪贴板:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">updateClipboard</span><span class="punctuation token">(</span>newClip<span class="punctuation token">)</span> <span class="punctuation token">{</span> + navigator<span class="punctuation token">.</span>clipboard<span class="punctuation token">.</span><span class="function token">writeText</span><span class="punctuation token">(</span>newClip<span class="punctuation token">)</span><span class="punctuation token">.</span><span class="function token">then</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> + <span class="comment token">/* clipboard successfully set */</span> + <span class="punctuation token">}</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> + <span class="comment token">/* clipboard write failed */</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span></code></pre> + +<h3 id="特定浏览器注意事项">特定浏览器注意事项</h3> + +<p> 这里涉及的剪贴板和其他API正在快速发展, 因此浏览器在工作方式上存在差异.</p> + +<p>在Chrome中:</p> + +<ul> + <li>你可以在所有执行上下文中写入系统粘贴板，像背景网页、内容脚本、标签页和弹出菜单。</li> + <li>你不需要 <code>"clipboardWrite"</code> 权限，甚至不需要在用户生成的事件处理程序中写入粘贴板</li> +</ul> + +<p>在Firefox中:</p> + +<ul> + <li>除了背景网页外，你可以在所有执行上下文中使用 execCommand 写入粘贴板。在Firefox中，你无法选择文本或将输入字段聚焦在后台页面中，因此无法使用 execCommand 从后台页面写入剪贴板。</li> + <li>只有version 51以上才支持"clipboardWrite" 权限。</li> + <li>从 version 57 开始，可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/clipboard/setImageData">clipboard.setImageData()</a></code> API 将图像复制到剪贴板。</li> + <li>在 Firefox 633 中添加了对 Clipboard API {{domxref("Clipboard.writeText", "navigator.clipboard.writeText()")}} 方法的支持。</li> + <li>当使用一个内容脚本，Clipboard API 只可用于 HTTPS 页。解决方法是，在内容脚本和后台脚本之间使用消息传递。</li> +</ul> + +<h2 id="读取系统粘贴板">读取系统粘贴板</h2> + +<p><code>execCommand()</code> 方法提供了 <code>"paste"</code> 指令，能让你粘贴内容。你可以使用 Clipboard API 的更灵活的方法： {{domxref("Clipboard.read()")}} 和 {{domxref("Clipboard.readText()")}}。</p> + +<h3 id="使用_execCommand()_2">使用 execCommand()</h3> + +<p>首先，你需要为扩展申请 <code>"clipboardRead"</code> <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a> 。即便你在用户生成的事件处理程序 ( 例如 {{event("click")}} 或 {{event("keypress")}} ) 中使用 "paste" 指令也是如此。</p> + +<p>假设你的HTML页面内容如下：</p> + +<pre class="brush: html"><input id="output" type="text"/> +<button id="paste">粘贴</button> +</pre> + +<p>要在用户单机 id 为 <code>"paste"</code> 的 {{HTMLElement("button")}} 时从剪贴板设置 id 为 <code>"output"</code> 的 {{HTMLElement("textarea")}} 的内容，可以使用这样的代码:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">paste</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">var</span> pasteText <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">querySelector</span><span class="punctuation token">(</span><span class="string token">"#output"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + pasteText<span class="punctuation token">.</span><span class="function token">focus</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + document<span class="punctuation token">.</span><span class="function token">execCommand</span><span class="punctuation token">(</span><span class="string token">"paste"</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>pasteText<span class="punctuation token">.</span>textContent<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +document<span class="punctuation token">.</span><span class="function token">querySelector</span><span class="punctuation token">(</span><span class="string token">"#paste"</span><span class="punctuation token">)</span><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> paste<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<h3 id="使用_Clipboard_API_2">使用 Clipboard API</h3> + +<p>剪贴板 API 的 {{domxref("Clipboard.readText", "navigator.clipboard.readText()")}} 和 {{domxref("Clipboard.read", "navigator.clipboard.read()")}} 方法让你从剪贴板读取任意文本或二进制数据。这让你从剪贴板访问数据无需将它们粘贴至一个可编辑的元素中。</p> + +<p>一旦你通过 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API">Permissions API</a> 获取了 <code>"clipboard-read"</code> 权限，你就可以轻松读取剪贴板:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">navigator<span class="punctuation token">.</span>clipboard<span class="punctuation token">.</span><span class="function token">readText</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>clipText <span class="operator token">=></span> + document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">"outbox"</span><span class="punctuation token">)</span><span class="punctuation token">.</span>innerText <span class="operator token">=</span> clipText<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>这个代码片段从剪贴板提取文本并且用该文本替换 ID 为 <code>"outbox"</code> 的元素的当前内容。</p> + +<h3 id="特定浏览器注意事项_2">特定浏览器注意事项</h3> + +<p>Firefox 在 54 版本提供了 <code>"clipboardRead"</code> <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a> ，但是仅支持向处于 <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content">内容可编辑模式</a> 的元素粘贴，对于内容脚本，只能在 {{HTMLElement("textarea")}} 工作。对于后台脚本，任何元素都可被设置为内容可编辑模式。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/intercept_http_requests/index.html b/files/zh-cn/mozilla/add-ons/webextensions/intercept_http_requests/index.html new file mode 100644 index 0000000000..1e1c155db3 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/intercept_http_requests/index.html @@ -0,0 +1,158 @@ +--- +title: 拦截HTTP请求 +slug: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +tags: + - Add-ons + - Extensions + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +--- +<div>{{AddonSidebar}}</div> + +<p>使用 {{WebExtAPIRef("webRequest")}} API可以拦截HTTP请求。该API允许开发者植入一个侦听器用以侦听各个阶段的HTTP请求。在侦听器中，你能：</p> + +<ul> + <li>获取请求及其返回的header和body</li> + <li>取消或重定向请求</li> + <li>修改请求及其返回的header</li> +</ul> + +<p>本文将探究<code>webRequest</code>模型的三种用法：</p> + +<ul> + <li>登陆请求的构造</li> + <li>重定向请求</li> + <li>修改请求的header</li> +</ul> + +<h2 id="记录请求的_URL">记录请求的 URL</h2> + +<p>新建一个名为<code>“</code>requests<code>”</code>的目录，在其中新建一个名为<code>“</code>manifest.json<code>”</code>的文件，文件包含如下 内容 ：</p> + +<pre class="brush: json">{ + "description": "Demonstrating webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "<all_urls>" + ], + + "background": { + "scripts": ["background.js"] + } +}</pre> + +<p>接着新加一个名为<code>“</code>background.js<code>”</code>的文件，包含如下内容：</p> + +<pre class="brush: js">function logURL(requestDetails) { + console.log("Loading: " + requestDetails.url); +} + +chrome.webRequest.onBeforeRequest.addListener( + logURL, + {urls: ["<all_urls>"]} +); + +</pre> + +<p>这里我们在请求开始之前用{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}调用<code>logURL()</code>函数。<code>logURL()</code><code>函数</code>抓取从事件对象发出的请求中的URL，然后将其打印到浏览器的控制台窗口中。<a href="/en-US/Add-ons/WebExtensions/Match_patterns">参数</a><code>{urls: ["<all_urls>"]}</code>表示拦截发往所有URL的HTTP请求。</p> + +<p>测试方法是：<a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">安装该WebExtension</a>， <a href="/en-US/docs/Tools/Browser_Console">打开浏览器的控制台</a>，然后开启某个网页即可。在浏览器控制台中就能见到浏览器请求所有资源的URL：</p> + +<p>{{EmbedYouTube("X3rMgkRkB1Q")}}</p> + +<h2 id="重定向请求">重定向请求</h2> + +<p>现在让我们用<code>webRequest</code>来重定向HTTP请求。首先将manifest.json文件内容替换如下：</p> + +<pre class="brush: json">{ + + "description": "Demonstrating webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "webRequestBlocking", + "https://mdn.mozillademos.org" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>这里唯一的变化是<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a></code>里 新增了<code>“</code><code>webRequestBlocking</code><code>”</code>项。新增这个权限是为了随时都能修改请求。</p> + +<p>下一步替换<code>“</code>background.js<code>”</code>文件内容如下：</p> + +<pre class="brush: js">var pattern = "https://mdn.mozillademos.org/*"; + +function redirect(requestDetails) { + console.log("Redirecting: " + requestDetails.url); + return { + redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif" + }; +} + +chrome.webRequest.onBeforeRequest.addListener( + redirect, + {urls:[pattern], types:["image"]}, + ["blocking"] +);</pre> + +<p>此外在请求构造出来之前我们用{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}事件侦听器来实现URL替换。侦听器将会用<code>redirectUrl</code>指定的内容替换原有的URL。</p> + +<p>这次我们不拦截所有的请求：<code>{urls:[pattern], types:["image"]}</code>选项告诉浏览器必须同时满足如下两点的请求才会被拦截：(1)在<code>“</code> https://mdn.mozillademos.org/<code>”</code>之下的URL； (2)图片资源。该功能的更多说明参见{{WebExtAPIRef("webRequest.RequestFilter")}}。</p> + +<p>刚才我们忽略了<code>“blocking</code><code>”</code>选项。要修改请求<code>就要用到“blocking</code><code>”</code>选项，该选项让侦听器函数阻塞住发往网络请求，浏览器将会等待侦听器返回才会继续处理。阅读{{WebExtAPIRef("webRequest.onBeforeRequest")}}以了解更多有关<code>“blocking</code> <code>”</code>的细节。.</p> + +<p>测试时打开MDN上的一个包含诸多图片的页面（如<a href="https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor">https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor</a> ），重新加载<a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">WebExtension</a>，然后重新加载这个页面：</p> + +<p>{{EmbedYouTube("ix5RrXGr0wA")}}</p> + +<h2 id="修改请求报头">修改请求报头</h2> + +<p>最后我们将使用<code>webRequest</code>修改请求报头。在这个例子中我们将修改 "User-Agent"报头，使得在浏览" http://useragentstring.com/"网站下的网页时可以识别浏览器Opera 12.16。</p> + +<p>"manifest.json" 可以与上一个例子相同。</p> + +<p>修改"background.js" 如下:</p> + +<pre class="brush: js">var targetPage = "http://useragentstring.com/*"; + +var ua = "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16"; + +function rewriteUserAgentHeader(e) { + for (var header of e.requestHeaders) { + if (header.name.toLowerCase() == "user-agent") { + header.value = ua; + } + } + return {requestHeaders: e.requestHeaders}; +} + +chrome.webRequest.onBeforeSendHeaders.addListener( + rewriteUserAgentHeader, + {urls: [targetPage]}, + ["blocking", "requestHeaders"] +);</pre> + +<p>在请求报头被发送前，我们使用 {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} 事件监听器来运行一个函数。</p> + +<p>只有在向匹配的URL格式的网页发送请求时，这个监听函数才会运行。 还需注意的是，我们再次使用了<code>"blocking"</code>选项。我们还使用了<code>"requestHeaders"</code>选项，使监听器可以传递我们希望的请求报头数组。了解更多{{WebExtAPIRef("webRequest.onBeforeSendHeaders")}}的信息。</p> + +<p>侦听函数在请求报头数组中寻找 "User-Agent" 报头，用<code>ua</code>变量替换它的值，然后返回修改后的报头数组 。现在这个修改后的数组会被发送到服务器。</p> + +<p>要测试它,先打开 <a href="http://useragentstring.com/">useragentstring.com</a>网址，检查标识浏览器是否为火狐浏览器 。然后加载附加组件， 刷新网址，再次检查标识浏览器，你会发现火狐浏览器被定义为 Opera了：</p> + +<p>{{EmbedYouTube("SrSNS1-FIx0")}}</p> + +<h2 id="了解更多">了解更多</h2> + +<p>学习你能使用的所有<code>webRequest</code> API，查看 <a href="/en-US/Add-ons/WebExtensions/API/WebRequest">reference documentation</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/internationalization/index.html b/files/zh-cn/mozilla/add-ons/webextensions/internationalization/index.html new file mode 100644 index 0000000000..88971977ae --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/internationalization/index.html @@ -0,0 +1,394 @@ +--- +title: 国际化 +slug: Mozilla/Add-ons/WebExtensions/Internationalization +translation_of: Mozilla/Add-ons/WebExtensions/Internationalization +--- +<div>{{AddonSidebar}}</div> + +<p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> API 有一个相当方便的模块可用于附加组件的国际化（<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a>）。我们将在本文中探讨其功能，并为它的运作方式提供一个实例。WebExtensions 的 i18n 系统类似常见的 i18n 用途 JavaScript 库，例如 <a href="http://i18njs.com/">i18n.js</a>。</p> + +<div class="note"> +<p>本文中的 WebExtension 实例 <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 可在 GitHub 上查阅。在您阅读下列章节时，可参照它的代码。</p> +</div> + +<h2 id="剖析一个国际化的_WebExtension">剖析一个国际化的 WebExtension</h2> + +<p>一个国际化的 WebExtension 与其他 WebExtension 一样可以包含各类功能，如<a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">后台脚本</a>、<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">内容脚本</a>等，但它也有些额外的部分，从而允许它适应不同的语言区域。目录树大致如下：</p> + +<ul class="directory-tree"> + <li>webextension-根目录/ + <ul> + <li>_locales + <ul> + <li>en + <ul> + <li>messages.json + <ul> + <li>英语消息（字符串）</li> + </ul> + </li> + </ul> + </li> + <li>de + <ul> + <li>messages.json + <ul> + <li>德语消息（字符串）</li> + </ul> + </li> + </ul> + </li> + <li>等其他语言</li> + </ul> + </li> + <li>manifest.json + <ul> + <li>含按语言区域而定的元数据</li> + </ul> + </li> + <li>myJavascript.js + <ul> + <li>含用于检索浏览器语言区域、特定语言环境的消息等的 JavaScript。</li> + </ul> + </li> + <li>myStyles.css + <ul> + <li>含按语言区域而定的 CSS</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>让我们逐项探讨这些新特性，因为下列每个章节都是你在国际化 WebExtension 时所要遵循的步骤。</p> + +<h2 id="在__locales_中提供本地化的字符串">在 _locales 中提供本地化的字符串</h2> + +<div class="pull-aside"> +<div class="moreinfo">你可以使用<a href="http://r12a.github.io/apps/subtags/">Language subtag lookup page</a>上的查找工具查询语言子标签。请注意，你需要搜索语言的英语名称。</div> +</div> + +<p>每个 i18n 系统都需要你提供想支持的各语言区域的已翻译字符串。 在 WebExtensions 中，这些字符串放在一个名为 <code>_locales</code> 的目录中，<code>_locales</code> 目录则位于扩展的根目录。每个语言区域都有一个名叫 <code>messages.json</code> 的文件，其中包含相应的字符串（在 WebExtension 中称作“消息”），这个文件放在 <code>_locales</code> 的子目录下，子目录以对应语言区域的语言子标签来命名。</p> + +<p>注意，如果子标签包含一个基本语言和一个区域变种，那么语言与变种之间通常会以连字号隔开，例如 "en-US"。但作为 <code>_locales</code> 的子目录，<strong>它必须采用下划线来分隔</strong>，如 "en_US"。</p> + +<p>因此<a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n/_locales" title="1">在我们这个示例应用</a>中，我们有如下几个目录："en"（英语）、"de"（德语）、"nl"（荷兰语）以及 "ja"（日语）。每个目录都包含一个 <code>messages.json</code> 文件。</p> + +<p>现在我们来看其中一个文件（<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/_locales/en/messages.json">_locales/en/messages.json</a>）的结构：</p> + +<pre class="brush: json">{ + "extensionName": { + "message": "Notify link clicks i18n", + "description": "Name of the extension." + }, + + "extensionDescription": { + "message": "Shows a notification when the user clicks on links.", + "description": "Description of the extension." + }, + + "notificationTitle": { + "message": "Click notification", + "description": "Title of the click notification." + }, + + "notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } + } +}</pre> + +<p>这个文件是一个标准的 JSON — 其中每个成员都是一个带有名称的对象，里面包含一个 <code>message</code>（消息）和一个 <code>description</code>（描述）。这些项目都是字符串。<code>$URL$</code> 是一个占位符，在 WebExtension 调用 <code>notificationContent</code> 成员时将被一个子字符串替换。你将在接下来的{{anch("从 JavaScript 检索消息字符串")}}章节中了解如何使用。</p> + +<div class="note"> +<p><strong>注意：</strong>你可以在 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">Locale-Specific Message reference</a> 里找到更多有关 <code>messages.json</code> 文件中内容的信息。</p> +</div> + +<h2 id="国际化_manifest.json">国际化 manifest.json</h2> + +<p>要国际化你的 manifest.json，有几项任务要完成。</p> + +<h3 id="在_manifests_中检索本地化的字符串">在 manifests 中检索本地化的字符串</h3> + +<p>你的 <a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/manifest.json">manifest.json</a> 包含显示给用户的字符串，例如附加组件的名称和描述。如果你将这些字符串国际化，并将合适的翻译放到 messages.json 中，则用户将根据当前语言区域看到适当的字符串翻译。</p> + +<p>要将这些字符串国际化，按如下格式指定：</p> + +<pre class="brush: json">"name": "__MSG_extensionName__", +"description": "__MSG_extensionDescription__",</pre> + +<p>我们在在这里检索到消息字符串依赖于浏览器的语言区域，而不仅仅是一个静态字符串。</p> + +<p>要这样调用消息字符串，你需要用的方式为：</p> + +<ol> + <li>两个下划线，接着是</li> + <li>字符串 "MSG"，接着是</li> + <li>一个下划线，接着是</li> + <li>你想调用的在 <code>messages.json</code> 中定义的消息名称，接着是</li> + <li>两个下划线</li> +</ol> + +<pre><strong>__MSG_</strong> + <em>messageName</em> + <strong>__</strong></pre> + +<h3 id="指定默认语言区域">指定默认语言区域</h3> + +<p>你还必须在你的 manifest.json 中指定另一个字段，它就是 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a>：</p> + +<pre class="brush: json">"default_locale": "en"</pre> + +<p>如果扩展没有包含浏览器当前语言区域的本地化字符串，则会使用该字段所指定的默认语言区域。任何浏览器语言区域下不可用的消息字符串都将用默认语言区域的字符串替换。有关浏览器如何选择字符串，还有一些细节需要注意 — 详见{{anch("选择本地化的字符串")}}。</p> + +<h2 id="依赖语言区域的_CSS">依赖语言区域的 CSS</h2> + +<p>您还可以在扩展的 CSS 文件中检索本地化的字符串。例如，您可能想构建一个依赖于语言区域的 CSS 规则，如下所示：</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_extensionName__/header.png); +}</pre> + +<p>这很有用，不过在这种情况下使用{{anch("预定义消息")}}来处理或许会更好。</p> + +<h2 id="从_JavaScript_检索消息字符串">从 JavaScript 检索消息字符串</h2> + +<p>所以，您应该已经建立起您的消息字符串和 manifest。现在只需开始从 JavaScript 调用这些消息字符串，以便你的扩展尽可能多地表述适合的语言。实际上 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n API</a> 相当简单，只需包含以下四个主要的方法（method）：</p> + +<ul> + <li>你最常用的很可能是 {{WebExtAPIRef("i18n.getMessage()")}} — 使用此方法可以检索一个指定的语言字符串。下方有特定的用法示例。</li> + <li>{{WebExtAPIRef("i18n.getAcceptLanguages()")}} 和 {{WebExtAPIRef("i18n.getUILanguage()")}} 这两个方法可以在你需要根据语言区域自定义用户界面时使用 — 或许你希望根据用户想要的语言在首选项列表更高层显示首选项，或只显示和特定语言有关的文化信息，又或是按浏览器语言显示格式化过的日期。</li> + <li>{{WebExtAPIRef("i18n.detectLanguage()")}} 这个方法可以用来检测用户提交内容的语言，并将其正确格式化。</li> +</ul> + +<p>在我们的 <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 示例中，<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/background-script.js">后台脚本</a>包含下列代码：</p> + +<pre class="brush: js">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url);</pre> + +<p>第一行是从最适合当前语言区域的可用 <code>messages.json</code> 文件中检索 <code>notificationTitle</code> <code>message</code> 字段。第二行与第一行类似，但它被传递了一个 URL 作为第二参数。怎么一回事？它就是你所指定的要替代 <code>notificationContent</code> 消息字段里 <code>$URL$</code> 占位符的内容：</p> + +<pre class="brush: json">"notificationContent": { + "message": "您点击了 $URL$。", + "description": "告诉用户点击了哪个链接。", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } +} +</pre> + +<p><code>"placeholders"</code> 这个成员定义了所有的占位符，以及它们所检索的来源。<code>"url"</code> 这个占位符指定了其内容取自 $1，它就是<code> getMessage() 第二个参数里的第一个值。由于占位符就叫做</code> <code>"url"，我们就在实际的消息字符串中用</code> <code>$URL$</code> 调用它（<code>"name"</code> 用<code> $NAME$</code> 调用也是一样的，以此类推）。对于多个占位符，你可以将其置于数组内，并作为第二个参数传递到 {{WebExtAPIRef("i18n.getMessage()")}} — <code>[a, b, c]</code> 可替换为 <code>$1</code>, <code>$2</code>, and <code>$3，以此类推，并置于</code> <code>messages.json</code> 内。</p> + +<p>接下来我们看一个例子：在 <code>en/messages.json 文件中</code>原始的 <code>notificationContent</code> 消息字符串如下： in the <code>en/messages.json</code> file is</p> + +<pre>您点击了 $URL$。</pre> + +<p>我们可以看到链接点击后会打开 <code>https://developer.mozilla.org。</code>在 {{WebExtAPIRef("i18n.getMessage()")}} 调用后，第二个参数的内容就变成了 messages.json 里的 <code>$1</code>，并替换定义在 <code>"url" 占位符里的</code> <code>$URL$</code> 这个占位符。所以最后的消息字符串就变成了：</p> + +<pre>您点击了 https://developer.mozilla.org。</pre> + +<h3 id="直接占位符的使用">直接占位符的使用</h3> + +<p>你可以直接将变量<code>（$1</code>, <code>$2</code>, <code>$3</code> 等）插入消息字符串，例如我们可以将上述的<code> "notificationContent"</code> 成员重写为：</p> + +<pre class="brush: json">"notificationContent": { + "message": "你点击了 $1。", + "description": "告诉用户点击了哪个链接。" +}</pre> + +<p>这么做看起来似乎更快捷，也没那么复杂，但另一种方法（使用 <code>"placeholders"）更切实际，因为提供一个占位符名</code>（例如 <code>"url"</code>）和 example 可帮你记住占位符是什么 — 在你代码写了一个礼拜后，你很可能忘了 <code>$1</code>–<code>$8</code> 表示什么，但你或许记得起来占位符名表示什么。</p> + +<h3 id="替换硬编码">替换硬编码</h3> + +<p>也可以在占位符中包含硬编码的字符串，从而每次都使用相同的值，而不是从代码中的变量获取值。例如：</p> + +<pre class="brush: json">"mdn_banner": { + "message": "For more information on web technologies, go to $MDN$.", + "description": "Tell the user about MDN", + "placeholders": { + "mdn": { + "content": "https://developer.mozilla.org/" + } + } +}</pre> + +<p>在本例中我们只是硬编码了占位符的内容，而不是从 <code>$1 这样的变量值中获取它。有时候你会遇到消息文件非常复杂，或者如果你想将文件里的不同值分离开来以便字符串可读性更好，</code>这种情况下它会很有用，这些值可通过编程来访问。</p> + +<p>此外，你可使用这样的替代方式指定不想被翻译的一部分字符串，例如人名或公司名。</p> + +<h2 id="选择本地化的字符串">选择本地化的字符串</h2> + +<p>语言区域可以仅使用语言代码指定，例如 <code>fr</code> 或 <code>en</code>，也可以进一步限定区域代码，例如 <code>en_US</code> 或 <code>en_GB</code>，其描述了使用相同基础语言的区域变体。当您向 i18n 系统询问一个字符串时，它将使用以下算法选择一个字符串：</p> + +<ol> + <li>如果有精确匹配当前语言区域的 <code>messages.json</code> 文件，并且它包含该字符串，则返回它。</li> + <li>否则，如果当前语言区域有合格区域（例如 <code>en_US</code>）并且有一个无区域限定的 <code>messages.json</code> 文件（例如 <code>en</code>）且包含该字符串，则返回它。</li> + <li>否则，如果 <code>manifest.json 里包含</code> <code>default_locale</code> 所对应的 <code>messages.json</code> 文件且包含该字符串，则返回它。</li> + <li>否则，返回一个空字符串。</li> +</ol> + +<p>参见下列示例：</p> + +<ul class="directory-tree"> + <li>webextension-root-directory/ + <ul> + <li>_locales + <ul> + <li>en_GB + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + en + + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "color", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + </li> + <li>fr + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "<span lang="fr">couleur</span>", "description": "Color." }, ...}</code></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>假设 <code>default_locale</code> 是设为 <code>fr</code>，而浏览器的语言环境为 <code>en_GB</code>：</p> + +<ul> + <li>如果该附加组件调用 <code>getMessage("colorLocalised")</code>，它将返回 "colour"。</li> + <li>如果 "colorLocalised" 没有在 <code>en_GB</code> 中提供，那么 <code>getMessage("colorLocalised")</code> 将返回 "color" 而不是 "couleur".</li> +</ul> + +<h2 id="预定义消息">预定义消息</h2> + +<p>i18n 模块为我们提供了一些预定义的消息，我们可以用之前在 {{anch("Calling message strings from manifests and extension CSS")}} 中看到的相同的方式调用。例如：</p> + +<pre>__MSG_extensionName__</pre> + +<p>预定义的消息使用完全相同的语法，例如在消息名称之前使用 <code>@@</code></p> + +<pre>__MSG_@@ui_locale__</pre> + +<p>下表显示了各个可用的预定义消息。</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">消息名</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>@@extension_id</code></td> + <td>扩展或应用的 ID；你可以使用该字符串构建 URL，用于扩展内部的资源。甚至未本地化的扩展也可以使用该消息。<br> + <strong>注意：</strong>该消息无法在 manifest 文件中使用。</td> + </tr> + <tr> + <td><code>@@ui_locale</code></td> + <td>当前的语言区域；你可以使用该字符串构建语言区域特有的 URL。</td> + </tr> + <tr> + <td><code>@@bidi_dir</code></td> + <td>当前语言区域对应的文本书写方向，可以是 "ltr"，例如英语这样的从左到右书写的语言，或"rtl"，例如阿拉伯语这样的从右到左书写的语言。</td> + </tr> + <tr> + <td><code>@@bidi_reversed_dir</code></td> + <td>如果 <code>@@bidi_dir</code> 是 "ltr"，则是 "rtl"，否则是 "ltr"。</td> + </tr> + <tr> + <td><code>@@bidi_start_edge</code></td> + <td>如果 <code>@@bidi_dir</code> 是 "ltr"，则是 "left"，否则是 "right"。</td> + </tr> + <tr> + <td><code>@@bidi_end_edge</code></td> + <td>如果<code> @@bidi_dir</code> 是 "ltr"，则是 "right"，否则是 "left"。</td> + </tr> + </tbody> +</table> + +<p>回到我们之前的例子，像下面这样写更有意义：</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_@@ui_locale__/header.png); +}</pre> + +<p>现在我们可以保存本地指定的图片，目录则可以根据所支持的不同语言区域进行匹配，例如 en、de 等 — 这样显得更有意义多了。</p> + +<p>让我们看看一个在 CSS 文件中使用 <code>@@bidi_*</code> 消息的例子：</p> + +<pre class="brush: css">body { + direction: __MSG_@@bidi_dir__; +} + +div#header { + margin-bottom: 1.05em; + overflow: hidden; + padding-bottom: 1.5em; + padding-__MSG_@@bidi_start_edge__: 0; + padding-__MSG_@@bidi_end_edge__: 1.5em; + position: relative; +}</pre> + +<p>对于从左到右语言（例如英语、中文），该 CSS 声明调用在上面预定义的消息，最终转换为下列代码：</p> + +<pre class="brush: css">direction: ltr; +padding-left: 0; +padding-right: 1.5em; +</pre> + +<p>而对于从右到左语言（如阿拉伯语），则将得到：</p> + +<pre class="brush: css">direction: rtl; +padding-right: 0; +padding-left: 1.5em;</pre> + +<h2 id="测试你的_WebExtension">测试你的 WebExtension</h2> + +<p>从 Firefox 45 开始，你可以临时安装磁盘上的 WebExtensions — 另见<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Packaging_and_installation#Loading_from_disk">从磁盘加载。</a>按上述步骤操作，然后尝试我们的 <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> WebExtension。访问你喜欢的任何网站，然后点一下链接，查看是否有通知出现来显示所点击的链接网址。</p> + +<p>接下来，将 Firefox 的语言区域更改为你想测试的扩展支持的某个语言区域。</p> + +<ol> + <li>在 Firefox 中打开 "about:config"，找到 <code>general.useragent.locale</code> 首选项。</li> + <li>双击该首选项（或按回车）以选择它，输入你想测试的语言环境的语言代码，然后点击“确定”（或按回车）。我们的示例扩展支持“en”（英语）、“de”德语（）、“nl”（荷兰语）和“ja”日语。</li> + <li>重启你的浏览器以完成更改。</li> +</ol> + +<div class="note"> +<p><strong>Note</strong>: 这个方法可以用来修改浏览器的语言区域，即使你未安装过该语言区域对应的<a href="https://addons.mozilla.org/en-US/firefox/language-tools/">语言包</a>。这样的话你就可以将浏览器用户界面调整显示为你的默认语言。</p> +</div> + +<ol> +</ol> + +<p>再次从磁盘临时加载该扩展，然后测试你的新语言区域：</p> + +<ul> + <li>再次访问 "about:addons" — 你现在应该看到该附加组件已列出其图标，以及相应语言的名称和描述。</li> + <li>再次测试你的 WebExtension。在我们的例子中，你会转到另一个网站并点击一个链接，以查看该通知现在是否以相应语言显示。</li> +</ul> + +<p>{{EmbedYouTube("R7--fp5pPGg")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/author/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/author/index.html new file mode 100644 index 0000000000..a688478298 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/author/index.html @@ -0,0 +1,40 @@ +--- +title: 作者 - author +slug: Mozilla/Add-ons/WebExtensions/manifest.json/author +tags: + - 作者 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/author +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>字符串（String）</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>非强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"author": "小明"</pre> + </td> + </tr> + </tbody> +</table> + +<p>附加组件的作者, 用于在浏览器用户界面上显示, 这样别人下载安装使用该附加组件的时候, 就能看见你的大名了.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"author": "小明"</pre> + +<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.manifest.author")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/background/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/background/index.html new file mode 100644 index 0000000000..df4e1fc9ae --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/background/index.html @@ -0,0 +1,88 @@ +--- +title: 后台 - background +slug: Mozilla/Add-ons/WebExtensions/manifest.json/background +tags: + - 后台 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/background +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Type</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>不强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"background": { + "scripts": ["background.js"] +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>通过background 键来给您的扩展程序引入一个或者多个后台脚本文件，以及一个可选的后台页面文件。</p> + +<p>后台脚本放置的是需要长期保持状态，或者需要执行长期的操作，并且与任意特定网页或者浏览器窗口的生命周期无关的代码。</p> + +<p>后台脚本会在扩展程序被加载后立即被加载，并且一直保持被加载状态，只有在扩展程序被禁止或者卸载的时候才停止运行。只要您获得了必要的许可<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>，您可以在该脚本中使用任意的扩展程序API。</p> + +<p>浏览<a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_pages">Anatomy of a WebExtension</a>中的Background pages部分以获取更多的细节。</p> + +<p>background 键最多只能拥有以下的两个属性，两个属性都是可选属性：</p> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>"scripts"</code></td> + <td> + <p>一个字符串数组，数组中的每个字符串都是JavaScript源文件相对于manifest.json的相对路径，JavaScript源文件便是些被包含在扩展程序中的后台脚本文件。</p> + + <p>脚本共享相同的全局窗口</p> + + <p>脚本按照在数组中的顺序进行加载</p> + + <p><strong>注意在低于Firefox 50版本的浏览器下会出现一个问题：</strong>当Firefox debugger已经打开时，脚本并不能总是按照数组中定义的顺序进行加载。若要解决这个问题，您可以使用page属性，用<script>标签将后台脚本文件从页面中加载进来。这个问题已经在Firefox 50中被修复。</p> + </td> + </tr> + <tr> + <td><code>"page"</code></td> + <td> + <p>如果您仅仅指定了“scripts”属性，将生成一个空白的页面来运行指定的脚本。</p> + + <p>如果您需要在页面中显示某些特定的内容，您可以使用“page”属性来定义自己的页面。</p> + + <p dir="ltr" id="tw-target-text">如果您使用此属性，您仍然可以使用“script”属性来指定后台脚本，但您也可以就像在普通网页中一样在页面中包含自己的脚本。</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="示例">示例</h2> + +<p>加载2个后台脚本文件.</p> + +<pre class="brush: json"> "background": { + "scripts": ["jquery.js", "my-background.js"] + }</pre> + +<p>加载1个自定义的后台页面文件.</p> + +<pre class="brush: json"> "background": { + "page": "my-background.html" + }</pre> + +<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.manifest.background", 10)}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html new file mode 100644 index 0000000000..f2e1ff07d1 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html @@ -0,0 +1,209 @@ +--- +title: browser_action +slug: Mozilla/Add-ons/WebExtensions/manifest.json/browser_action +tags: + - Add-ons + - Extensions + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/browser_action +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">类型</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">是否必须</th> + <td>否</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json no-line-numbers"> +"browser_action": { + "browser_style": true, + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>浏览器按钮（browser action）指您的扩展在浏览器工具栏上所添加的按钮。该按钮有个图标，并可可选地拥有一个使用 HTML，CSS，和 JavaScript 指定内容的弹出窗口。</p> + +<p>如果您使用弹窗（popup），则该弹窗将在用户点击该按钮时打开，并且弹窗中你所提供的运行中的 JavaScript 将可处理用户与其的交互。如果您不使用弹窗，则会在用户点击该按钮时将点击事件传递给你扩展的 <a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a> 中。</p> + +<p>您同样可以使用 <a href="/zh-CN/Add-ons/WebExtensions/API/browserAction">browserAction API</a> 以编程的方式创建及控制浏览器按钮。</p> + +<h2 id="语法">语法</h2> + +<p><code>browser_action</code> 键是一个可能有以下任何属性的对象，均是可选：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">名称</th> + <th scope="col">类型</th> + <th scope="col">详细描述</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>browser_style</code></td> + <td><code>Boolean</code></td> + <td> + <div class="geckoVersionNote">Firefox 48 中新出现</div> + + <p>可选，默认为 <code>false</code>。</p> + + <p>使用此项来包含一个样式表以使其与浏览器 UI 和其它使用了 <code>browser_style</code> 属性的扩展外观上保持一致。虽然此键值默认为 <code>false</code>，还是建议您将其包含并设其为 <code>true</code>。</p> + + <p>在 Firefox 中，该样式表详阅 chrome://browser/content/extension.css，OS X 系统或见于 chrome://browser/content/extension-mac.css。</p> + + <p><a href="https://firefoxux.github.io/StyleGuide/#/controls">Firefox Style Guide</a> 记述了为获得特定样式您所能为弹窗中元素应用的 class。</p> + + <p><a href="https://github.com/mdn/webextensions-examples/tree/master/latest-download">latest-download</a> 中的示例扩展的弹窗使用了 <code>browser_style</code>。</p> + </td> + </tr> + <tr> + <td><code>default_area</code></td> + <td><code>String</code></td> + <td> + <div class="geckoVersionNote">Firefox 54 中新出现</div> + + <p>定义浏览器最初放置该按钮的位置。该字符串可能是以下四个值中的一个：</p> + + <ul> + <li>"navbar"：按钮会被放置到浏览器主工具栏中，与 URL 栏并肩。</li> + <li>"menupanel"：按钮会被放置到弹出面板中。</li> + <li>"tabstrip"：按钮会被放置到包含浏览器选项卡的工具栏中。</li> + <li>"personaltoolbar"：按钮会被放置到书签工具栏中。</li> + </ul> + + <p>该属性只有 Firefox 支持。</p> + + <p>这个属性是可选的，并默认为 "navbar"。</p> + + <p>扩展不能在其被安装后主动更改其按钮的位置，但用户可以使用浏览器内置的界面定制机制来移动按钮。</p> + </td> + </tr> + <tr> + <td><code>default_icon</code></td> + <td><code>Object</code> 或 <code>String</code></td> + <td> + <p>使用此项以指定一个或多个 browser action 之图标。该图标默认显示在浏览器工具栏里。</p> + + <p>图标使用相对于 manifest.json 文件本身的 URL 指定。</p> + + <p>你可以通过提供一个字符串以指定单个的图标文件：</p> + + <pre class="brush: json no-line-numbers"> +"default_icon": "path/to/geo.svg"</pre> + + <p>要指定多个不同大小的图标，则在此指定一个对象。每个属性的名字是以像素记的该图标的高，且其必须被转换为一个整数。值为其 URL。示例：</p> + + <pre class="brush: json no-line-numbers"> + "default_icon": { + "16": "path/to/geo-16.png", + "32": "path/to/geo-32.png" + }</pre> + + <p>参阅 <a href="/zh-CN/Add-ons/WebExtensions/manifest.json/browser_action#选择图标大小">选择图标大小</a> 以获得此项的更多指引。</p> + </td> + </tr> + <tr> + <td><code>default_popup</code></td> + <td><code>String</code></td> + <td> + <p>指向包含弹窗信息的 HTML 文件之路径</p> + + <p>该 HTML 文件可能会使用 <code><a href="/zh-CN/docs/Web/HTML/Element/link"><link></a></code> and <code><a href="/zh-CN/docs/Web/HTML/Element/script"><script></a></code> 元素来包含 CSS 和 JavaScript，就像普通网页一样。</p> + + <p>与普通网页不同，弹窗中运行的 JavaScript 能访问所有的 <a href="/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a>（当然，仅对于拥有适当<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>的扩展）。</p> + + <p>这是一个<a href="/zh-CN/Add-ons/WebExtensions/Internationalization#国际化_manifest.json">可本地化属性</a>。</p> + </td> + </tr> + <tr> + <td><code>default_title</code></td> + <td><code>String</code></td> + <td> + <p>按钮的工具提示，在用户将鼠标移到其上时显示。</p> + + <p>这是一个<a href="/zh-CN/Add-ons/WebExtensions/Internationalization#国际化_manifest.json">可本地化属性</a>。</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="选择图标大小">选择图标大小</h2> + +<p>浏览器按钮的图标在不同上下文中可能需要以不同大小显示：</p> + +<ul> + <li>图标默认是在浏览器工具栏中显示，但用户能把它挪到浏览器菜单面板里（那个在用户点击 “汉堡” 图标时打开的面板）。工具栏里的图标比菜单面板里的图标小。</li> + <li>在像 Retina 屏的高密度显示器上，图标大要两倍。</li> +</ul> + +<p>如果浏览器在给定的情况下找不到正确尺寸的图标，它就会选最匹配的并对其缩放。缩放可能会使图标模糊，所以一件很重要的事情就是小心地选择图标尺寸。</p> + +<p>对此有两种常用方法。你可以以 SVG 文件的形式提供单个图标，然后它就会被正确地缩放：</p> + +<pre class="brush: json no-line-numbers">"default_icon": "path/to/geo.svg"</pre> + +<p>或者，您可以提供几个不同尺寸的图标，浏览器将选择最佳匹配。</p> + +<p>Firefox 中：</p> + +<ul> + <li>工具栏中图标的默认宽高为 16 * <code><a href="/zh-CN/docs/Web/API/Window/devicePixelRatio">window.devicePixelRatio</a></code>。</li> + <li>菜单面板中图标的默认宽高为 32 * <code><a href="/zh-CN/docs/Web/API/Window/devicePixelRatio">window.devicePixelRatio</a></code>。</li> +</ul> + +<p>所以你可以选定精确匹配的图标，不论普通屏还是 Retina 屏的显示，都仅需要提供三个图标文件，并把它们像这样确定下来：</p> + +<pre class="brush: json no-line-numbers"> "default_icon": { + "16": "path/to/geo-16.png", + "32": "path/to/geo-32.png", + "64": "path/to/geo-64.png" + }</pre> + +<p>如果 Firefox 找不到其需要的精确匹配的尺寸，则它会选择大于理想尺寸的已指定的最小图标。如果所有图标都小于理想尺寸，它就将选择已指定的最大图标。</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json no-line-numbers">"browser_action": { + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + } +}</pre> + +<p>只有一个图标的浏览器按钮，指定了 2 种不同大小。其扩展的 background scripts 能接收用户点击其图标时的点击事件代码大概像这样：</p> + +<pre class="brush: js no-line-numbers"> browser.browserAction.onClicked.addListener(handleClick);</pre> + +<pre class="brush: json">"browser_action": { + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" +}</pre> + +<p>浏览器按钮具有一个图标，一个标题，还有一个弹窗。弹窗会在用户点击按钮时出现。</p> + +<p>对于一个简易，但是完整，使用了浏览器按钮的扩展，参见<a href="/zh-CN/Add-ons/WebExtensions/Your_second_WebExtension">演练教程</a>。</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>{{Compat("webextensions.manifest.browser_action", 10)}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html new file mode 100644 index 0000000000..5d200de3bd --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html @@ -0,0 +1,66 @@ +--- +title: applications +slug: Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings +tags: + - 插件 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>注意这个key不被Blink-based浏览器(Google Chrome和Opera)支持。如果你在插件中包含了这个key，当在这些浏览器中调用时虽然能用但是会显示警告。</p> +</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">类型</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>通常不做强制性要求（详细参见<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_Add-on_ID">When do you need an Add-on ID</a><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/applications#When_do_I_need_the_applications_key">?</a>)。在Firefox 48版本之前为强制要求。</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"applications": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0" + } +}</pre> + </td> + </tr> + </tbody> +</table> + +<p><code>applications</code> key包含特定于主机应用程序的键。</p> + +<p>目前只包含了一个key：<code>gecko</code>，其中包含了4个attributes:</p> + +<ul> + <li><code>id</code>即<a href="https://developer.mozilla.org/zh-CN/Add-ons/Install_Manifests#id">extension ID</a>。从Firefox 48起为可选项，在此之前为强制必须项。参看<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">WebExtensions and the Add-on ID</a>来确认何时需要定义附加组件ID。</li> + <li><code>strict_min_version</code>: Gecko所能支持的最小版本号。不允许使用"*"来定义版本号。默认值为 "42a1"。{{gecko_minversion_inline("45")}}</li> + <li><code>strict_max_version</code>: Gecko所能支持的最大版本号。如果安装或运行附加组件的Firefox版本号高于这个最大版本号，附加组件将不能运行或不允许被安装。默认值为"*"，意思为不对最大版本号做检查。{{gecko_minversion_inline("45")}}</li> + <li><code>update_url</code>为链接到<a href="/zh-CN/Add-ons/Updates">add-on update manifest</a>的链接。注意链接必须以"https"开头。这是为了使你自己就能够管理附加组件的更新(如不通过AMO)。{{gecko_minversion_inline("45")}}</li> +</ul> + +<h2 id="Chrome不兼容性">Chrome不兼容性</h2> + +<p>你不能在Chrome附加组件中使用这个key。</p> + +<h2 id="示例">示例</h2> + +<p>示例中包含了所有可能的key。注意你通常不会包含<code>strict_max_version</code>或<code>update_url</code>key在大部分附加组件中。</p> + +<pre class="brush: json">"applications": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0", + "strict_max_version": "50.*", + "update_url": "https://example.com/updates.json" + } +}</pre> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.html new file mode 100644 index 0000000000..9fab86d4b9 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.html @@ -0,0 +1,216 @@ +--- +title: content_scripts +slug: Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts +tags: + - WebExtensions + - 扩展 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">类型</th> + <td>数组（<code>Array）</code></td> + </tr> + <tr> + <th scope="row">必要</th> + <td>否</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } +]</pre> + </td> + </tr> + </tbody> +</table> + +<p>让浏览器将<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a>加载到匹配网址的网站上</p> + +<p>此键（content_scripts）是一个数组，每个项目都是一个满足下列条件的对象：</p> + +<ul> + <li> + <p><strong>必须</strong>包含一个名为<strong><code>matches</code></strong>的键，指定要加载脚本的URL的格式</p> + </li> + <li> + <p><strong>可以</strong>包含一个名为<strong><code>js</code></strong>或<strong><code>css</code></strong>的键，<span>列出要加载到匹配页面的脚本</span></p> + </li> + <li> + <p><strong>可以</strong>包含控制如何加载、何时加载等方面更精细的属性</p> + </li> +</ul> + +<p>下面表格列出了所有与你可以使用的键：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">名称</th> + <th scope="col">类型</th> + <th scope="col">描述</th> + </tr> + </thead> + <tbody> + <tr> + <td><a id="all_frames" name="all_frames"><code>all_frames</code></a></td> + <td><code>Boolean</code></td> + <td> + <p><code>true</code>: 将<code><a href="#js">js</a></code>和<code><a href="#css">css</a></code>注入该页面所有的框架（frame）中</p> + + <p><code>false</code>: 仅注入到顶层</p> + + <p>默认为false</p> + </td> + </tr> + <tr> + <td><a id="css" name="css"><code>css</code></a></td> + <td><code>Array</code></td> + <td> + <p>一个数组，包含将会被注入到匹配页面的CSS文件的路径（路径相对于manifest.json）。</p> + + <p>在加载DOM之前，文件将会按指定的顺序注入。</p> + </td> + </tr> + <tr> + <td><a id="exclude_globs" name="exclude_globs"><code>exclude_globs</code></a></td> + <td><code>Array</code></td> + <td> + <div class="geckoVersionNote">Firefox 自48版本开始支持globs</div> + + <p><span class="short_text" id="result_box" lang="zh-CN"><span>包含通配符的字符串数组。</span> <span>请参阅下面的<a href="#Matching_URL_patterns">匹配URL格式</a>。</span></span></p> + </td> + </tr> + <tr> + <td><a id="exclude_matches" name="exclude_matches"><code>exclude_matches</code></a></td> + <td><code>Array</code></td> + <td>一个<a href="/en-US/Add-ons/WebExtensions/match_patterns">match patterns</a>的数组，<span class="short_text" id="result_box" lang="zh-CN"><span>请参阅下面的<a href="#Matching_URL_patterns">匹配URL格式</a>。</span></span></td> + </tr> + <tr> + <td><a id="include_globs" name="include_globs"><code>include_globs</code></a></td> + <td><code>Array</code></td> + <td> + <div class="geckoVersionNote">Firefox 自48版本开始支持globs</div> + <span class="short_text" id="result_box" lang="zh-CN"><span>包含通配符的字符串数组。</span> <span>请参阅下面的<a href="#Matching_URL_patterns">匹配URL格式</a>。</span></span></td> + </tr> + <tr> + <td><a id="js" name="js"><code>js</code></a></td> + <td><code>Array</code></td> + <td> + <p>一个数组，包含将会被注入到匹配页面的JS文件的路径（路径相对于manifest.json）。</p> + + <p>文件将会按指定的顺序注入。这意味着如果你想在另一个脚本中包含jQuery，可以这样做：</p> + + <pre class="brush: json"> +<code>"js": ["jquery.js", "my-content-script.js"]</code></pre> + + <p>接下来，<code>"my-content-script.js"</code>可以使用jQuery.</p> + + <p><span class="short_text" id="result_box" lang="zh-CN"><span>文件将在<a href="#run_at">run_at</a>指定的时间注入。</span></span></p> + </td> + </tr> + <tr> + <td><a id="matches" name="matches"><code>matches</code></a></td> + <td><code>Array</code></td> + <td> + <p>一个<a href="/en-US/Add-ons/WebExtensions/match_patterns">match patterns</a>的数组，<span class="short_text" id="result_box" lang="zh-CN"><span>请参阅下面的<a href="#Matching_URL_patterns">匹配URL格式</a>。</span></span></p> + + <p><span class="short_text" id="result_box" lang="zh-CN"><span>这是唯一的必须键。</span></span></p> + </td> + </tr> + <tr> + <td><a id="run_at" name="run_at"><code>run_at</code></a></td> + <td><code>String</code></td> + <td> + <p>此选项指定在<a href="#js">“js”键</a>中的脚本何时被注入。您可以使用下列的三个字符串之一，每个字符串都代表加载文档过程中的不同状态。状态直接对应于{{domxref("Document/readyState", "Document.readyState")}}：</p> + + <ul> + <li>“<code>document_start</code>”：对应于正在加载。 <span>DOM仍在加载中。</span></li> + <li>“<code>document_end</code>”：对应于可交互。 <span>DOM已完成加载，但脚本和图像等资源可能仍在加载。</span></li> + <li>“<code>document_idle</code>”：对应完成。 <span>文档及其所有资源已完成加载。</span></li> + </ul> + + <p>默认值为“document_idle”。</p> + + <p>在所有情况下，<a href="#js">js键</a>中的文件都会在<a href="#css">css键</a>中的文件之后注入。</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="匹配URL格式">匹配URL格式</h2> + +<p>“content_scripts”键基于URL匹配将content scripts注入到网页上：如果网页的URL与键中的规则匹配，则将注入脚本。“content_scripts”中有四个属性，可以用于此规则：</p> + +<ul> + <li><code>matches</code>: 一个关于<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match patterns</a>的数组</li> + <li><code>exclude_matches:</code> 一个关于<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match patterns</a>的数组</li> + <li><code>include_globs</code>: 一个关于<a href="#globs">globs</a>的数组</li> + <li><code>exclude_globs:</code> 一个关于<a href="#globs">globs</a>的数组</li> +</ul> + +<p>要匹配这些属性之一，网址必须与其数组中的至少一个项匹配。例如，指定一个属性：</p> + +<pre class="brush: json">"matches": ["*://*.example.org/*", "*://*.example.com/*"]</pre> + +<p>"http://example.org/"和"http://example.com/"都将会匹配</p> + +<p>由于matches是唯一的强制性键，其他三个键用于进一步限制匹配的URL。要匹配作为一个整体的键，网址必须：</p> + +<ol> + <li>匹配matches属性</li> + <li>并且，匹配include_globs属性（如果有）</li> + <li>并且，不匹配<code>exclude_matches</code>属性（如果有）</li> + <li>并且，不匹配<code>exclude_globs</code>属性（如果有）</li> +</ol> + +<h3 id="globs">globs</h3> + +<div class="geckoVersionNote">Firefox 自48版本开始支持globs</div> + +<p>glob只是一个可以包含通配符的字符串。 有两种类型的通配符，您可以在一个glob中组合使用它们：</p> + +<ul> + <li>"*" 匹配零个或多个字符</li> + <li>"?" 匹配一个字符</li> +</ul> + +<p><code>例如，"*na?i"</code>会匹配<code>"illuminati"和</code><code>"annunaki"</code>，但不会匹配<code>"sagnarelli"</code>.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } +]</pre> + +<p>这会将content脚本“borderify.js”插入到“mozilla.org”或其任何子域下的所有页面，无论是HTTP还是HTTPS。</p> + +<pre class="brush: json"> "content_scripts": [ + { + "exclude_matches": ["*://developer.mozilla.org/*"], + "matches": ["*://*.mozilla.org/*"], + "js": ["jquery.js", "borderify.js"] + } + ]</pre> + +<p>这会将两个content脚本插入到“mozilla.org”及其任何子域（除“developer.mozilla.org”外）的所有页面中，无论是通过HTTP还是HTTPS。</p> + +<p>content脚本有相同的DOM视图，并按照它们在数组中出现的顺序注入，因此“borderify.js”可以访问由“jquery.js”添加的全局变量。</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.manifest.content_scripts")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/default_locale/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/default_locale/index.html new file mode 100644 index 0000000000..9dc13eec3f --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/default_locale/index.html @@ -0,0 +1,42 @@ +--- +title: default_locale +slug: Mozilla/Add-ons/WebExtensions/manifest.json/default_locale +tags: + - default_locale +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/default_locale +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Type</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>可能发生的：如果存在_locales子目录，必须存在，否则不存在。</td> + </tr> + <tr> + <th scope="row">例子</th> + <td> + <pre class="brush: json"> +"default_locale": "en"</pre> + </td> + </tr> + </tbody> +</table> + +<p>如果扩展名包含_locales目录，则该key必须存在，否则不得存在。它标识 _locales的一个子目录，该子目录将用于查找扩展名的默认字符串。</p> + +<p>见 <a href="/en-US/Add-ons/WebExtensions/Internationalization">国际化</a> 。</p> + +<h2 id="范例">范例</h2> + +<pre class="brush: json">"default_locale": "en"</pre> + +<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.manifest.default_locale")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/description/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/description/index.html new file mode 100644 index 0000000000..9081c82e10 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/description/index.html @@ -0,0 +1,43 @@ +--- +title: 描述 - description +slug: Mozilla/Add-ons/WebExtensions/manifest.json/description +tags: + - 描述 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/description +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>字符串</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>不强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"description": "附加组件的主要功能特性的简短描述."</pre> + </td> + </tr> + </tbody> +</table> + +<p>用于在用户下载安装使用界面中显示的一段简短的关于该附加组件的描述.</p> + +<p>关于本地化, 可查看 <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"description": "附加组件的主要功能特性的简短描述."</pre> + +<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.manifest.description")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/developer/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/developer/index.html new file mode 100644 index 0000000000..86c16d8da1 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/developer/index.html @@ -0,0 +1,48 @@ +--- +title: developer +slug: Mozilla/Add-ons/WebExtensions/manifest.json/developer +tags: + - Developer +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/developer +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>对象</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>非强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"developer": { + "name": "Walt Whitman", + "url": "https://en.wikipedia.org/wiki/Walt_Whitman" +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>插件开发者的名字和主页地址，用于显示在浏览器的用户界面中。</p> + +<p>该对象的两个属性都是可选的。如果存在“name”和“url”属性，将会分别覆盖<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/author">author</a>和<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url</a>键。这个对象仅仅允许指定一个开发者名字的主页地址。</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"developer": { + "name": "Walt Whitman", + "url": "https://en.wikipedia.org/wiki/Walt_Whitman" +}</pre> + +<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.manifest.developer")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/index.html new file mode 100644 index 0000000000..281382d382 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/index.html @@ -0,0 +1,140 @@ +--- +title: manifest.json +slug: Mozilla/Add-ons/WebExtensions/manifest.json +tags: + - JSON + - manifest.json +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json +--- +<div>{{AddonSidebar}}</div> + +<div class="blockIndicator note"> +<p>本文描述的是适用于 WebExtensions 的 manifest.json。若您正在寻找适用于 PWA 的 manifest.json 的有关信息，请参考这篇文章：<a href="/zh-CN/docs/Web/Manifest">Web App Manifest</a>。</p> +</div> + +<div><code>manifest.json</code> 是每个 WebExtension 唯一必须包含的元数据文件。</div> + +<p>通过使用 <code>manifest.json</code>，您可以指定扩展的基本元数据，例如名称和版本，还可以指定扩展各个方面的功能（例如后台脚本，内容脚本和某些浏览器行为）。</p> + + +<p>它是一个允许使用 "<code>//</code>" 撰写单行注释的、特殊的 <a href="/zh-CN/docs/Glossary/JSON">JSON</a> 文件。</p> + +<h2 id="manifest.json_键列表">manifest.json 键列表</h2> + +<p>支持的 <code>manifest.json</code> 键如下所示：</p> + +<h3 id="简体中文内容">简体中文内容</h3> + +<div class="index">{{ListSubpages("/zh-CN/Add-ons/WebExtensions/manifest.json")}}</div> + +<h3 id="英文内容">英文内容</h3> + +<div class="index">{{ListSubpages("/en-US/Add-ons/WebExtensions/manifest.json")}}</div> + +<ul> + <li><code>"manifest_version"</code>，<code>"version"</code>，和 <code>"name"</code> 是唯一的强制必填键。</li> + <li>如果 "_locales" 目录存在的话，"<code>default_locale"</code> 也必须相应存在，否则不应存在。</li> + <li>Google Chrome 不支持 <code>"browser_specific_settings"</code></li> +</ul> + +<h3 id="在运行时访问_manifest.json_键">在运行时访问 manifest.json 键</h3> + +<p>你可以在拓展的 JavaScript 代码中通过 {{WebExtAPIRef("runtime.getManifest()")}} 函数访问拓展的 manifest 数据：</p> + +<pre class="brush: js; no-line-numbers">browser.runtime.getManifest().version;</pre> + +<h2 id="示例">示例</h2> + +<p>The block below shows the basic syntax for some common manifest keys.</p> + +<div class="blockIndicator note"> +<p><strong>Note:</strong> This is not intended to be used as a copy-paste-ready example. Selecting the keys you'll need depends on the extension you are developing.</p> +</div> + +<p>For complete example extensions, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Examples">Example extensions</a>.</p> + +<pre class="brush: json;">{ + "browser_specific_settings": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0" + } + }, + + "background": { + "scripts": ["jquery.js", "my-background.js"], + }, + + "browser_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "commands": { + "toggle-feature": { + "suggested_key": { + "default": "Ctrl+Shift+Y", + "linux": "Ctrl+Shift+U" + }, + "description": "Send a 'toggle-feature' event" + } + }, + + "content_security_policy": "script-src 'self' https://example.com; object-src 'self'", + + "content_scripts": [ + { + "exclude_matches": ["*://developer.mozilla.org/*"], + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ], + + "default_locale": "en", + + "description": "...", + + "icons": { + "48": "icon.png", + "96": "icon@2x.png" + }, + + "manifest_version": 2, + + "name": "...", + + "page_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "permissions": ["webNavigation"], + + "version": "0.1", + + "user_scripts": { + "api_script": "apiscript.js", + }, + + "web_accessible_resources": ["images/my-image.png"] +}</pre> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>For a full overview of all manifest keys and their sub-keys, see the<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json"> full <code>manifest.json</code> browser compatibility table</a>.</p> + + + +<p>{{Compat("webextensions.manifest")}}</p> + +<h2 id="参见">参见</h2> + +<p>{{WebExtAPIRef("permissions")}} JavaScript API</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html new file mode 100644 index 0000000000..9d67a37b89 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html @@ -0,0 +1,45 @@ +--- +title: manifest_version +slug: Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version +tags: + - WebExtensions + - 拓展 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>Number</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"manifest_version": 2</pre> + </td> + </tr> + </tbody> +</table> + +<p>此键指定扩展使用的 manifest.json 的版本。</p> + +<p>目前，此值必须为 2。</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"manifest_version": 2 +</pre> + +<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.manifest.manifest_version")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/name/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/name/index.html new file mode 100644 index 0000000000..3869571374 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/name/index.html @@ -0,0 +1,43 @@ +--- +title: 名称 - name +slug: Mozilla/Add-ons/WebExtensions/manifest.json/name +tags: + - 名称 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/name +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>字符串（String）</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"name": "附加组件的名称"</pre> + </td> + </tr> + </tbody> +</table> + +<p>附加组件的名称. 用于在用户界面和 addons.mozilla.org 网站上显示标识名称.</p> + +<p>关于本地化, 可查看 <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"name": "插件的名称"</pre> + +<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.manifest.name")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/permissions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/permissions/index.html new file mode 100644 index 0000000000..f26782540e --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/permissions/index.html @@ -0,0 +1,182 @@ +--- +title: 权限 - permissions +slug: Mozilla/Add-ons/WebExtensions/manifest.json/permissions +tags: + - 权限 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/permissions +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>数组</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>不强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json notranslate"> +"permissions": [ + "*://developer.mozilla.org/*", + "webRequest" +]</pre> + </td> + </tr> + </tbody> +</table> + +<p>使用permissions 关键字为你的扩展请求特殊的权限。该关键字为一个字符串数列，每个字符串请求一项权限。</p> + +<p>如果你使用该关键字请求权限，浏览器可能会在安装该扩展时通知用户该扩展需求某些权限，并询问他们是否愿意给予这些权限。在插件安装之后浏览器也可能允许用户检查扩展的权限。因为要求授予权限可能会影响用户安装你的扩展的意愿，所以请求权限需要特别小心的考虑。举个例子，你想要避免请求不必要的权限，而且可以在你的扩展描述中提供你为何需要某些权限的信息。更多关于这个话题的描述你可以参考这篇提供的文章 <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Request_the_right_permissions">请求正确的权限</a>。</p> + +<p>该关键字能够包含三种类型的权限:</p> + +<ul> + <li>主机权限</li> + <li>API 权限</li> + <li>活动标签权限</li> +</ul> + +<h2 id="主机权限">主机权限</h2> + +<p> 主机权限使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match patterns </a>指定，扩展在每一个表达式指定的网址上请求额外权限。</p> + +<p>额外权限包括:</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a> 和 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API">fetch</a> 用于访问无跨源限制的源文件（包括从content scripts发出的访问请求）</li> + <li>以编程方式（使用 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript</a>）将脚本注入到来自源服务器（origins）提供的页面的功能。</li> + <li>使用 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a> 在其主机上获取消息的能力。</li> + <li>使用 <a href="/en-US/Add-ons/WebExtensions/API/cookies">cookies</a> API 访问主机cookies的能力，只要 cookies api的权限也被请求。</li> + <li>使用无通配符（*）的全域名会绕开跟踪保护机制，但不能与 <code><all_urls></code> 共用.</li> +</ul> + +<p>Firefox浏览器，自56以后的版本，扩展都会自动获取其源的主机权限，如以下形式：</p> + +<pre class="notranslate"><code>moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/</code></pre> + +<p><code>60a20a9b-1ad4-af49-9b6c-c64c98c37920</code> 是扩展内部ID。编程时可使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/extension/getURL">extension.getURL()</a> 来返回此URL路径:</p> + +<ol> + <li> + <pre class="notranslate"><code>browser.extension.getURL(""); +// </code><code>moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/</code></pre> + </li> +</ol> + +<h2 id="API_权限">API 权限</h2> + +<p>API 权限有关键字指定，每个关键字标志着一类WebExtension API 能够被使用。</p> + +<p>如下关键字是当前可用的:</p> + +<ul> + <li><code>activeTab</code></li> + <li><code>alarms</code></li> + <li><code>bookmarks</code></li> + <li><code>browsingData</code></li> + <li><code>browserSettings</code></li> + <li><code>contextMenus</code></li> + <li><code>contextualIdentities</code></li> + <li><code>cookies</code></li> + <li><code>downloads</code></li> + <li><code>downloads.open</code></li> + <li><code>find</code></li> + <li><code>geolocation</code></li> + <li><code>history</code></li> + <li><code>identity</code></li> + <li><code>idle</code></li> + <li><code>management</code></li> + <li><code>menus</code></li> + <li><code>nativeMessaging</code></li> + <li><code>notifications</code></li> + <li><code>pkcs11</code></li> + <li><code>privacy</code></li> + <li><code>proxy</code></li> + <li><code>sessions</code></li> + <li><code>storage</code></li> + <li><code>tabs</code></li> + <li><code>theme</code></li> + <li><code>topSites</code></li> + <li><code>webNavigation</code></li> + <li><code>webRequest</code></li> + <li><code>webRequestBlocking</code></li> +</ul> + +<p>在大部分情况下这种权限仅仅允许你访问API，除了以下情况:</p> + +<ul> + <li><code>tabs</code>让你可以访问 <a href="/en-US/Add-ons/WebExtensions/API/tabs"><code>一部分特权API</code></a>: <code>Tab.url</code>, <code>Tab.title</code>, and <code>Tab.faviconUrl</code>。在Firefox中你也需要<code>tabs </code>来将queryInfo中的url参数加入 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code>. 剩余的<code>tabs</code> API能在不要求任何权限的情况被使用</li> + <li><code>webRequestBlocking</code> 允许你是用“blocking”参数，所以你可以<a href="/en-US/Add-ons/WebExtensions/API/WebRequest"> 修改或取消requests</a>.</li> + <li><code>downloads.open</code> 让你使用 {{WebExtAPIRef("downloads.open()")}} API.</li> +</ul> + +<h2 id="活动标签权限">活动标签权限</h2> + +<p>该权限被指定为<code>“activeTab”</code>。如果一个扩展拥有<code>activeTab</code>权限，当用户跟该扩展交互时，扩展仅在活动标签被赋予额外权限。</p> + +<p>“用户交互”包括:</p> + +<ul> + <li>用户点击扩展的浏览器按钮或者页面按钮</li> + <li>用户选择了扩展的上下文菜单</li> + <li>用户敲击了扩展定义的快捷键</li> +</ul> + +<p>额外特权包括:</p> + +<ul> + <li>插入JavaScript或者CSS的能力, 使用 <code><a href="/en-US/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript</a></code> 和 <code><a href="/en-US/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS</a></code></li> + <li>为当前标签访问tabs API权限部分的能力，包括：Tab.url,Tab.title, 和Tab .faviconUrl。</li> +</ul> + +<p>改权限的目的是为了在不给予扩展太多权限的情况下，使得扩展能够应付大部分情况。很多扩展需要在用户要求时，在当前页面做一些处理，比如，考虑一个扩展想要在用户点击一个浏览器按钮时在当前页面运行一个脚本，如果 activeTab 权限不存在，扩展将需要请求主机权限<all_urls>，但是这给予了扩展超过其需要的权限：现在它可以在任何任何时间标签页执行脚本任何次，而不是仅仅在活动标签而且仅仅回应用户的行为。</p> + +<h2 id="剪贴板访问">剪贴板访问</h2> + +<p>有两种权限使得WebExtentsion可以跟剪贴板交互:</p> + +<ul> + <li><code>clipboardWrite</code>: 使用<code>document.execCommand("copy")</code> 或<code>document.execCommand("cut")</code> 向剪贴板写入</li> + <li><code>clipboardRead</code>: 使用 <code>document.execCommand("paste")</code> 从剪贴板读取</li> +</ul> + +<p>查看 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard">Interact with the clipboard</a> 获取更多</p> + +<h2 id="无限制存储">无限制存储</h2> + +<p><code>unlimitedStorage</code> 权限:</p> + +<ul> + <li>能使扩展突破{{WebExtAPIRef("storage.local")}} API设定的quota限制</li> + <li>Firefox浏览器中，无须提示用户授权，便可帮助扩展创建永久保存的IndexedDB数据库 <a href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria#Firefox_specifics">"persistent" IndexedDB database</a></li> +</ul> + +<dl> +</dl> + +<h2 id="示例">示例</h2> + +<pre class="brush: json notranslate"> "permissions": ["*://developer.mozilla.org/*"]</pre> + +<p>请求 developer.mozilla.org 下的权限访问.</p> + +<pre class="brush: json notranslate"> "permissions": ["tabs"]</pre> + +<p>请求tabs API的权限需要部分的访问。</p> + +<pre class="brush: json notranslate"> "permissions": ["*://developer.mozilla.org/*", "tabs"]</pre> + +<p>请求以上两种访问。</p> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<p>本页的兼容列表是从结构化数据生成的。如果你想参与修改此数据，请参考 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 并发送pull 请求。</p> + +<p>{{Compat("webextensions.manifest.permissions")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/short_name/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/short_name/index.html new file mode 100644 index 0000000000..444dac6eaa --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/short_name/index.html @@ -0,0 +1,43 @@ +--- +title: 短名称 - short_name +slug: Mozilla/Add-ons/WebExtensions/manifest.json/short_name +tags: + - 短名称 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/short_name +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Type</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>不强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"short_name": "附加组件的短名称"</pre> + </td> + </tr> + </tbody> +</table> + +<p>附加组件的短名称. 一般用在 <a href="/en-US/Add-ons/WebExtensions/manifest.json/name">name</a> 特性太长的情况下. 建议短名称的长度不要超过12个字符. 如果没有在 manifest.json 主文件中声明 short_name, 并且 name 特性的值又比较长的话, 用户界面显示的时候可能只会显示一部分. </p> + +<p>关于本地化, 可查看 <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"short_name": "附加组件的短名称"</pre> + +<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.manifest.short_name")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/version/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/version/index.html new file mode 100644 index 0000000000..98028f9235 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/version/index.html @@ -0,0 +1,49 @@ +--- +title: version +slug: Mozilla/Add-ons/WebExtensions/manifest.json/version +tags: + - version + - 版本信息 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/version +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Type</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"version": "0.1"</pre> + </td> + </tr> + </tbody> +</table> + +<p>附加组件的版本, 一般格式设置为由点分隔开来数字的ASCII字符串. 关于版本格式的详细信息, 请查看 <a href="https://developer.mozilla.org/en-US/docs/Toolkit_version_format">Version format</a> .</p> + +<p>需要注意的是 Chrome 浏览器的 version 格式要求(<a href="https://developer.chrome.com/extensions/manifest/version">the syntax defined for Chrome's <code>version</code></a>)比 Firefox 浏览器的 version 格式更严格一些, 这意味这:</p> + +<ul> + <li>对 Chrome 浏览器有效的 version 特性的值一定在 Firefox 浏览器中有效</li> + <li>但对 Firefox 浏览器有效的 version 特性的值在 Chrome 浏览器中却不一定有效</li> +</ul> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"version": "0.1"</pre> + +<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.manifest.version")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.html new file mode 100644 index 0000000000..713741a26b --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.html @@ -0,0 +1,96 @@ +--- +title: web_accessible_resources +slug: Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources +tags: + - 扩展应用 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">类型</th> + <td><code>Array</code></td> + </tr> + <tr> + <th scope="row">是否必需</th> + <td>No</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json no-line-numbers"> +"web_accessible_resources": [ + "images/my-image.png" +]</pre> + </td> + </tr> + </tbody> +</table> + +<h2 id="描述">描述</h2> + +<p>你有时想将资源（如图片、HTML、CSS 或 JavaScript）与你的扩展应用合并打包，让网页能够访问它们。</p> + +<p>举个例子，<a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">Beastify example extension</a> 将用户选择的野兽图片来替换网页，这些图片与应用是经过合并打包的。该应用添加 <code><a href="/en-US/docs/Web/HTML/Element/img"><img></a></code>，其 <code>src</code> 指向图片，这样就使选中的图片可见了。网页要载入图片的话，这些图片就必须可经访问。</p> + +<p>通过 <code>web_accessible_resources</code>， 你列出资源，让它们可经网页访问。这些资源路径相对于 manifest.json 文件.</p> + +<p>注意，这其中不必包括 content scripts。</p> + +<p>如果你的应用要用 {{WebExtAPIRef("webRequest")}} 来重定向公共 URL(如 HTTPS) 到一个该应用中的页面, 那么应用必须将该页面列入<code>web_accessible_resources</code>。</p> + +<h3 id="使用_web_accessible_resources">使用 web_accessible_resources</h3> + +<p>例如，如果你的应用含有图片，路径为 images/my-image.png，如下所示：</p> + +<pre class="no-line-numbers">my-extension-files/ + manifest.json + my-background-script.js + images/ + my-image.png</pre> + +<p>如果要使网页能够从元素 <code><a href="/en-US/docs/Web/HTML/Element/img"><img></a></code> 的属性 <code>src</code> 指向该图片，你得写明<code>web_accessible_resources</code>，如下所示：</p> + +<pre class="brush: json no-line-numbers">"web_accessible_resources": ["images/my-image.png"]</pre> + +<p>之后，图片可通过 URL 来访问，如下所示：</p> + +<pre class="no-line-numbers">moz-extension://<extension-UUID>/images/my-image.png"</pre> + +<p><code><extension-UUID></code> 不是应用 ID，它随机生成，对应每个浏览器实例，以防网页查看浏览器安装的扩展应用来获取信息。</p> + +<div class="blockIndicator note"> +<p>Chrome 的 <code><extension-UUID></code> 是不变的。某资源如果由<code>web_accessible_resources</code> 写明，那么它可通过 <code>chrome-extension://<your-extension-id>/<path/to/resource></code> 来访问。 </p> +</div> + +<p>要获得资源的 URL，推荐用 <code><a href="/en-US/Add-ons/WebExtensions/API/runtime/getURL">runtime.getURL</a></code> 向参数传递 manifest.json 的相对路径，比如：</p> + +<pre class="brush: js no-line-numbers">browser.runtime.getURL("images/my-image.png"); +// something like: +// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png</pre> + +<p>这会返回正确的 URL，不受应用运行的浏览器影响。</p> + +<h3 id="通配符">通配符</h3> + +<p><code>web_accessible_resources</code> 中的条目还可以有通配符。比如，下面的条目匹配“images/my-image.png”：</p> + +<pre class="brush: json no-line-numbers"> "web_accessible_resources": ["images/*.png"]</pre> + +<h3 id="安全">安全</h3> + +<p>注意，如果你部署了一个页面，那么任一网页可能会链接或重定向至该页面，因而它应认为任意输入（比如 POST data）的来源不可信任，这与通常网页的做法一样。</p> + +<h2 id="Example">Example</h2> + +<pre class="brush: json no-line-numbers">"web_accessible_resources": ["images/my-image.png"]</pre> + +<p>Make the file at "images/my-image.png" web accessible.</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.manifest.web_accessible_resources")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/主页地址/index.html b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/主页地址/index.html new file mode 100644 index 0000000000..01749d5ff3 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/manifest.json/主页地址/index.html @@ -0,0 +1,42 @@ +--- +title: homepage_url +slug: Mozilla/Add-ons/WebExtensions/manifest.json/主页地址 +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">值类型</th> + <td><code>字符串（String）</code></td> + </tr> + <tr> + <th scope="row">强制性</th> + <td>非强制</td> + </tr> + <tr> + <th scope="row">示例</th> + <td> + <pre class="brush: json"> +"homepage_url": "https://example.org/my-addon"</pre> + </td> + </tr> + </tbody> +</table> + +<p>该扩展的主页地址。</p> + +<p>如果 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/developer">developer</a> 键存在且包含“url”属性，它将会覆盖 <code>homepage_url</code> 键。</p> + +<p>这是一个 <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + +<h2 id="示例">示例</h2> + +<pre class="brush: json">"homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/beastify"</pre> + +<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.manifest.homepage_url")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/match_patterns/index.html b/files/zh-cn/mozilla/add-ons/webextensions/match_patterns/index.html new file mode 100644 index 0000000000..44df7ebb7f --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/match_patterns/index.html @@ -0,0 +1,384 @@ +--- +title: 匹配模式 +slug: Mozilla/Add-ons/WebExtensions/Match_patterns +tags: + - Match_patterns + - URIs + - urls +translation_of: Mozilla/Add-ons/WebExtensions/Match_patterns +--- +<div>{{AddonSidebar}}</div> + +<p>匹配模式是一种指定网址组的方法：: 一个匹配模式匹配特定的一组URL。 它们由WebExtensions 在几个地方使用，最明显的是指定要将<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">内容脚本</a>加载到哪些文档中，并指定要向其中添加 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest </a>侦听器的URL。</p> + +<p>使用匹配模板的API通常接收一个匹配模板的列表，当URL匹配任何模式时会恰当的运行. 看个例子 在manifest.json中的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> 关键字。</p> + +<h2 id="匹配模式结构">匹配模式结构</h2> + +<p>所有的匹配模式用一个字符串来定义，而且都是<a href="/en-US/Add-ons/WebExtensions/Match_patterns#%3Call_urls%3E">"<all_urls>"</a> 模板的一部份， 匹配模板包含三个部分: <em>scheme</em>, <em>host</em>, 和 <em>path</em>. scheme host 用 "://" 分隔。</p> + +<pre><scheme>://<host><path></pre> + +<h3 id="方案">方案</h3> + +<p> <em>scheme</em> 可能以下两种格式之一:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Form</th> + <th scope="col">Matches</th> + </tr> + </thead> + <tbody> + <tr> + <td>"*"</td> + <td>Only "http" and "https".</td> + </tr> + <tr> + <td>One of "http", "https", "file", "ftp", "app".</td> + <td>Only the given scheme.</td> + </tr> + </tbody> +</table> + +<h3 id="主机">主机</h3> + +<p> <em>host </em>组件可以采取三种形式之一：:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Form</th> + <th scope="col">Matches</th> + </tr> + </thead> + <tbody> + <tr> + <td>"*"</td> + <td>Any host.</td> + </tr> + <tr> + <td>"*." followed by part of the hostname.</td> + <td>The given host and any of its subdomains.</td> + </tr> + <tr> + <td>A complete hostname, without wildcards.</td> + <td>Only the given host.</td> + </tr> + </tbody> +</table> + +<p>只有当 <em>scheme</em> 是 "file" 是 <em>host</em> 可选的</p> + +<p>值得注意的是通配符可能只会在开头显示。</p> + +<h3 id="路径">路径</h3> + +<p><em>path </em>组件必须以“/”开头。</p> + +<p>之后，它可能随后包含“*”通配符和网址路径中允许的任何字符的任意组合。 与 <em>host </em>不同， <em>path </em>组件可能在中间或末尾包含“*”通配符，并且“*”通配符可以多次出现。</p> + +<h3 id="<all_urls>"><all_urls></h3> + +<p>特殊值“<all_urls>”匹配任何受支持方案下的所有URL：即, "http", "https", "file", "ftp", "app"。</p> + +<h2 id="范例">范例</h2> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 33%;">Pattern</th> + <th scope="col" style="width: 33%;">Example matches</th> + <th scope="col" style="width: 33%;">Example non-matches</th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p><code><all_urls></code></p> + + <p>Match all URLs.</p> + </td> + <td> + <p><code>http://example.org/</code></p> + + <p><code>ftp://files.somewhere.org/</code></p> + + <p><code>https://a.org/some/path/</code></p> + </td> + <td> + <p><code>resource://a/b/c/</code><br> + (unsupported scheme)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://*.mozilla.org/*</code></p> + + <p>Match all HTTP and HTTPS URLs that are hosted at "mozilla.org" or one of its subdomains.</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + + <p><code>http://a.mozilla.org/</code></p> + + <p><code>http://a.b.mozilla.org/</code></p> + + <p><code>https://b.mozilla.org/path/</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>http://mozilla.com/</code><br> + (unmatched host)</p> + + <p><code>http://firefox.org/</code><br> + (unmatched host)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://mozilla.org/</code></p> + + <p>Match all HTTP and HTTPS URLs that are hosted at exactly "mozilla.org/".</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>http://a.mozilla.org/</code><br> + (unmatched host)</p> + + <p><code>http://mozilla.org/a</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>ftp://mozilla.org/</code></p> + + <p>Match only "ftp://mozilla.org/".</p> + </td> + <td><code>ftp://mozilla.org</code></td> + <td> + <p><code>http://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>ftp://sub.mozilla.org/</code><br> + (unmatched host)</p> + + <p><code>ftp://mozilla.org/path</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path</code></p> + + <p>Match HTTPS URLs on any host, whose path is "path".</p> + </td> + <td> + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://a.mozilla.org/path</code></p> + + <p><code>https://something.com/path</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.org/path/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path/</code></p> + + <p>Match HTTPS URLs on any host, whose path is "path/".</p> + </td> + <td> + <p><code>https://mozilla.org/path/</code></p> + + <p><code>https://a.mozilla.org/path/</code></p> + + <p><code>https://something.com/path</code>/</p> + </td> + <td> + <p><code>http://mozilla.org/path/</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.org/path</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*</code></p> + + <p>Match HTTPS URLs only at "mozilla.org", with any path.</p> + </td> + <td> + <p><code>https://mozilla.org/</code></p> + + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://mozilla.org/another</code></p> + + <p><code>https://mozilla.org/path/to/doc</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.com/path</code><br> + (unmatched host)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p>Match only this URL.</p> + </td> + <td><code>https://mozilla.org/a/b/c/</code></td> + <td>Anything else.</td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*/b/*/</code></p> + + <p>Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle.</p> + </td> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p><code>https://mozilla.org/d/b/f/</code></p> + + <p><code>https://mozilla.org/a/b/c/d/</code></p> + </td> + <td> + <p><code>https://mozilla.org/b/*/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a/b/</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>file:///blah/*</code></p> + + <p>Match any FILE URL whose path begins with "blah".</p> + </td> + <td> + <p><code>file:///blah/</code></p> + + <p><code>file:///blah/bleh</code></p> + </td> + <td><code>file:///bleh/</code><br> + (unmatched path)</td> + </tr> + </tbody> +</table> + +<h3 id="无效匹配模式">无效匹配模式</h3> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Invalid pattern</th> + <th scope="col">Reason</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>resource://path/</code></td> + <td>Unsupported scheme.</td> + </tr> + <tr> + <td><code>https://mozilla.org</code></td> + <td>No path.</td> + </tr> + <tr> + <td><code>https://mozilla.*.org/</code></td> + <td>"*" in host must be at the start.</td> + </tr> + <tr> + <td><code>https://*zilla.org/</code></td> + <td>"*" in host must by the only character or be followed by ".".</td> + </tr> + <tr> + <td><code>http*://mozilla.org/</code></td> + <td>"*" in scheme must be the only character.</td> + </tr> + <tr> + <td><code>file://*</code></td> + <td>Empty path: this should be "<code>file:///*</code>".</td> + </tr> + </tbody> +</table> + +<h2 id="测试匹配模式">测试匹配模式</h2> + +<p>当制作扩展时你通常不会跟直接使用匹配模板: 通常你讲一个匹配模式传递给API，然后API构造一个匹配模式并且使用他来测试url。不过如果你正在尝试哪一种匹配模式可以被使用，或者调试一个匹配问题，那么直接创建和测试匹配模板的能力将变得有用，这个模块将解释如何做到这点。</p> + +<p>首先，打开开发者工具设置，并且检查 "Enable browser chrome and add-on debugging toolboxes" 被打开:</p> + +<p>{{EmbedYouTube("JDEe2fyFpHE")}}</p> + +<p>然后打开 "Browser Console":</p> + +<p>{{EmbedYouTube("mfuBMje6dA4")}}</p> + +<p>它给了你一个命令行以使你可以执行一些特权javascript代码。</p> + +<div class="warning"> +<p>因为运行在浏览器控制台的代码拥有系统特权，在任何时候都请你小心理解你的代码做了什么</p> +</div> + +<p>现在粘贴以下代码到命令行然后按下 <kbd>enter</kbd>:</p> + +<pre class="brush: js">Cu.import("resource://gre/modules/MatchPattern.jsm"); +Cu.import("resource://gre/modules/BrowserUtils.jsm");</pre> + +<p>这做了两件事:</p> + +<ul> + <li>导入 "MatchPattern.jsm": 这是实现了匹配模板的系统模块，特别的，这个模块包含了 <code>MatchPattern</code> 对象. <code>MatchPattern</code> 对象定义了一个 <code>matches()</code> 方法, 他需要一个URL然后返回 <code>true</code> 或者 <code>false</code>.</li> + <li>导入 "BrowserUtils.jsm": 包含了一个方法 <code>makeURI()</code>, 他转换一个字符串为一个 <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURI">nsIURI</a></code> 对象. <code>nsIURI</code> 是 <code>matches()</code> 方法需要接受的一个参数。</li> +</ul> + +<p>现在你可以构造MatchPattern对象，构造URIs，并检查URIs 是否匹配：</p> + +<pre class="brush: js">var match = new MatchPattern("*://mozilla.org/"); + +var uri = BrowserUtils.makeURI("https://mozilla.org/"); +match.matches(uri); // < true + +uri = BrowserUtils.makeURI("https://mozilla.org/path"); +match.matches(uri); // < false</pre> + +<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/modify_a_web_page/index.html b/files/zh-cn/mozilla/add-ons/webextensions/modify_a_web_page/index.html new file mode 100644 index 0000000000..9f4856de63 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/modify_a_web_page/index.html @@ -0,0 +1,239 @@ +--- +title: 修改web页面 +slug: Mozilla/Add-ons/WebExtensions/Modify_a_web_page +translation_of: Mozilla/Add-ons/WebExtensions/Modify_a_web_page +--- +<div>{{AddonSidebar}}</div> + +<p>浏览器附加组件( add-on )常被用于修改网页。例如更改页面的样式，隐藏特定的DOM节点或把DOM节点注入到页面中。</p> + +<p>使用WebExtensions有两种方式：</p> + +<ul> + <li>声明方式:定义一个网址格式，用来匹配特定的网址，然后加载脚本到对应的网页中.</li> + <li>编程方式: 使用JavaScript 接口, 将脚本加载到一个指定标签页所承载的页面中</li> +</ul> + +<p>无论使用上面何种方式，它们都被称为内容脚本， 与其他脚本的区别：</p> + +<ul> + <li>只能使用一部分的webextension API。</li> + <li>能读取加载了内容脚本的网页。</li> + <li>通过使用消息API与其他的webextension通信。</li> +</ul> + +<p>在本文中，我们将看下加载脚本的两种方式。</p> + +<h2 id="修改匹配URL的页面">修改匹配URL的页面</h2> + +<p>首先，创建一个名为“ modify-page ”的文件夹，并在目录下创建“ manifest.json ”文件，内容如下：</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["https://developer.mozilla.org/*"], + "js": ["page-eater.js"] + } + ] + +}</pre> + +<p>"content_scripts"指出符合 URL 格式的页面地址，然后让浏览器加载脚本(“ page-eater.js“)到匹配的URL页面(<a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a> )。</p> + +<div class="note"> +<p><span id="result_box" lang="zh-CN"><span>由于</span></span> <code>content_scripts</code> <span lang="zh-CN"><span>的</span></span> <code>"js"</code> <span lang="zh-CN"><span>属性是一个数组，因此可以使用它将多个脚本注入匹配的页面。</span> <span>如果这样做，页面将按照数组中列出的顺序加载多个脚本。</span></span></p> +</div> + +<div class="note"> +<p><code>content_scripts</code> <span class="short_text" lang="zh-CN"><span>键还具有一个</span></span> <code>"css"</code> <span class="short_text" lang="zh-CN"><span>属性，可以使用它来注入CSS样式表。</span></span></p> +</div> + +<p>在 "modify-page" 文件夹下创建“ page-eater.js ”文件，内容如下：</p> + +<pre class="brush: js">document.body.textContent = ""; + +var header = document.createElement('h1'); +header.textContent = "This page has been eaten"; +document.body.appendChild(header);</pre> + +<p>现在安装这个<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">WebExtension</a>, 然后浏览 <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>：</p> + +<p>{{EmbedYouTube("lxf2Tkg6U1M")}}</p> + +<div class="note"> +<p><span id="result_box" lang="zh-CN"><span>请注意，虽然此视频显示在</span></span> <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> <span lang="zh-CN"><span>工作的</span></span> content scripts <span lang="zh-CN"><span>，但目前该网站已禁止</span></span> content scripts <span lang="zh-CN"><span>。</span></span></p> +</div> + +<h2 id="通过程序修改页面">通过程序修改页面</h2> + +<p>如何修改程序使其在用户要求时才吞页面。现在修改上面的例子，在点击右键菜单项时才注入内容脚本。</p> + +<p>修改 "manifest.json" 内容如下:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "permissions": [ + "activeTab", + "contextMenus" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>这里我们要移除"<code>content_scripts</code>"键值，并添加两个键：</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code>:要向页面中注入脚本，就需要拥有修改页面对应的权限。<a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>activeTab</code></a>可以临时获得修改当前活动标签所加载的页面的权限。 另外还通过 contextmenus 来获取添加右键菜单项的权限。</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background</a></code>: 加载名为 "background.js" 的 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">"background script"</a> （长期有效的后台脚本），在该脚本中，我们将设置注入右键菜单的内容脚本。</li> +</ul> + +<p>在 "modify-page" 文件夹下创建名为 "background.js"的新文件，内容如下：</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "eat-page", + title: "Eat this page" +}); + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + browser.tabs.executeScript({ + file: "page-eater.js" + }); + } +}); +</pre> + +<p>在该脚本中我们创建了一个右键菜单项， 给了它一个具体的 id 和标题 (将在菜单中显示的文本)。 然后又设置了一个事件侦听器，当用户点击菜单项时，检查该菜单项是否就是我们的吞页菜单项。 如果是, 就通过<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code> 接口，把"page-eater.js" 注入到活动标签页中。 这个接口用标签ID做为参数：如果省略标签ID参数，就默认把脚本注入当前活动标签。</p> + +<p>现在，附加组件看起来像这样：</p> + +<pre class="line-numbers language-html"><code class="language-html">modify-page/ + background.js + manifest.json + page-eater.js</code></pre> + +<p>重新加载<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">WebExtension</a>, 打开页面 (这次可以是任何一个页面) 激活右键菜单，然后选择 "Eat this page"：</p> + +<p>{{EmbedYouTube("zX4Bcv8VctA")}}</p> + +<div class="note"> +<p><span id="result_box" lang="zh-CN"><span>请注意，虽然此视频显示在</span></span> <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> <span lang="zh-CN"><span>工作的</span></span> content scripts <span lang="zh-CN"><span>，但目前该网站已禁止</span></span> content scripts <span lang="zh-CN"><span>。</span></span></p> +</div> + +<h2 id="消息">消息</h2> + +<p>内容脚本和后台脚本不能直接相互访问，但可以通过发送消息进行通信。当一端设置一个消息侦听器时，另一个端就可以发送消息了。下面的表格总结了通信时的api接口：</p> + +<table class=" fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"> </th> + <th scope="col">在内容脚本中</th> + <th scope="col">在后台脚本中</th> + </tr> + <tr> + <th scope="row">发送消息</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#sendMessage()">browser.runtime.sendMessage()</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/sendMessage">browser.tabs.sendMessage()</a></code></td> + </tr> + <tr> + <th scope="row">接收消息</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onMessage">browser.runtime.onMessage</a></code></td> + </tr> + </thead> +</table> + +<p>修改上面的示例，使得可以通过后台脚本来发送消息。</p> + +<p>首先，修改 "background.js" 如下:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "eat-page", + title: "Eat this page" +}); + +function messageTab(tabs) { + browser.tabs.sendMessage(tabs[0].id, { + replacement: "Message from the add-on!" + }); +} + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + browser.tabs.executeScript({ + file: "page-eater.js" + }); + + var querying = browser.tabs.query({ + active: true, + currentWindow: true + }); + querying.then(messageTab); + } +}); +</pre> + +<p> 注入 "page-eater.js"后， 通过使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code> 获取当前活动标签页， 然后使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code> 将消息发送到该标签页中的内容脚本。 该消息的内容 <code>{replacement: "Message from the add-on!"}。</code></p> + +<p>接下来，修改 "page-eater.js" 如下:</p> + +<pre class="brush: js">function eatPage(request, sender, sendResponse) { + document.body.textContent = ""; + + var header = document.createElement('h1'); + header.textContent = request.replacement; + document.body.appendChild(header); +} + +browser.runtime.onMessage.addListener(eatPage); +</pre> + +<p>现在，不再立即执行吞页，内容脚本将先通过使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code>来监听消息。当监听到消息时, 内容脚本才开始运作，除了来自<code>request.replacement</code>的替换文本不一样以外，其他的脚本运作本质上与之前的相同 。</p> + +<p>如果我们想将消息从内容脚本发送到后台页面，除了在内容脚本中使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code> ，其他与上面的过程相反。</p> + +<div class="note"> +<p><span id="result_box" lang="zh-CN"><span>这些例子注入的都是JavaScript;</span> 想</span><span lang="zh-CN"><span>注入CSS可以使用</span></span> <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code> <span lang="zh-CN"><span>函数。</span></span></p> +</div> + +<h2 id="了解更多">了解更多</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">Content scripts</a> 指南</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code></li> + <li>使用<code>content_scripts</code>的例子: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">borderify</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/inpage-toolbar-ui">inpage-toolbar-ui</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/page-to-extension-messaging">page-to-extension-messaging</a></li> + </ul> + </li> + <li>使用<code>tabs.executeScript()</code>的例子: + <ul> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-demo">context-menu-demo</a></li> + </ul> + </li> +</ul> + +<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/native_manifests/index.html b/files/zh-cn/mozilla/add-ons/webextensions/native_manifests/index.html new file mode 100644 index 0000000000..b83609fa85 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/native_manifests/index.html @@ -0,0 +1,344 @@ +--- +title: 原生应用清单 +slug: Mozilla/Add-ons/WebExtensions/Native_manifests +translation_of: Mozilla/Add-ons/WebExtensions/Native_manifests +--- +<div>{{AddonSidebar}}</div> + +<p> </p> + +<p>原生应用清单是一个符合特定规则的JSON文件，它应该使用与 extension 不同的安装方式存放在用户的计算机上。举个例子，原生应用清单是由设备管理员或者通过原生应用安装器提供的。</p> + +<p>有三种不同的原生应用清单：</p> + +<table class="standard-table"> + <tbody> + <tr> + <td style="width: 40%;"><a href="#原生应用通信清单">原生应用通信清单</a></td> + <td> + <p>定义关于 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">与本地应用通信</a> 的功能：哪一个 extension 可以与本机的原生应用交换信息。</p> + </td> + </tr> + <tr> + <td><a href="#存储管理清单">存储管理清单</a></td> + <td> + <p>定义一些 extension 可以用 {{WebExtAPIRef("storage.managed")}} 读取的只读数据。</p> + </td> + </tr> + <tr> + <td><a href="#PKCS #11 清单">PKCS #11 清单</a></td> + <td> + <p>定义了 extension 使用 {{WebExtAPIRef("pkcs11")}} API 去枚举 PKCS #11 安全模型 并在Firefox安装它们。</p> + </td> + </tr> + </tbody> +</table> + +<p>对于所有的原生应用清单，你需要做一些工作以便于浏览器可以找到它们。这些规则在 <a href="#清单路径">清单路径</a><a href="#Manifest_location"> </a>章节。</p> + +<h2 id="原生应用通信清单_2">原生应用通信清单<a id="原生应用通信清单" name="原生应用通信清单"></a></h2> + +<p>原生应用通信清单中包含单个JSON对象，对象具有如下属性：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Name</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>name</code></td> + <td>String</td> + <td> + <p>原生应用的名字</p> + + <p>它必须与 extension 调用 {{WebExtAPIRef("runtime.connectNative()")}} 和 {{WebExtAPIRef("runtime.sendNativeMessage()")}} 时传入的名称保持一致。</p> + + <p>在 OS X 和 Linux 中，它必须和清单文件的文件名保持一致（除.json文件扩展名外）。</p> + + <p>在 Windows 中，它必须和你创建的包含原生应用清单路径的注册表一致。</p> + + <p>它必须符合正则表达式 "^\w+(\.\w+)*$"。这意味着它只能包含小写字母、数字、下划线和 <code>.</code> ，并且不允许开头或结束是 <code>.</code> ，并且 <code>.</code> 后面不能是 <code>.</code> 。</p> + </td> + </tr> + <tr> + <td><code>description</code></td> + <td>String</td> + <td> + <p>关于这个原生应用的描述。</p> + </td> + </tr> + <tr> + <td><code>path</code></td> + <td>String</td> + <td> + <p>到原生应用的路径。</p> + + <p>在 Windows 中，这可以是一个相对路径。在 OS X 和 Linux 中，必须是绝对路径。</p> + </td> + </tr> + <tr> + <td><code>type</code></td> + <td>String</td> + <td> + <p>定义 extension 和原生应用的连接方法。</p> + + <p>目前只支持一种值，那就是 stdio。该值表示应用使用标准输入（stdin）来接受消息，用标准输出（stdout）来发送消息。</p> + </td> + </tr> + <tr> + <td><code>allowed_extensions</code></td> + <td>Array of String</td> + <td> + <p>由 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">Add-on ID</a> 组成的数组。每个值代表允许ID为该值的 extension 与这个原生应用通信。</p> + + <div class="note"> + <p>这意味着你可能需要在你 extension 的 manifest.json 中包含 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> 字段，并为 extension 设置一个显示的ID，哪怕是在开发时</p> + </div> + </td> + </tr> + </tbody> +</table> + +<p>举个例子，这是 ping_pong 原生应用的原生应用通信清单：</p> + +<pre class="brush: json">{ + "name": "ping_pong", + "description": "Example host for native messaging", + "path": "/path/to/native-messaging/app/ping_pong.py", + "type": "stdio", + "allowed_extensions": [ "ping_pong@example.org" ] +}</pre> + +<p>清单表示：它允许ID为 ping_pong@example.org 的 extension 通过传入 ping_pong 给 {{WebExtAPIRef("runtime")}} 与自己连接。原生应用自身在 /path/to/native-messaging/app/ping_pong.py 中。</p> + +<h2 id="存储管理清单_2">存储管理清单<a id="存储管理清单" name="存储管理清单"></a></h2> + +<p>存储管理清单中包含单个JSON对象，对象具有如下属性：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Name</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>name</code></td> + <td>String</td> + <td> + <p><strong>一个</strong> extension 的 ID，表示这个 extension 可以读取这个仓库。</p> + + <p>给出这个ID需要你的 extension 的 manifest.json 文件包含 <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> 字段。</p> + </td> + </tr> + <tr> + <td><code>description</code></td> + <td>String</td> + <td> + <p>人类可读的描述，Firefox会忽略它。</p> + </td> + </tr> + <tr> + <td><code>type</code></td> + <td>String</td> + <td> + <p>该值只能是<code>storage</code>。</p> + </td> + </tr> + <tr> + <td><code>data</code></td> + <td>Object</td> + <td> + <p>一个JSON对象，其中可以包含任何合法的JSON值（string、number、boolean、array、object），他们将成为<code>browser.storage.managed</code>可访问的数据。</p> + </td> + </tr> + </tbody> +</table> + +<p>举个例子：</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="punctuation token">{</span> + <span class="key token">"name":</span> <span class="string token">"favourite-colour-examples@mozilla.org"</span><span class="punctuation token">,</span> + <span class="key token">"description":</span> <span class="string token">"ignored"</span><span class="punctuation token">,</span> + <span class="key token">"type":</span> <span class="string token">"storage"</span><span class="punctuation token">,</span> + <span class="key token">"data":</span> + <span class="punctuation token">{</span> + <span class="key token">"colour":</span> <span class="string token">"management thinks it should be blue!"</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span></code></pre> + +<p>在给出的清单文件中，ID 为 favourite-colour-examples@mozilla.org 的 extension 有权限使用清单中的 data 字段中的数据，代码如下：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> storageItem <span class="operator token">=</span> browser<span class="punctuation token">.</span>storage<span class="punctuation token">.</span>managed<span class="punctuation token">.</span><span class="keyword token">get</span><span class="punctuation token">(</span><span class="string token">'colour'</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +storageItem<span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span><span class="punctuation token">(</span>res<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="template-string token"><span class="string token">`Managed colour is: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>res<span class="punctuation token">.</span>colour<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></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> + +<h2 id="PKCS_11_清单">PKCS #11 清单<a id="PKCS #11 清单" name="PKCS #11 清单"></a></h2> + +<p>PKCS #11 清单中包含单个JSON对象，对象具有如下属性：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Name</th> + <th scope="col">Type</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>name</code></td> + <td>String</td> + <td> + <p>PKCS #11 模块的名字。</p> + + <p>它必须和你使用 <code>pkcs11</code> API 时的名字一致。</p> + + <p>在 OS X 和 Linux 中，它必须和清单文件的文件名保持一致（除文件扩展名外）</p> + + <p>在 Windows 中，它必须和你创建的包含原生应用清单路径的注册表一致。</p> + + <p>它必须符合正则表达式 "^\w+(\.\w+)*$"。这意味着它只能包含小写字母、数字、下划线和 <code>.</code> ，并且不允许开头或结束是 <code>.</code> ，并且 <code>.</code> 后面不能是 <code>.</code> 。</p> + </td> + </tr> + <tr> + <td><code>description</code></td> + <td>String</td> + <td> + <p>关于该模块的描述。</p> + + <p>它将被用在浏览器界面中为模块设置一个友好的名字（比如，在Firefox的“安全设备”对话框中）</p> + </td> + </tr> + <tr> + <td><code>path</code></td> + <td>String</td> + <td> + <p>到模块的路径。</p> + + <p>在 Windows 中，这可以是一个相对路径。在 OS X 和 Linux 中，必须是绝对路径。</p> + </td> + </tr> + <tr> + <td><code>type</code></td> + <td>String</td> + <td>该值只能是<code>pkcs11</code>。 This must be "pkcs11".</td> + </tr> + <tr> + <td><code>allowed_extensions</code></td> + <td>Array of String</td> + <td> + <p>由 <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">Add-on ID</a> 组成的数组。每个值代表允许ID为该值的 extension 与这个模块通信。</p> + + <div class="note"> + <p>这意味着你可能需要在你 extension 的 manifest.json 中包含 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> 字段，并为 extension 设置一个显示的ID，哪怕是在开发时</p> + </div> + </td> + </tr> + </tbody> +</table> + +<p>举个例子：</p> + +<pre class="brush: json line-numbers language-json">{ + "name": "my_module", + "description": "My test module", + "type": "pkcs11", + "path": "/path/to/libpkcs11testmodule.dylib", + "allowed_extensions": ["my-extension@mozilla.org"] +}</pre> + +<p>给出的这个JSON清单，保存为 my_module.json，ID为 my-extension@mozilla.org 的 extension 就能够使用类似于如下代码安装 /path/to/libpkcs11testmodule.dylib 安全模块：</p> + +<pre class="brush: js line-numbers language-js">browser.pkcs11.installModule("my_module");</pre> + +<h2 id="清单路径_2">清单路径<a id="清单路径" name="清单路径"></a></h2> + +<p>在 Linux 和 Mac OS X 中，你需要将清单文件存在特定的位置。在 Windows 中，你需要创建一个注册表来指向清单文件。</p> + +<p>所有类型的清单的详细规则都是相同的，除了倒数第二个的 type 字段表示了清单的类型。下面的例子展示了三种不同类型的清单。在例子中，<name> 代表清单中的 name 字段值。</p> + +<h3 id="Windows">Windows</h3> + +<p>如果想要全局可见，使用下面的路径创建注册表：</p> + +<pre>HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\NativeMessagingHosts\<name> + +HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\<code class="language-html">ManagedStorage</code>\<name> + +HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\PKCS11Modules\<name></pre> + +<p>注册表应该有单个默认值，值里存放“到清单文件的路径”。比如为原生应用通信清单建立的注册表差不多是这样：</p> + +<p><img alt="为原生应用通信清单建立的注册表" src="https://mdn.mozillademos.org/files/15643/native-message-regkey-exaple.png" style="height: 308px; width: 1027px;"></p> + +<div class="note"> +<p><em>对于原生应用清单，即使原生应用是32位的，也不能在 <a href="https://en.wikipedia.org/wiki/WoW64#Registry_and_file_system">Wow6432Node</a> 下创建注册表。浏览器将总会在 native 视图下寻找注册表的，而不是32位放在环境。确保注册表的创建在原生视图中，你可以键入KEY_WOW64_64KEY 或 KEY_WOW64_32KEY 到 RegCreateKeyEx。请参考：<a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa384129(v=vs.85).aspx">Accessing an Alternate Registry View</a></em></p> +</div> + +<p>如果想要用户级别的可见，使用下面的路径创建注册表：</p> + +<pre>HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\<name> + +HKEY_CURRENT_USER\SOFTWARE\Mozilla\<code class="language-html">ManagedStorage</code>\<name> + +HKEY_CURRENT_USER\SOFTWARE\Mozilla\PKCS11Modules\<name></pre> + +<p>注册表应该有单个默认值，值里存放“到清单文件的路径”。</p> + +<h3 id="Mac_OS_X">Mac OS X</h3> + +<p>如果想要全局可见，将清单文件存放在：</p> + +<pre>/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json + +/Library/Application Support/Mozilla/<code class="language-html">ManagedStorage</code>/<name>.json + +/Library/Application Support/Mozilla/PKCS11Modules/<name>.json</pre> + +<p>如果想要用户级别的可见，将清单文件存放在：</p> + +<pre>~/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json + +~/Library/Application Support/Mozilla/<code class="language-html">ManagedStorage</code>/<name>.json + +~/Library/Application Support/Mozilla/PKCS11Modules/<name>.json +</pre> + +<h3 id="Linux">Linux</h3> + +<p>如果想要全局可见，将清单文件存放在：</p> + +<pre>/usr/lib/mozilla/native-messaging-hosts/<name>.json + +/usr/lib/mozilla/<code class="language-html">managed-storage</code>/<name>.json + +/usr/lib/mozilla/pkcs11-modules/<name>.json +</pre> + +<p>或者：</p> + +<pre>/usr/lib64/mozilla/native-messaging-hosts/<name>.json + +/usr/lib64/mozilla/<code class="language-html">managed-storage</code>/<name>.json + +/usr/lib64/mozilla/pkcs11-modules/<name>.json</pre> + +<p>如果想要用户级别的可见，将清单文件存放在：</p> + +<pre>~/.mozilla/native-messaging-hosts/<name>.json + +~/.mozilla/<code class="language-html">managed-storage</code>/<name>.json + +~/.mozilla/pkcs11-modules/<name>.json</pre> + +<p> </p> + +<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html b/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html new file mode 100644 index 0000000000..505ba9a16a --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/native_messaging/index.html @@ -0,0 +1,326 @@ +--- +title: 与本地应用通信 +slug: Mozilla/Add-ons/WebExtensions/Native_messaging +translation_of: Mozilla/Add-ons/WebExtensions/Native_messaging +--- +<div>{{AddonSidebar}}</div> + +<p>Native messaging 可以让 extension 与安装在用户计算机上的原生应用交换信息。 原生应用仅需给 extension 提供服务，而无需在网页中可访问。 一个常见的例子是密码管理器: 原生应用负责存储和加密你的密码，并且和 extension 通信来填充网页中的表单字段。Native messaging 可以让 extension 拥有那些WebExtensions APIs 所没有的功能，比如访问某些特定的硬件。</p> + +<p>原生应用的安装与管理并不是在浏览器当中的： 它应该是使用操作系统进行安装，和其他的原生应用一样。然后你需要将你的原生应用安装在指定位置，并提供一个清单。清单中描述了浏览器如何连接到你的原生应用。</p> + +<p>extension 必须在 manifest.json 中获得"nativeMessaging" <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a>。 同时，原生应用也需要在其清单中的 "allowed_extensions" 字段中包含 extension 的ID来表示允许该 extension 与自己进行通信。</p> + +<p>经过上述操作，extension 就可以通过 {{WebExtAPIRef("runtime")}} API 与原生应用进行JSON数据通信了。原生应用可以通过标准输入/输出来接受/返回数据与 extension 通信。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13833/native-messaging.png" style="display: block; height: 548px; margin-left: auto; margin-right: auto; width: 672px;"></p> + +<p>和 Chrome 相比，WebExtensions 所支持的 native messaging 有2个主要区别：</p> + +<ul> + <li>在 WebExtensions 中，原生应用的清单中的 "allowed_extensions" 字段是一个由 extension ID 组成的数组，而在 Chrome 中，清单中的 "allowed_origins" 字段是一个由 "chrome-extension" URLs 组成的数组</li> + <li>原生应用清单的存储位置不一样</li> +</ul> + +<p>Github 中的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples 仓库</a>有一个<a href="https://github.com/mdn/webextensions-examples/tree/master/native-messaging">完整的关于 native messaging 的例子</a>，文章中的大部分代码片段均出于此。</p> + +<h2 id="安装">安装</h2> + +<h3 id="Extension_的_manifest.json">Extension 的 manifest.json</h3> + +<p>如果你想让你的 extension 与原生应用进行通信，你需要：</p> + +<ul> + <li>你必须在 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 中申请 "nativeMessaging" 的 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">权限</a> 。</li> + <li>你可能需要明确自己 extension 的ID（因为在原生应用的清单中，extension ID将会在被用来识别此 extension 是否被允许与原生应用通信）</li> +</ul> + +<p>这有一个 manifest.json 的例子:</p> + +<pre class="brush: json">{ + + "description": "Native messaging example extension", + "manifest_version": 2, + "name": "Native messaging example", + "version": "1.0", + "icons": { + "48": "icons/message.svg" + }, + + "applications": { + "gecko": { + "id": "ping_pong@example.org", + "strict_min_version": "50.0" + } + }, + + "background": { + "scripts": ["background.js"] + }, + + "browser_action": { + "default_icon": "icons/message.svg" + }, + + "permissions": ["nativeMessaging"] + +}</pre> + +<h3 id="原生应用清单">原生应用清单</h3> + +<p>原生应用清单描述了浏览器如何与原生应用进行连接。</p> + +<p>原生应用清单需要与原生应用一起安装，浏览器仅会查阅清单而不会安装或管理原生应用。因此，何时采用何种方式来安装或更新这些文件的安全模型比起使用WebExtensions APIs 更像原生应用 。（我也搞不懂这句啥意思，原文：Thus the security model for when and how these files are installed and updated is much more like that for native applications than that for extensions using WebExtension APIs.）</p> + +<p>关于原生应用清单的详细语法和路径规则，可参考 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests">原生应用清单</a>。</p> + +<blockquote> +<div class="warning"> +<p>除清单外，原生应用还<strong>必需</strong>配置路径规则，你可以参考 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests">原生应用清单 </a>来配置路径。</p> +</div> +</blockquote> + +<p>这有一个例子，是关于 "ping_pong" 原生应用的清单：</p> + +<pre class="brush: json">{ + "name": "ping_pong", + "description": "Example host for native messaging", + "path": "/path/to/native-messaging/app/ping_pong.py", + "type": "stdio", + "allowed_extensions": [ "ping_pong@example.org" ] +}</pre> + +<p>上面的清单代表：</p> + +<ul> + <li>这个原生应用允许ID为 "ping_pong@example.org" 的 extension 连接，并通过{{WebExtAPIRef("runtime")}} API来传入信息</li> + <li>这个原生应用本身存放在本机的 "/path/to/native-messaging/app/ping_pong.py" 中</li> +</ul> + +<div class="note"> +<p><strong>对于Windows</strong>: 在上面的例子中，原生应用是一个Python脚本，它在Windows下可能是无法运行的。一个代替方案是提供一个 .bat 文件，并且在清单中指向这个 .bat 文件：</p> + +<pre class="brush: json">{ + "name": "ping_pong", + "description": "Example host for native messaging", + "path": "c:\\path\\to\\native-messaging\\app\\ping_pong_win.bat", + "type": "stdio", + "allowed_extensions": [ "ping_pong@example.org" ] +}</pre> + +<p>在 .bat 文件中调用 Python 脚本：</p> + +<pre class="brush: bash">@echo off + +python -u "c:\\path\\to\\native-messaging\\app\\ping_pong.py"</pre> + +<p> </p> +</div> + +<ul> +</ul> + +<h2 id="交换信息">交换信息</h2> + +<p>根据上面的配置，extension已经可以和原生应用交换JSON信息了。</p> + +<h3 id="Extension_端">Extension 端</h3> + +<p>你使用过 <a href="/zh-CN/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">messaging APIs</a> 与 content script 通信，与原生应用通信你应该非常熟悉，有2种方式：</p> + +<ul> + <li>基于连接的通信</li> + <li>无连接的通信（请求/响应 模式）</li> +</ul> + +<h4 id="基于连接的通信">基于连接的通信</h4> + +<p>在这种方式下，你需要调用 {{WebExtAPIRef("runtime.connectNative()")}} 并传入原生应用的名称（名称在原生应用清单中的 "name" 字段定义）。这个操作将会运行原生应用（如果它之前没在运行的话）并返回一个 {{WebExtAPIRef("runtime.Port")}} 。</p> + +<p>当原生应用启动后，它被会传入2个参数：</p> + +<ul> + <li>到原生应用清单的完整路径</li> + <li>（Firefox 55+）启动它的<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications"> extension ID</a></li> +</ul> + +<p>原生应用会一直保持运行，直到 extension 调用 <code>Port.disconnect()</code> 或连接它的记录被结束。</p> + +<p>使用 <code>Port</code> ，调用 <code>postMessage()</code> 传入一个JSON来发送消息，使用 <code>onMessage.addListener()</code> 来接收消息。</p> + +<p>下面是一个例子：background script 建立与 ping_pong 原生应用的链接，并监听原生应用发来的消息。每当browser action 点击时，发送一个 ping 的消息给原生应用。</p> + +<pre class="brush: js">/* +启动，连接 ping_pong 原生应用 +*/ +var port = browser.runtime.connectNative("ping_pong"); + +/* +监听从原生应用发来的消息 +*/ +port.onMessage.addListener((response) => { + console.log("Received: " + response); +}); + +/* +每当 browser action 被点击时，发送一条消息给原生应用 +*/ +browser.browserAction.onClicked.addListener(() => { + console.log("Sending: ping"); + port.postMessage("ping"); +});</pre> + +<h4 id="无连接的通信">无连接的通信</h4> + +<p>在这种模式下你需要调用 {{WebExtAPIRef("runtime.sendNativeMessage()")}} 传入如下参数：</p> + +<ul> + <li>原生应用的名字</li> + <li>要发送是JSON数据</li> + <li>（可选）一个回调函数</li> +</ul> + +<p>每个消息都会创建一个新的原生应用实例。当原生应用启动时会被传入2个参数：</p> + +<ul> + <li>到原生应用清单的完整路径</li> + <li>（Firefox 55+）启动它的<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications"> extension ID</a></li> +</ul> + +<p>原生应用发送的第一条消息将会被作为对 <code>sendNativeMessage()</code> 响应，将会被传入回调函数中。</p> + +<p>这有一个例子，对在上方的代码片段进行重写，改成使用 <code>runtime.sendNativeMessage()</code> 的方式：</p> + +<pre class="brush: js">function onResponse(response) { + console.log("Received " + response); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +/* +每当 browser action 被点击时，发送一条消息给原生应用 +*/ +browser.browserAction.onClicked.addListener(() => { + console.log("Sending: ping"); + var sending = browser.runtime.sendNativeMessage( + "ping_pong", + "ping"); + sending.then(onResponse, onError); +}); +</pre> + +<h3 id="原生应用端">原生应用端</h3> + +<p>在原生应用端，使用标准输入来接受消息，使用标准输出来发送消息。</p> + +<p>每条消息将会被序列化成UTF-8格式的JSON数据，并且在消息前面有一个32位的值来表示该条消息使用本地字节序的长度。</p> + +<p>发送给原生应用的单条消息最大是1MB，总消息不得超越4GB。</p> + +<p>下面是一个用 Python 写的原生应用例子。监听 extensions 发送的消息，如果消息是 ping，则回复 pong：</p> + +<pre class="brush: python">#!/usr/bin/python -u +# Note that running python with the `-u` flag is required on Windows, +# in order to ensure that stdin and stdout are opened in binary, rather +# than text, mode. + +import sys, json, struct + +# 从 stdin 读取解码消息 +def getMessage(): + rawLength = sys.stdin.read(4) + if len(rawLength) == 0: + sys.exit(0) + messageLength = struct.unpack('@I', rawLength)[0] + message = sys.stdin.read(messageLength) + return json.loads(message) + +# 为了能被传输，对给定的内容进行编码 +def encodeMessage(messageContent): + encodedContent = json.dumps(messageContent) + encodedLength = struct.pack('@I', len(encodedContent)) + return {'length': encodedLength, 'content': encodedContent} + +# 向 stdout 发送一个已编码的消息 +def sendMessage(encodedMessage): + sys.stdout.write(encodedMessage['length']) + sys.stdout.write(encodedMessage['content']) + sys.stdout.flush() + +while True: + receivedMessage = getMessage() + if (receivedMessage == "ping"): + sendMessage(encodeMessage("pong")) +</pre> + +<h2 id="关闭原生应用">关闭原生应用</h2> + +<p>如果你通过 <code>runtime.connectNative()</code> 连接原生应用，则原生应用会一直保持运行，直到 extension 调用 <code>Port.disconnect()</code> 或连接它的记录被结束。 如果你通过 <code>runtime.sendNativeMessage()</code> 向原生应用发消息，原生应用会在回复消息后被关闭。</p> + +<p>关闭原生应用的过程：</p> + +<ul> + <li>在 *nix 系统比如 OS X 和Linux 中，浏览器会向原生应用发送 SIGTERM 信号让其可以优雅的退出，然后再发送 SIGKILL 信号。这些信号将会传递给每一个子进程，除非它们分裂成一个新的进程组。</li> + <li>在 Windows 中，浏览器会向原生应用的进程发送一个 <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms684161(v=vs.85).aspx">Job object</a> 并杀死任务，如果原生应用启动任何的额外进程并希望它们能在原生应用被杀死后继续保持运行，原生应用需要在启动进程时使用 <code><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms684863(v=vs.85).aspx">CREATE_BREAKAWAY_FROM_JOB</a></code> 标记。</li> +</ul> + +<h2 id="常见问题_Troubleshooting">常见问题 Troubleshooting</h2> + +<p>如果有什么地方出错，可以检查<a href="/en-US/Add-ons/WebExtensions/Debugging#Viewing_log_output">浏览器控制台</a>。原生应用发送的任何 stderr 都会被反应在浏览器控制台中。所以如果你已经运行了原生应用，你可以看到原生应用发出的所有错误信息。</p> + +<p>如果你没有配置好原生应用，你应该会看到一些错误信息。</p> + +<pre>"No such native application <name>"</pre> + +<ul> + <li>检查 <code>runtime.connectNative()</code> 传入的名称与应用程序清单中的名称一致</li> + <li>OS X/Linux：检查原生应用清单文件的名称是 <name>.json</li> + <li>Windows：检查注册表是否在正确的位置，并且它的名称是否与应用程序清单中的名称一致</li> + <li>Windows：检查注册中给出的路径是否指向的是原生应用清单</li> +</ul> + +<pre>"Error: Invalid application <name>"</pre> + +<ul> + <li>检查原生应用的名称是否有非法字符</li> +</ul> + +<pre>"'python' is not recognized as an internal or external command, ..."</pre> + +<ul> + <li>Windows：如果你的应用是一个Python script，检查你是否已经安装过Python，并为其配置好路径</li> +</ul> + +<pre>"File at path <path> does not exist, or is not executable"</pre> + +<ul> + <li>如果你看见它，意味着应用程序清单已经被找到了</li> + <li>检查应用程序清单的 path 字段是正确的</li> + <li>Windows：检查你是否已经转移过了路径分隔符 ("c:\\path\\to\\file")</li> + <li>检查原生应用是否在原生应用清单中的 path 字段中指向的本地路径</li> + <li>检查原生应用是否可执行</li> +</ul> + +<pre>"This extension does not have permission to use native application <name>"</pre> + +<ul> + <li>检查原生应用清单中的 "allowed_extensions" 字段中是否包含了 extension 的 ID。</li> +</ul> + +<pre>"TypeError: browser.runtime.connectNative is not a function"</pre> + +<ul> + <li>检查 extension 是否已经拥有了 nativeMessaging 权限</li> +</ul> + +<pre>"[object Object] NativeMessaging.jsm:218"</pre> + +<ul> + <li>这是一个启动原生应用时的问题。</li> +</ul> + +<h2 id="与_Chrome_的兼容问题">与 Chrome 的兼容问题</h2> + +<p>{{Page("Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities", "Native_messaging")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/packaging_and_installation/index.html b/files/zh-cn/mozilla/add-ons/webextensions/packaging_and_installation/index.html new file mode 100644 index 0000000000..e0eb081cc7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/packaging_and_installation/index.html @@ -0,0 +1,82 @@ +--- +title: 打包和安装 +slug: Mozilla/Add-ons/WebExtensions/Packaging_and_installation +translation_of: Mozilla/Add-ons/WebExtensions/Temporary_Installation_in_Firefox +--- +<h2 id="打包你的扩展">打包你的扩展</h2> + +<p>Firefox 扩展应打包为 XPI 文件。它只是一个 ZIP 文件，但采用 <code>.xpi</code> 作为扩展名。</p> + +<p>最重要的一点，ZIP 文件必须是扩展文件的 ZIP 打包，<strong>不能</strong>包含一层根目录。</p> + +<h3 id="Windows">Windows</h3> + +<ol> + <li>打开你的扩展文件所在的文件夹。</li> + <li>选择所有文件。</li> + <li>右击并选择 发送到 → 压缩(zipped)文件夹。</li> + <li>将得到的文件从 <code>文件名.zip</code> 重命名为 <code>文件名.xpi</code>。</li> +</ol> + +<p><img alt="Screenshot of the Windows Explorer context menu showing Send to compressed (zipped) folder" src="https://mdn.mozillademos.org/files/11717/pUF1vnr.png" style="height: 641px; width: 904px;"></p> + +<h3 id="Mac_OS_X">Mac OS X</h3> + +<ol> + <li>打开你的扩展文件所在的文件夹。</li> + <li>选择所有文件。</li> + <li>右击并选择 压缩 <em>n</em> 项。</li> + <li>将得到的文件从 <code>Archive.zip</code> 重命名为 <code>文件名.xpi</code>。</li> +</ol> + +<p><img alt="Screenshot of the Finder context menu showing the Compress 15 Items option" src="https://mdn.mozillademos.org/files/11715/Screen%20Shot%202015-10-08%20at%2016.19.02.png" style="height: 460px; width: 850px;"></p> + +<h3 id="Linux_Mac_OS_X_终端">Linux / Mac OS X 终端</h3> + +<ol> + <li><code>cd path/to/my-extension/</code></li> + <li><code>zip -r ../my-extension.xpi *</code></li> +</ol> + +<h2 id="安装你的扩展">安装你的扩展</h2> + +<ol> + <li>导航到 <code>about:addons</code></li> + <li>拖拽 XPI 到页面上，或者打开齿轮菜单，选择“从文件安装附加组件...”</li> + <li>点击弹出的对话框中的“安装”</li> +</ol> + +<h2 id="在_Firefox_OS_上安装你的扩展">在 Firefox OS 上安装你的扩展</h2> + +<p><code>你可以使用 WebIDE 提供的 USB 或者 Wifi 进行安装</code></p> + +<h2 id="故障排除">故障排除</h2> + +<p>下面是几种你可能会遇到的常见问题：</p> + +<h3 id="此附加组件无法安装，因为它未经验证。">"此附加组件无法安装，因为它未经验证。"</h3> + +<ul> + <li>确保你正在使用 <a href="https://nightly.mozilla.org/">Nightly</a> ，并且已在 <code>about:config </code>中将 <code>xpinstall.signatures.required</code> 切换为 <code>false</code>。</li> + <li>在 <a href="/en-US/docs/Mozilla/Add-ons/Distribution">附加组件签名与分发</a> 了解更多信息。</li> +</ul> + +<h3 id="该附加组件无法安装，因为它似乎已损坏。">"该附加组件无法安装，因为它似乎已损坏。"</h3> + +<ul> + <li>确保你是直接压缩你的附加组件文件，<strong>而不是</strong>压缩它们所在的文件夹。你的 manifest.json 文件必须在 zip 文件的根目录中。</li> + <li>确保你正在使用 <a href="https://nightly.mozilla.org/">Nightly</a> 版本的 Firefox。</li> +</ul> + +<h3 id="完全没反应">完全没反应</h3> + +<ul> + <li>确保你的文件名称以 <code>.xpi</code> 结尾，因为某些操作系统可能会隐藏真实的文件扩展名。 + + <ul> + <li>在 Windows 上，选中 查看 → 显示 / 隐藏：文件扩展名。</li> + <li>在 Mac OS X 上，选中 文件 → 获取信息 → 名称和扩展名。</li> + </ul> + </li> + <li>还有一种可能，你不小心点击并因此驳回了安装提示。在 Nightly 中的后退按钮旁边找到一个拼图图标。点击它将重获这个弹出提示。</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html b/files/zh-cn/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html new file mode 100644 index 0000000000..496abe0bd3 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html @@ -0,0 +1,22 @@ +--- +title: 从 Google Chrome 移植 +slug: Mozilla/Add-ons/WebExtensions/Porting_from_Google_Chrome +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension +--- +<div>{{AddonSidebar}}</div> + +<p>使用 WebExtension API 开发的扩展是专为跨浏览器兼容而设计的：很大程度上，该技术与 Google Chrome 和 Opera 支持的<a class="external external-icon" href="https://developer.chrome.com/extensions">扩展 API</a> 代码直接兼容。为这些浏览器编写的扩展，在大多数情况下，只需少数修改就能在 Firefox 中运行。几乎所有的<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API">扩展 API</a> 都支持使用 <code>chrome</code> 命名空间下的回调函数，跟 Chrome 一样。那些仅有的 <code>chrome</code> 命名空间不支持的 API 是故意不与 Chrome 兼容的。这些情况下，API 文档页将明确声明它仅在 <code>browser</code> 命名空间中受支持。从 Chrome 或者 Opera 移植一个扩展的过程大概这样：</p> + +<ol> + <li>检查你 manifest.json 使用的功能并了解 WebExtension API 对应的 <a href="/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">Chrome 不兼容参考表</a>。如果你在使用的功能或者 API 还未被 Firefox 支持，那你可能还不能移植你的扩展。Mozilla 提供了一个服务可助您自动执行此步：<a href="https://www.extensiontest.com/">https://www.extensiontest.com/</a>。</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">安装你的扩展至 Firefox</a> 并对其进行测试。</li> + <li>如有任何问题，可通过 <a class="external external-icon" href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons 邮件列表</a>或 <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a> 上的 <a href="irc://irc.mozilla.org/webextensions">#webextensions</a> 联系我们。</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Publishing_your_WebExtension">提交您的附加组件至 AMO 以供签名及分发</a>。</li> +</ol> + +<p>如果您依赖 Chrome 命令行选项来加载解压的扩展，请参看 Firefox 中进行临时安装的 <a href="/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> 工具以便开发。</p> + +<ul> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/prerequisites/index.html b/files/zh-cn/mozilla/add-ons/webextensions/prerequisites/index.html new file mode 100644 index 0000000000..75abcfb904 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/prerequisites/index.html @@ -0,0 +1,21 @@ +--- +title: 前提条件 +slug: Mozilla/Add-ons/WebExtensions/Prerequisites +tags: + - firefox signature config + - firefox webextension config + - xpi signatures config +translation_of: Mozilla/Add-ons/WebExtensions/Prerequisites +--- +<p>要使用 WebExtension API 进行开发，你需要进行一些最基本的设置。</p> + +<ul> + <li>下载、安装和启动 <a href="https://www.mozilla.org/en-US/firefox/developer/">Firefox Developer Edition</a> 或者 <a class="external text" href="https://nightly.mozilla.org/" rel="nofollow">Firefox Nightly</a>。如果想要使用最近的更新，请使用 Nightly 版本。</li> + <li>调整 Firefox 是否允许你安装未签名附加组件的首选项。需注意，该首选项仅在 Firefox Developer Edition 和 Firefox Nightly 中可用。 + <ul> + <li>在 Firefox 的地址栏中输入 <code>about:config</code></li> + <li>在搜索框中输入 <code>xpinstall.signatures.required</code></li> + <li>双击该首选项，或者右击并选择“切换”，将其设置为 <code>false</code>。</li> + </ul> + </li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/publishing_your_webextension/index.html b/files/zh-cn/mozilla/add-ons/webextensions/publishing_your_webextension/index.html new file mode 100644 index 0000000000..e7792b75d4 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/publishing_your_webextension/index.html @@ -0,0 +1,98 @@ +--- +title: 发布你的附加组件 +slug: Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Package_your_extension_ +--- +<div>{{AddonSidebar}}</div> + +<p>一般当你完成了基于WebExtension技术的附加组件的代码编写和测试, 你可能会想与其他人分享这成果(不管出于什么目的...). Mozilla旗下有一个网站: <a class="external external-icon" href="https://addons.mozilla.org">addons.mozilla.org</a> (简称AMO), 开发者们可以在这里发布附加组件, 而其他用户可以在这里找到这些附加组件并安装使用, 通过在AMO上发布你的附加组件, 你可以加入到我们的社区里来, 这里有一群用户和创造者, 说不准会发现几个使用你的附加组件的人哦.</p> + +<p>你编写的附加组件并不一定需要发布在AMO上， 但是、即使你不打算在AMO上发布你的附加组件, 你也必须提交你的附加组件到AMO上来进行审核以获得签名。因为火狐浏览器会拒绝安装没有AMO签名的附加组件。</p> + +<p>所以发布一个附加组件的流程, 可概述为:</p> + +<ol> + <li>压缩你所创建的附加组件文件</li> + <li>在<a href="https://addons.mozilla.org/zh-CN/">AMO</a>上创建一个属于你的账户</li> + <li>上传你的压缩文件到AMO来进行签名和审核, 并选择是否在AMO上进行发布</li> + <li>修复在审核中发现的任何问题</li> + <li>如果你选择不在AMO上发布, 可以恢复已签名的附件组件, 并自行发布</li> +</ol> + +<p>当你准备发布附加组件的新版本时, 你可以访问 <a class="external external-icon" href="https://addons.mozilla.org">addons.mozilla.org </a>的附加组件页来更新它, 并上传新的版本.<br> + 需要注意的是: 你必须在这个附加组件页进行更新, 否则AMO没法知道你是要更新一个已经存在的附加组件呢, 还是要上传一个全新的附加组件呢.</p> + +<p>如果你选择在AMO上发布你的附加组件, 之后火狐浏览器会自动检查更新. 如果你选择自行发布, 你需要在你的manifest.json中手动设置一个<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> 唯一标识, 并且需要手动设置<code>update_url属性指向你的</code><a href="/en-US/Add-ons/Updates">update manifest file</a>.</p> + +<div class="pull-aside"> +<div class="moreinfo"> +<p>火狐浏览器把附加组件包的后缀叫做或改为".xpi", 这只是".zip"的一个扩展.</p> + +<p>在上传附加组件到AMO的时候, 你不需要把压缩包的后缀改为".XPI".</p> +</div> +</div> + +<h2 id="1._使用zip压缩你的附加组件文件">1. 使用zip压缩你的附加组件文件</h2> + +<p>首先你的附加组件文件夹应该包含一个manifest.json和其他一些需要的文件 - javascript文件, icons文件, HTML文件等等. 你需要使用zip把它们压缩成一个文件以便上传到AMO.</p> + +<p>注意: 请将你的附加组件目录的的所有文件压缩为zip包,而 不要直接对附加组件根目录进行压缩(见下图所示).</p> + +<h3 id="Windows">Windows</h3> + +<ol> + <li>打开你的附加组件所在的文件夹.</li> + <li>选中所有文件.</li> + <li>右键并选择发送到 → 压缩到(zipped)文件夹.</li> +</ol> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11949/install-windows.png" style="display: block; height: 576px; margin-left: auto; margin-right: auto; width: 800px;"></p> + +<h3 id="Mac_OS_X">Mac OS X</h3> + +<ol> + <li>打开你的附加组件所在的文件夹.</li> + <li>选中所有文件.</li> + <li>右键并选择压缩<em>n项</em>.</li> +</ol> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11951/install-osx.png" style="display: block; height: 449px; margin-left: auto; margin-right: auto; width: 800px;"></p> + +<h3 id="Linux_Mac_OS_X_Terminal">Linux / Mac OS X Terminal</h3> + +<ol> + <li><code>cd path/to/my-addon/</code></li> + <li><code>zip -r ../my-addon.zip *</code></li> +</ol> + +<h2 id="2._在AMO上创建一个账户">2. 在AMO上创建一个账户</h2> + +<p>访问<a href="https://addons.mozilla.org/">https://addons.mozilla.org/</a>. 如果你已经有一个<a href="https://support.mozilla.org/zh-CN/kb/firefox-mozilla">火狐账户</a>, 你可以直接使用它来登录. 否则, 点击"注册"并按要求创建一个火狐账户.</p> + +<h2 id="3._上传你的zip压缩文件">3. 上传你的zip压缩文件</h2> + +<p>接下来, 上传压缩后的附加组件到AMO进行签名和审查, 并选择是否发布到AMO, 更多细节, 可查看<a href="/en-US/Add-ons/Distribution#Submitting_to_AMO">Submitting to AMO</a>.</p> + +<div class="note"> +<p>需要注意的是一旦你上传了你的附加组件(基于WebExtension技术)到AMO, 你不能使用Add-on SDK或过时的XUL/XPCOM技术来更新该附加组件. 如果你切换到了这些技术平台之一, 必须把它做为新的附加组件并重新提交.</p> + +<p>总而言之: 像Add-on SDK和XUL/XPCOM等过时的技术体系在不久的将来都将被淘汰, WebExtensions才是唯一.</p> + +<p>在上传你的附加组件之前，请再次检查你的zip包内没有包含其他不相关的文件.</p> +</div> + +<h2 id="4._修复审查中出现的问题">4. 修复审查中出现的问题</h2> + +<p>当你上传了附加组件, AMO服务器将运行一些基本的检查并立即通知你有关的一切问题. 这些问题分为2种类型: "错误"和"警告". 如果你有错误, 你必须修复它们并重新提交, 如果只是警告, 你最好也搞定它们(当可以也忽略警告): 然后可以继续提交.</p> + +<p>如果自动检查器没有报告任何错误, 该附件组件将进行更为详细的审核(复查). 你同样会收到审查结果并且需要修复所有问题, 然后重新提交.</p> + +<h2 id="5._发布你的附加组件">5. 发布你的附加组件</h2> + +<p>如果你选择了在AMO上托管你的附加组件, 这意味着发布过程的结束. AMO会对该附加组件进行签名和发布, 之后其他用户就能下载并安装使用了.</p> + +<p>如果你选择不在AMO上进行发布, 可以恢复已签名的附加组件, 并自行发布(比如把附件组件的压缩包直接发给别人).</p> + +<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/safely_inserting_external_content_into_a_page/index.html b/files/zh-cn/mozilla/add-ons/webextensions/safely_inserting_external_content_into_a_page/index.html new file mode 100644 index 0000000000..d40d36d813 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/safely_inserting_external_content_into_a_page/index.html @@ -0,0 +1,102 @@ +--- +title: Safely inserting external content into a page +slug: Mozilla/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page +translation_of: Mozilla/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page +--- +<p>{{AddonSidebar}}</p> + +<p>很多时候你需要从外部资源引入内容到你的插件。但是，源可能被嵌入了恶意的源代码，这些恶意的源代码可能由源的开发者或者恶意的第三方所编写。</p> + +<p>以RSS读取器为例子。你不知道你的插件将会打开什么RSS源也无法控制那些RSS源的内容。所以，可能用户可能订阅到一个RSS源里面包含了带有恶意脚本的标题。可能就是简单的JavaScript代码标签<script></script>。如果你在提取标题的时候，当作一般文本添加到一个页面的DOM，用户可能加载未知的脚本。因此，需要注意避免直接把一般文本加载为HTML。</p> + +<p>你还需要记住扩展有授权的上下文，例如后台的脚本backgroup scrips以及内容脚本content scripts。最坏的情况里，一个内嵌的洁白你可能运行在一个或多种上下文中，导致一些提取操作。这种情况会导致用户的浏览器暴露在远程攻击下，被注入代码访问用户的重要数据，例如密码、浏览器历史或者浏览器行为等。</p> + +<p>这篇文章说明如何安全的对待远端数据并添加到DOM。</p> + + + +<h2 id="处理任意字符串">处理任意字符串</h2> + +<p>当处理字符串时，有很多推荐的策略来安全添加他们到页面：标准的DOM节点创建方法或jQuery。</p> + +<h3 id="DOM节点创建方法函数">DOM节点创建方法/函数</h3> + +<p>一个轻量级的方法来插入字符串到页面是使用原生的DOM操纵方法/函数: <a href="/en-US/docs/Web/API/Document/createElement"><code>document.createElement</code></a>, <a href="/en-US/docs/Web/API/Element/setAttribute"><code>Element.setAttribute</code></a>, 以及<a href="/en-US/docs/Web/API/Node/textContent"><code>Node.textContent</code></a>. 安全的方法是分别创建节点并使用textContent属性赋值：</p> + +<pre class="brush: js example-good">var data = JSON.parse(responseText); +var div = document.createElement("div"); +div.className = data.className; +div.textContent = "Your favorite color is now " + data.color; +addonElement.appendChild(div);</pre> + +<p>这种方法安全原因是使用<code>.textContent</code> 时会自动消除 <code>data.color</code>.中的任何远程 HTML代码。</p> + +<p>但是要注意，使用原生方法不能保证绝对安全，例如下面的代码：</p> + +<pre class="brush: js example-bad">var data = JSON.parse(responseText); +addonElement.innerHTML = "<div class='" + data.className + "'>" + + "Your favorite color is now " + data.color + + "</div>";</pre> + +<p>在其中，Here, the contents of <code>data.className</code> 或 <code>data.color</code> 的内容可能包含HTML代码使得标签提早关闭，并插入更多的HTML内容，之后关闭另一个标签。</p> + +<p>jQuery</p> + +<p>当使用jQuery的方法如 <code>attr()</code> 和 <code>text()</code> ，会清洗添加到DOM的内容。所以，上面“favorite color”例子采用jQuery实现会形如：</p> + +<pre class="brush: js example-good">var node = $("</div>"); +node.addClass(data.className); +node.text("Your favorite color is now " + data.color); </pre> + +<h2 id="处理HTML内容">处理HTML内容</h2> + +<p>当你知道处理外部源的内容是HTML的时候，添加到页面之前净化HTML是很关键的。净化HTML的最好办法是使用HTML净化的库或者一个带有HTML净化特性的模板引擎。在这一节，我们来看一些合适的工具以及使用方法。</p> + +<h3 id="HTML_净化">HTML 净化</h3> + +<p>An HTML sanitization library strips anything that could lead to script execution from HTML, so you can safely inject complete sets of HTML nodes from a remote source into your DOM. <a href="https://github.com/cure53/DOMPurify">DOMPurify</a>,是一个HTML净化的库，可以脱离任意会导致脚本执行的元素，以便安全注入远端源到HTML节点，这个库被很多不同的安全专家评估过，是很适合这种任务扩展的库。</p> + +<p><a href="https://github.com/cure53/DOMPurify">DOMPurify</a> 有一个简约版用于生产环境，purify.min.js. 你可以使用这个版本来适配你的扩展，例如你可以这样添加:</p> + +<pre class="brush: json">"content_scripts": [ + { + "matches" : ["<all_urls>"], + "js": ["purify.min.js", "myinjectionscript.js"] + } +]</pre> + +<p>之后，在myinjectionscript.js中你可以读取外部HTML并净化，之后添加到页面的DOM中：</p> + +<pre class="brush: js">var elem = document.createElement("div"); +var cleanHTML = DOMPurify.sanitize(externalHTML); +elem.innerHTML = cleanHTML;</pre> + +<p>你可以使用任何方法添加净化后的HTML到DOM，例如jQuery’s <code>.html()</code> 方法。注意这种情况需要使用 Remember though that the <code>SAFE_FOR_JQUERY</code> 标记:</p> + +<pre class="brush: js">var elem = $("<div/>"); +var cleanHTML = DOMPurify.sanitize(externalHTML, { SAFE_FOR_JQUERY: true }); +elem.html(cleanHTML);</pre> + +<h3 id="模板引擎">模板引擎</h3> + +<p>另一个常见的模式是对一个页面创建本地HTML模板并通过远端的值来填空。这种方法被广泛应用，应该注意去避免构造函数的使用，可能会导致执行代码的注入。当模板引擎使用构造函数插入HTML到文档的时候会发生这种情况，如果用来注入原始HTML的变量是远端代码，这就属于上面介绍中的安全风险。</p> + +<p>例如，当使用<a href="https://mustache.github.io/">mustache templates</a> 你必须使用两个花括号<code>\{{variable}}</code>,来去掉任何HTML。使用三个花括号<code>\{\{{variable}}}</code> 必须避免注入原始HTML字符串到模板。</p> + +<p><a href="http://handlebarsjs.com/">Handlebars</a> 工作原理也是类似, <code>\{{variable}}</code> 。同时，如果创造了Handlebars helper使用 <code>Handlebars.SafeString</code> 使用<code>Handlebars.escapeExpression()</code> 来消除任何传给helper的动态参数。<code>Handlebars.SafeString</code> 的结果被认为是安全的，当插入到双handlebars的时候就不会做消除动作。</p> + +<p>在其他模板系统中也有类似的构造函数，需要有同样的考虑。</p> + +<h2 id="其他参考">其他参考</h2> + +<p>关于这个主题更多的信息，可以查看下面的文章</p> + +<ul> + <li> + <p><a href="https://owasp.org/www-community/xss-filter-evasion-cheatsheet">XSS (Cross Site Scripting) Prevention Cheat Sheet</a></p> + </li> +</ul> + +<div id="gtx-trans" style="position: absolute; left: 220px; top: 3487px;"> +<div class="gtx-trans-icon"></div> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html new file mode 100644 index 0000000000..1ec5a5aced --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html @@ -0,0 +1,50 @@ +--- +title: Toolbar button +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +<div>{{AddonSidebar}}</div> + +<p>常说的 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">浏览器动作（browser action）</a>, 指通过在工具栏上上添加新按钮，提供用户互动选项，用户可点击按钮与你的扩展进行互动。<br> + <img alt="" src="https://mdn.mozillademos.org/files/15751/browser-action.png" style="display: block; height: 182px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>工具栏按钮（browser action）与地址栏按钮（page action）极为相似。区分其不同点及使用，请参看 <a href="/en-US/Add-ons/WebExtensions/user_interface/Page_actions#Page_actions_and_browser_actions">Page actions and browser actions</a>.</p> + +<h2 id="指定浏览器动作">指定浏览器动作</h2> + +<p>通过manifest.json里的关键字<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 来定义浏览器动作的属性：</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"browser_action":</span> <span class="punctuation token">{</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span> +<span class="punctuation token">}</span></code></pre> + +<p>必须定义的键是 <code>default_icon</code>.</p> + +<p>有两种方法来指定浏览器动作：带弹出框（<a href="/en-US/Add-ons/WebExtensions/Popups">popup</a>）和不带弹出框（<a href="/en-US/Add-ons/WebExtensions/Popups">popup</a>）。</p> + +<p>如果不指定弹出框，当用户点击按钮时，点击事件将被发送至扩展，而扩展可用以下函数来捕获 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/BrowserAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>browserAction.onClicked</code></a>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">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>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>如果指定了弹出框，当用户点击按钮时，点击事件将不会被发送，而是显示出弹出框。用户能够通过弹出框进行互动，并且点击框外区域时弹出框会自动关闭。请参看文章 <a href="/en-US/Add-ons/WebExtensions/Popups">Popup </a>来了解更多关于创建和管理弹出框的细节。</p> + +<p>注意一个扩展只能指定一个浏览器动作。</p> + +<p>可通过<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API在程序里更改你的浏览器动作的属性。</p> + +<h2 id="图标">图标</h2> + +<p>想了解更多关于如何创建浏览器动作图标信息，请参看<a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> 文档里的 <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> 部分.</p> + +<h2 id="范例">范例</h2> + +<p>在Github上的扩展范例库 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> 中有两个实现浏览器动作的例子：</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> uses a browser action without a popup.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> uses a browser action with a popup.</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html new file mode 100644 index 0000000000..e0647bc543 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html @@ -0,0 +1,466 @@ +--- +title: Browser styles +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +tags: + - Browser style + - WebExtensions + - 扩展程序 + - 指南 + - 浏览器扩展程序 + - 浏览器插件 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +--- +<div>{{AddonSidebar}}</div> + +<p>扩展程序包含的某些UI组件，例如： <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popups</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">sidebars</a>, <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Options_pages">options pages</a> ，实际上可以用如下方式统一定义：</p> + +<ol> + <li>创建一个HTML文件用于描述该UI组件的页面结构</li> + <li>在manifest.json中添加字段 (<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code>, 或 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code>) 以指向其对应的页面</li> +</ol> + +<p>这种方式面临的一个挑战是如何使用浏览器自带的样式，以使得组件的UI表现与浏览器的UI风格相符。要解决这个问题，可以在该字段的配置中增加一个可字段 <code>browser_sytle</code> ，如果设置了这个字段并且值为 <code>true</code> , 那么该UI组件的HTML将会被插入一个或多个样式表，样式表会使你的扩展程序的UI表现与浏览器的风格一致 (并且与其它同样应用了这个字段的扩展程序一致)。</p> + +<p>若使用了 <code>browser_style: true</code> , 你需要在不同的浏览器主题中测试你的扩展程序，以确保其UI表现和期望的一致。 </p> + +<div class="blockIndicator note"> +<p><strong>谷歌浏览器Google Chrome</strong> 和 欧朋浏览器 <strong>Opera</strong> 使用字段名 <code>chrome_style</code> 而非<code>browser_style</code>, 因此如果要适配它们，你需要同时添加这两个字段。</p> +</div> + +<p>在火狐浏览器中，这个样式文件可以在 <code>chrome://browser/content/extension.css</code>查看。为Mac OS X系统额外准备的样式文件也可以在 <code>chrome://browser/content/extension-mac.css</code> 查看。</p> + +<p>大多数样式是自动应用的，但是某些元素需要添加非标准的类名 <code style="white-space: nowrap;">browser-style</code> 来获得其样式，如下表所示：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Element</th> + <th scope="col">Example</th> + </tr> + </thead> + <tbody> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/button"><button></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<button class="browser-style">Click me</button></pre> + </td> + </tr> + <tr> + <td> + <p><code><a href="/en-US/docs/Web/HTML/Element/select"><select></a></code></p> + </td> + <td> + <pre class="brush: html no-line-numbers"> +<select class="browser-style" name="select"> + <option value="value1">Value 1</option> + <option value="value2" selected>Value 2</option> + <option value="value3">Value 3</option> +</select></pre> + </td> + </tr> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/textarea"><textarea></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<textarea class="browser-style">Write here</textarea></pre> + </td> + </tr> + <tr> + <td>Parent of an <code><a href="/en-US/docs/Web/HTML/Element/input"><input></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<div class="browser-style"> + <input type="radio" id="op1" name="choices" value="op1"/> + <label for="op1">Option 1</label> + + <input type="radio" id="op2" name="choices" value="op2"/> + <label for="op2">Option 2</label> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<div class="blockIndicator note"> +<p>查看 {{bug(1465256)}} 以了解相关修订</p> +</div> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<div class="hidden">兼容列表由结构化文件生成，如果你想要贡献此文件，请通过 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 向我们发送pull request.</div> + +<p>{{Compat("webextensions.browser_style")}}</p> + +<h2 id="火狐面板组件Firefox_Panel_Components">火狐面板组件Firefox Panel Components</h2> + +<div class="blockIndicator nonStandard"> +<p><strong>非标准</strong><br> + 此功能不是通用标准，仅支持在firefox中使用</p> +</div> + +<p><code>chrome://browser/content/extension.css</code> 样式文件中也包含了火狐面板组件的样式</p> + +<p><a href="https://firefoxux.github.io/StyleGuide/#/navigation">legacy Firefox Style Guide</a> 使用示例</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Element</th> + <th scope="col">Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>Header</td> + <td> + <pre class="brush: html"> +<header class="panel-section panel-section-header"> + <div class="icon-section-header"><img src="image.svg"/></div> + <div class="text-section-header">Header</div> +</header></pre> + </td> + </tr> + <tr> + <td>Footer</td> + <td> + <pre class="brush: html"> +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + </td> + </tr> + <tr> + <td>Tabs</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-tabs"> + <button class="panel-section-tabs-button selected">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> +</div></pre> + </td> + </tr> + <tr> + <td>Form</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-formElements"> + <div class="panel-formElements-item"> + <label for="name01">Label:</label> + <input type="text" value="Name" id="name01" /> + </div> + <div class="panel-formElements-item"> + <label for="picker01">Label:</label> + <select id="picker01"> + <option value="value1" selected="true">Dropdown</option> + <option value="value2">List Item</option> + <option value="value3">List Item</option> + </select> + </div> + <div class="panel-formElements-item"> + <label for="placeholder01">Label:</label> + <input type="text" placeholder="Placeholder" id="placeholder01" /> + <button name="expander" class="expander"></button> + </div> +</div></pre> + </td> + </tr> + <tr> + <td>Menu</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="Example">Example</h3> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><header class="panel-section panel-section-header"> + <div class="icon-section-header"><!-- An image goes here. --></div> + <div class="text-section-header">Header</div> +</header> + +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div> + +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + +<div class="hidden"> +<h4 id="CSS">CSS</h4> + +<pre class="brush: css">/* Global */ +html, +body { + background: white; + box-sizing: border-box; + color: #222426; + cursor: default; + display: flex; + flex-direction: column; + font: caption; + margin: 0; + padding: 0; + -moz-user-select: none; +} + +body * { + box-sizing: border-box; + text-align: start; +} + +button.panel-section-footer-button, +button.panel-section-tabs-button { + color: inherit; + background-color: unset; + font: inherit; + text-shadow: inherit; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + border: none; +} + +/* Panel Section */ +.panel-section { + display: flex; + flex-direction: row; +} + +.panel-section-separator { + background-color: rgba(0, 0, 0, 0.15); + min-height: 1px; +} + +/* Panel Section - Header */ +.panel-section-header { + border-bottom: 1px solid rgba(0, 0, 0, 0.15); + padding: 16px; +} + +.panel-section-header > .icon-section-header { + background-position: center center; + background-repeat: no-repeat; + height: 32px; + margin-right: 16px; + position: relative; + width: 32px; +} + +.panel-section-header > .text-section-header { + align-self: center; + font-size: 1.385em; + font-weight: lighter; +} + +/* Panel Section - List */ +.panel-section-list { + flex-direction: column; + padding: 4px 0; +} + +.panel-list-item { + align-items: center; + display: flex; + flex-direction: row; + height: 24px; + padding: 0 16px; +} + +.panel-list-item:not(.disabled):hover { + background-color: rgba(0, 0, 0, 0.06); + border-bottom: 1px solid rgba(0, 0, 0, 0.1); + border-top: 1px solid rgba(0, 0, 0, 0.1); +} + +.panel-list-item:not(.disabled):hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-list-item.disabled { + color: #999; +} + +.panel-list-item > .icon { + flex-grow: 0; + flex-shrink: 0; +} + +.panel-list-item > .text { + flex-grow: 10; +} + +.panel-list-item > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; + justify-content: flex-end; +} + +.panel-section-list .panel-section-separator { + margin: 4px 0; +} + +/* Panel Section - Footer */ +.panel-section-footer { + background-color: rgba(0, 0, 0, 0.06); + border-top: 1px solid rgba(0, 0, 0, 0.15); + color: #1a1a1a; + display: flex; + flex-direction: row; + height: 41px; + margin-top: -1px; + padding: 0; +} + +.panel-section-footer-button { + flex: 1 1 auto; + height: 100%; + margin: 0 -1px; + padding: 12px; + text-align: center; +} + +.panel-section-footer-button > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; +} + +.panel-section-footer-button:hover { + background-color: rgba(0, 0, 0, 0.06); +} + +.panel-section-footer-button:hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-section-footer-button.default { + background-color: #0996f8; + box-shadow: 0 1px 0 #0670cc inset; + color: #fff; +} + +.panel-section-footer-button.default:hover { + background-color: #0670cc; + box-shadow: 0 1px 0 #005bab inset; +} + +.panel-section-footer-button.default:hover:active { + background-color: #005bab; + box-shadow: 0 1px 0 #004480 inset; +} + +.panel-section-footer-separator { + background-color: rgba(0, 0, 0, 0.1); + width: 1px; + z-index: 99; +}</pre> + +<hr> +<pre class="brush: css">/* Example specific – not part of chrome://browser/content/extension.css */ +body { + background: #fcfcfc; + background-clip: padding-box; + border: 1px solid rgba(24,26,27,.2); + box-shadow: 0 3px 5px rgba(24,26,27,.1),0 0 7px rgba(24,26,27,.1); + box-sizing: content-box; + margin: 2em auto .5em; + width: 384px; +} + +html { + min-height: 100vh; +} + +html > body { + margin: auto; +} + +.icon-section-header { + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDMyIDMyIj48Y2lyY2xlIGZpbGw9IiMzNjM5NTkiIGN4PSIxNSIgY3k9IjE1IiByPSIxNSIvPjwvc3ZnPg=="); +}</pre> +</div> + +<h4 id="Result若查看失败，请切回英文版查看">Result(若查看失败，请切回英文版查看)</h4> + +<p>{{EmbedLiveSample("Example","640","360")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html new file mode 100644 index 0000000000..2844e7319a --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html @@ -0,0 +1,48 @@ +--- +title: Context menu items +slug: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>This user interface option adds one or more items to a browser context menu. This is the context menu available when a user right-clicks on a web page. Tabs can have context menus also, available through the <a href="/en-US/Add-ons/WebExtensions/API/menus">browser.menus API</a>.</p> + +<p><img alt="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="display: block; height: 587px; margin-left: auto; margin-right: auto; width: 573px;"></p> + +<p>You would use this option to expose features that are relevant to specific browser or web page contexts. For example, you could show features to open a graphic editor when the user clicks on an image or offer a feature to save page content when part of a page is selected. You can add plain menu items, checkbox items, radio button groups, and separators to menus. Once a context menu item has been added using {{WebExtAPIRef("contextMenus.create")}} it's displayed in all browser tabs, but you can hide it by removing it with {{WebExtAPIRef("contextMenus.remove")}}.</p> + +<h2 id="Specifying_context_menu_items">Specifying context menu items</h2> + +<p>You manage context menu items programmatically, using the {{WebExtAPIRef("contextMenus")}} API. However, you need to request the <code>contextMenus</code> permission in your manifest.json to be able to take advantage of the API.</p> + +<pre class="brush: json">"permissions": ["contextMenus"]</pre> + +<p>You can then add (and update or delete) the context menu items in your extension's background script. To create a menu item you specify an id, its title, and the context menus it should appear on:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "log-selection", + title: browser.i18n.getMessage("contextMenuItemSelectionLogger"), + contexts: ["selection"] +}, onCreated);</pre> + +<p>Your extension then listens for clicks on the menu items. The passed information about the item clicked, the context where the click happened, and details of the tab where the click took place can then be used to invoke the appropriate extension functionality.</p> + +<pre class="brush: js">browser.contextMenus.onClicked.addListener(function(info, tab) { + switch (info.menuItemId) { + case "log-selection": + console.log(info.selectionText); + break; + ... + } +})</pre> + +<h2 id="Examples">Examples</h2> + +<p>The <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo on GitHub, contains several examples of extensions that use context menu items:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/menu-demo">menu-demo</a> adds several items to the browser's context menu.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-copy-link-with-types">context-menu-copy-link-with-types</a> adds a context menu item to links that copies the URL to the clipboard, as plain text and rich HTML.</li> +</ul> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html new file mode 100644 index 0000000000..8f55647526 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html @@ -0,0 +1,61 @@ +--- +title: devtools panels +slug: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>This feature is available since Firefox 54.</p> +</div> + +<p>When an extension provides tools that are of use to developers, it's possible to add a UI for them to the browser's developer tools as a new panel.</p> + +<p><img alt='Simple example showing the addition of "My panel" to the Developer Tools tabs.' src="https://mdn.mozillademos.org/files/15746/developer_panel_tab.png" style="display: block; height: 112px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<h2 id="Specifying_a_developer_tools_panel">Specifying a developer tools panel</h2> + +<p>A developer tools panel is added using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.panels">devtools.panels</a></code> API, which in turn needs to be run from a special devtools page.</p> + +<p>Add the devtools page by including the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a></code> key in extension's <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> and provide the location of the page's HTML file in the extension:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"devtools_page":</span> <span class="string token">"devtools-page.html"</span></code></pre> + +<p>From the devtools page, call a script that will add the devtools panel:</p> + +<pre class="brush: html"><body> + <script src="devtools.js"></script> +</body></pre> + +<p>In the script, create the devtools panel by specifying the panel's title, icon, and HTML file that provides the panel's content:</p> + +<pre class="brush: js">function handleShown() { + console.log("panel is being shown"); +} + +function handleHidden() { + console.log("panel is being hidden"); +} + +browser.devtools.panels.create( + "My Panel", // title + "icons/star.png", // icon + "devtools/panel/panel.html" // content +).then((newPanel) => { + newPanel.onShown.addListener(handleShown); + newPanel.onHidden.addListener(handleHidden); +});</pre> + +<p>The extension can now run code in the inspected window using <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow/eval"><code>devtools</code>.inspectedWindow.eval()</a></code> or by injecting a content script via the background script by passing a message. You can find more details on how to do this in <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools.</a></p> + +<h2 id="Developer_panel_design">Developer panel design</h2> + +<p>For details on how to design your developer panel's web page to match the style of Firefox, see the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Icons">Icons</h2> + +<p>For details on how to create icons to use with your developer tools panel, see <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> in the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Examples">Examples</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a href="https://github.com/mdn/webextensions-examples/blob/master/devtools-panels/">devtools-panels</a> example which implements a devtools panel.</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..f34e594284 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,92 @@ +--- +title: User interface +slug: Mozilla/Add-ons/WebExtensions/user_interface +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>为了能给用户提供在不同场景下都具有价值的功能， WebExtensions 提供了许多的用户界面选项。下面是这些选项的摘要，在本章中将会对每个选项做出更详细的说明。</p> + +<div class="note"> +<p>想要使你的扩展能提供良好的用户体验吗? 请查看文章<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_experience_best_practices">用户体验的最佳实践</a> .</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">UI 选项</th> + <th scope="col">描述</th> + <th scope="col" style="width: 350px;">实例</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">浏览器工具栏按钮</a>(浏览器行为)</td> + <td>工具栏上一个可点击的按钮，点击时将事件派发到附件组件上。默认情况下，这个按钮在栏位中是可见的。</td> + <td><img alt="Example of a WebExtension toolbar button" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="height: 99px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">带有弹出面板的工具栏按钮</a></td> + <td>当这个在工具栏上的按钮被点击时，它会弹出一个面板。这个面板使用 HTML 文档编写，用于处理与用户的交互行为。</td> + <td><img alt="Example of a WebExtension toolbar button with a popup" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="height: 156px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">地址栏菜单按钮</a>(页面行为)</td> + <td>这个按钮位于浏览器地址栏菜单条，按钮被点击的时候可以派发一个事件出来。默认情况下，这个按钮在所有tab上都是隐藏的.</td> + <td><img alt="Example showing an address bar button (page action)" src="https://mdn.mozillademos.org/files/15047/address_bar_button.png" style="height: 127px; width: 350px;"></td> + </tr> + <tr> + <td>带有<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">弹出面板</a>的地址栏菜单按钮</td> + <td>地址栏菜单按钮被点击时，会弹出一个面板，这个面板通过HTML文档定义,用于处理用户交互。</td> + <td><img alt="Example of a popup on the address bar button" src="https://mdn.mozillademos.org/files/15053/page_action_popup.png" style="height: 250px; width: 330px;"></td> + </tr> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">上下文菜单项</a></td> + <td>在一个或多个网页上下文菜单中的菜单项,复选框和单选按钮.菜单项也可以通过添加分隔栏进行分组,当一个菜单项被点击时,一个事件将会被派发至附加组件.</td> + <td><img alt="" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="height: 359px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">侧边栏</a></td> + <td> + <p dir="ltr">一个在网页边显示的HTML文档,每页都有其特定的内容. 每当扩展安装时侧边栏将会打开,但最终还是遵循用户的侧边栏可见性设置. 侧边栏内的用户交互通过HTML文档处理.</p> + </td> + <td><img alt="Example of a WebExtension's sidebar" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="height: 209px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">选项页面</a></td> + <td>一个可以使你定义可以更改的扩展首选项的页面. 用户可以从浏览器的附加组件管理器中访问此页面.</td> + <td><img alt="Example showing the options page content added in the favorite colors example." src="https://mdn.mozillademos.org/files/15055/options_page.png" style="height: 259px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">扩展页面</a></td> + <td> + <p>在单独的窗口或页面中使用扩展提供的页面来提供表单,帮助或其他任何需要的内容.</p> + </td> + <td><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15063/bundled_page_as_panel_small.png" style="height: 180px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">通知</a></td> + <td>通过底层操作系统的通知机制向用户显示的短暂通知. 当用户点击或者通知关闭时(用户关闭或超时关闭)派发事件到扩展程序.</td> + <td><img alt="Example notification from a WebExtension" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="height: 95px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">地址栏建议</a></td> + <td>当用户输入关键词时提供自定义的地址栏建议.</td> + <td><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15059/omnibox_example_small.png" style="height: 242px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">开发者工具面板</a></td> + <td>在浏览器的开发者工具中显示的一个关联了HTML文档的标签.</td> + <td><img alt="New panel tab in the Developer Tools tab bar" src="https://mdn.mozillademos.org/files/15049/developer_panel_tab.png" style="height: 180px; width: 350px;"></td> + </tr> + </tbody> +</table> + +<p>以下的操作指南提供了一些创建用户界面选项的指导;</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">在工具栏中添加一个按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">实现一个设置页面</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">扩展开发人员工具</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Browser_styles">浏览器样式</a></li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html new file mode 100644 index 0000000000..fe3901c4a8 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html @@ -0,0 +1,93 @@ +--- +title: 地址栏按钮 +slug: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +--- +<div>{{AddonSideBar}}</div> + +<div>通常来说的page action，是添加到浏览器地址栏中的按钮。用户通过点击这个按钮与你的扩展进行交互。</div> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15745/address_bar_button.png" style="display: block; height: 174px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<h2 id="地址栏按钮（Page_actions）和工具栏按钮（_browser_actions）">地址栏按钮（Page actions）和工具栏按钮（ browser actions）</h2> + +<p>地址栏按钮(或 page action) 与工具栏按钮(或 browser action)非常相似。</p> + +<p>其不同之处为：</p> + +<ul> + <li>位置： + <ul> + <li>地址栏按钮是显示在浏览器的地址栏内；</li> + <li>工具栏按钮不是显示在地址栏内，而是在浏览器的工具栏上。</li> + </ul> + </li> + <li>可见性： + <ul> + <li>地址栏按钮默认是隐藏的（尽管可以通过manifest中“show_matches和hide_matches来改变），而你可以在特定tabs中调用pageAction.show()和pageAction.hide()来显示或隐藏它。</li> + <li>工具栏按钮总是可见的。</li> + </ul> + </li> +</ul> + +<p>当动作（行为）与当前页面关联时，使用地址栏按钮，而当动作（行为）与浏览器相关或与多个页面相关时使用工具栏按钮。例如：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row">类型</th> + <th scope="col">书签动作</th> + <th scope="col">内容动作</th> + <th scope="col">标签操作</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">page action</th> + <td>将本页面保存到书签</td> + <td>Reddit enhancement</td> + <td>Send tab</td> + </tr> + <tr> + <th scope="row">browser action</th> + <td>显示所有书签</td> + <td>使能ad-blocking</td> + <td>同步所有打开的标签</td> + </tr> + </tbody> +</table> + +<p> </p> + +<h2 id="定义地址栏按钮">定义地址栏按钮</h2> + +<p>你可以在manifest.json中使用page_action键定义地址栏按钮的属性：</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"page_action":</span> <span class="punctuation token">{</span> + <span class="key token">"browser_style":</span> <span class="keyword token">true</span><span class="punctuation token">,</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span> +<span class="punctuation token">}</span></code></pre> + +<p>仅default_icon是强制（必需）的。</p> + +<p>有两种方式定义地址栏按钮：带popup窗口和无popup窗口。如果你没有指定一个popup，则当用户点击此按钮时，事件被派送到使用<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction/onClicked">pageAction.onClicked</a>侦听器的扩展：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>pageAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>如果你指定了一个popup，则点击事件不被派送，在用户点击按钮时显示popup。用户可以与popup进行交互，并且当用户点击popup以外区域时，popup自动关闭。参见<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Popups">Popup</a>可获得创建和管理popups更详细内容。</p> + +<p>注意你的扩展只能有一个地址栏按钮。</p> + +<p>通过使用<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a> API，你可以以编程方式修改地址栏按钮的任何属性。</p> + +<h2 id="Icons">Icons</h2> + +<p>如何创建用于地址栏按钮的ICONS的详细内容，请参见<a href="https://design.firefox.com/photon/index.html">Photon Design System</a>文档中的<a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a>节。</p> + +<h2 id="示例">示例</h2> + +<p>GitHub上的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> 库中包括了实现无popup地址栏按钮的例子 <a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a> 。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html new file mode 100644 index 0000000000..8d13bfaf2c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html @@ -0,0 +1,53 @@ +--- +title: 侧边栏 +slug: Mozilla/Add-ons/WebExtensions/user_interface/侧边栏 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>A sidebar is a pane that is displayed at the side of the browser window, next to the web page. The browser provides a UI that enables the user to see the currently available sidebars and to select a sidebar to display. For example, Firefox has a "View > Sidebar" menu. Only one sidebar can be shown at a time, and that sidebar will be displayed for all tabs and all browser windows.</p> + +<p>The browser may include a number of built-in sidebars. For example, Firefox includes a sidebar for interacting with bookmarks:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15755/bookmarks-sidebar.png" style="display: block; height: 423px; margin-left: auto; margin-right: auto; width: 350px;">Using the <code>sidebar_action</code> manifest.json key, an extension can add its own sidebar to the browser. It will be listed alongside the built-in sidebars, and the user will be able to open it using the same mechanism as for the built-in sidebars.</p> + +<p>就像浏览器的弹出页面，侧边栏也是一个HTML文档。当用户打开侧边栏时，HTML文档载入打开的浏览器窗口。每个窗口有一个该文档的实例。打开一个新窗口时，该窗口获得自己的文档实例</p> + +<p>可以使用函数{{WebExtAPIRef("sidebarAction.setPanel()")}}指定侧边栏仅用于指定的某个标签，使用{{WebExtAPIRef("windows.getCurrent()")}} 侧边栏知道自己属于哪一个标签。</p> + +<pre class="brush: js">// sidebar.js +browser.windows.getCurrent({populate: true}).then((windowInfo) => { + myWindowId = windowInfo.id; +});</pre> + +<p>不同的窗口使用不同的侧边栏是非常有用的，这是一个实例 ，见<a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">"annotate-page" example</a>.</p> + +<p>侧边栏俱有和后台程序以及弹出窗口相同的API权限，在非隐藏模式下，侧边栏使用API {{WebExtAPIRef("runtime.getBackgroundPage()")}} 可以直接访问后台页面，使用 API 如{{WebExtAPIRef("tabs.sendMessage()")}} 与content scripts交互，使用API 如 {{WebExtAPIRef("runtime.sendNativeMessage()")}} 与原生应用交互。</p> + +<p>关闭窗口或关闭侧边栏时，侧边栏文档退出。这意味着和后台页面不同，侧边栏文档不是一直住留，也不像弹出窗口，只要用户与页面交互 ，它就一直存在。</p> + +<p>使用侧边栏的扩展载入时，侧边栏自动打开。这是为了帮助用户知道扩展俱有侧边栏。注意不能通过编程的方式打开侧边栏：侧边栏只能由用户打开。</p> + +<h2 id="声明侧边栏">声明侧边栏</h2> + +<p>声明侧边栏，只需在manifest.json中指 定关键字 <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code> 并同时指定title 和 icon:</p> + +<pre class="brush: json">"sidebar_action": { + "default_title": "My sidebar", + "default_panel": "sidebar.html", + "default_icon": "sidebar_icon.png" +}</pre> + +<p>使用API {{WebExtAPIRef("sidebarAction")}} ，你可以用编程的方式修改title panel icon。</p> + +<p>浏览器提供的显示侧边栏的UI中，title和icon显示给用户，如Firefox菜单栏的"View > Sidebar"</p> + +<h2 id="Sidebar_design">Sidebar design</h2> + +<p>For details on how to design your sidebar's web page to match the style of Firefox, see the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Example">Example</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">annotate-page</a> example which implements a sidebar.</p> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/walkthrough/index.html b/files/zh-cn/mozilla/add-ons/webextensions/walkthrough/index.html new file mode 100644 index 0000000000..962e04d404 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/walkthrough/index.html @@ -0,0 +1,488 @@ +--- +title: 你的第二个 WebExtension +slug: Mozilla/Add-ons/WebExtensions/Walkthrough +translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +--- +<p>{{AddonSidebar}}</p> + +<p>如果你已经阅读了 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">你的第一个扩展</a>，那么你现在已经知道如何写一个扩展了。在这篇文章，我们将写一个稍微复杂一点点的扩展来为你展示更多的一些API 。</p> + +<p>这个扩展会添加一个新按钮到 Firefox 的工具栏。在用户点击该按钮时，我们会显示一个弹出窗（popup）来让他们选择一种动物。在他们选择之后，我们会将当前网页替换为他所选动物的图片。</p> + +<p>要实现这点，我们将：</p> + +<ul> + <li><strong>定义一个浏览器动作(browser action)，这用来附加一个按钮到 Firefox 的工具栏。</strong><br> + 对于该按钮，我们将提供： + <ul> + <li>一个文件名为 "beasts-32.png" 的图标</li> + <li>按钮被按下时要打开的弹出窗。该弹出窗将包含 HTML、CSS 和 JavaScript。</li> + </ul> + </li> + <li><strong>为扩展定义一个图标</strong>，叫做“beasts-48.png”。这个将会在Add-ons管理器中显示。</li> + <li><strong>写一个内容脚本 "beastify.js"，用于注入到网页中。</strong><br> + 这是用来实际修改页面的代码。</li> + <li><strong>打包一些动物的图像，用以替换网页中的图像。</strong><br> + 我们让图像成为 “Web 可访问资源”（ web accessible resources ），以便页面可以引用它们。</li> +</ul> + +<p>你可以想象这样的扩展的整体结构：</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13671/Untitled-1.png"></p> + +<p>这是一个非常简单的扩展，但也展示了 WebExtensions API 的许多基本概念：</p> + +<ul> + <li>添加一个按钮到工具栏</li> + <li>定义一个将使用 HTML、CSS 和 JavaScript 的弹出窗</li> + <li>注入content scripts到网页</li> + <li>content scripts与扩展的其他部分之间的通信</li> + <li>打包你的扩展的资源，使其可被网页所用</li> +</ul> + +<p>你可以在 GitHub 找到<a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">该扩展的完整的源代码</a>。</p> + +<p>写这个扩展，你需要45或更高版本的firefox。</p> + +<h2 id="编写扩展">编写扩展</h2> + +<p>创建一个新目录，并切换到该目录：</p> + +<ol> + <li> + <pre class="brush: bash">mkdir beastify +cd beastify</pre> + </li> +</ol> + +<h3 id="manifest.json">manifest.json</h3> + +<p>现在创建一个名为 "manifest.json" 的文件，并对其添加下列内容：</p> + +<ol> + <li> + <pre><code>{ + + "manifest_version": 2, + "name": "Beastify", + "version": "1.0", + + "description": "Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. See https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#beastify", + "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/beastify", + "icons": { + "48": "icons/beasts-48.png" + }, + + "permissions": [ + "activeTab" + ], + + "browser_action": { + "default_icon": "icons/beasts-32.png", + "default_title": "Beastify", + "default_popup": "popup/choose_beast.html" + }, + + "web_accessible_resources": [ + "beasts/frog.jpg", + "beasts/turtle.jpg", + "beasts/snake.jpg" + ] + +}</code></pre> + </li> +</ol> + +<ul> + <li>最开始的三个属性: <strong><code>manifest_version</code></strong>, <strong><code>name</code></strong>, <strong><code>version</code></strong>, 是必须的并且包含了插件最基本的信息。</li> + <li><a href="/zh-CN/docs/Mozilla/Tech/XUL/Attribute/description">description </a>和 <a href="/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url </a>是可选的，但是推荐填写，因为它们提供关于扩展的有用信息。</li> + <li><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/icons">icons </a>也是可选但推荐的，它决定了插件在附加组件中的图标。</li> + <li><strong><code>permissions</code></strong> 列出了插件所需要的权限。在这里我们仅需要 <a href="/zh-CN/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">activeTab permission</a>。</li> + <li><strong><code>browser_action</code></strong> 指定了工具栏按钮。我们在这里提供了三个信息片段: + <ul> + <li><strong><code>default_icon</code></strong> 是必须的，指定了按钮的图标。</li> + <li><strong><code>default_title</code></strong> 是可选的，用于按钮的提示。</li> + <li><strong><code>default_popup</code></strong> 在你想要当用户点击按钮时显示出一个弹出窗时使用。而在这里，我们需要，所以我们列入这个键并将其指向扩展中包括的一个HTML文件。</li> + </ul> + </li> + <li><strong><code>web_accessible_resources</code></strong> 列出了页面可访问的资源。例如由于当前插件使用动物图像替换了页面原有的图像，当前的动物图像要可以被页面访问。</li> +</ul> + +<p>需要注意，所有路径是相对于 manifest.json 。</p> + +<h3 id="图标">图标</h3> + +<p>插件应该有一个图标。这个图标被用于显示在附加组件管理器中（可以通过"about:addons"来访问）。当前插件中manifest.json指定了我们插件的图标位于"icons/beasts-48.png"。</p> + +<p>创建“icons”文件夹，并将图标命名为“beasts-48.png”。你可以使用我们例子中的<a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-48.png">图标</a>，它是从 <a href="https://www.iconfinder.com/iconsets/free-retina-icon-set">Aha-Soft’s Free Retina iconset</a> 截取的，使用需要遵循该网站的<a href="http://www.aha-soft.com/free-icons/free-retina-icon-set//zh-CN/docs/">许可证</a>。</p> + +<p>如果你使用自己的图标，它的尺寸应该是48<math><semantics><mo>×</mo><annotation encoding="TeX">\times</annotation></semantics></math>48像素的。同时，对于高分辨率的设备，可以提供96<math><semantics><mo>×</mo><annotation encoding="TeX">\times</annotation></semantics></math>96像素的图片。此时，manifest.json应当这样配置：</p> + +<ol> + <li> + <pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/beasts-48.png"</span><span class="punctuation token">,</span> + <span class="key token">"96":</span> <span class="string token">"icons/beasts-96.png"</span> +<span class="punctuation token">}</span></code></pre> + </li> +</ol> + + + +<h3 id="工具栏按钮">工具栏按钮</h3> + +<p>工具栏按钮也需要一个图标，并且我们的 manifest.json 承诺我们会为该工具栏在 "icons/beasts-32.png" 提供一个图标。</p> + +<p>将一个图标命名为为 "beasts-32.png"并保存到"icons"文件夹。你可以使用例子中的<a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png">图片</a>，它是取自 <a href="http://www.iconbeast.com/free">IconBeast Lite 图标集</a>并按其<a href="http://www.iconbeast.com/faq/">许可协议</a>授权使用。</p> + +<p>如果你没有弹出窗，用户点击的事件会直接分派到你的插件中。<span style="line-height: 1.5;">如果你制作了弹出窗，用户点击会直接打开这个弹出窗，而不会被分派给插件。</span><span style="line-height: 1.5;">本例中我们需要弹出窗，因此我们现在开始写它。</span></p> + +<h3 id="弹出窗">弹出窗</h3> + +<p>该弹出窗的函数是让用户选择三种动物的其中一种。</p> + +<p>在根目录下创建“popup”文件夹，用于存放弹出窗的代码。弹出窗由以下文件组成：</p> + +<ul> + <li><strong><code>choose_beast.html</code></strong> 定义了界面的主面板</li> + <li><strong><code>choose_beast.css</code></strong> 美化内容</li> + <li><strong><code>choose_beast.js</code></strong> 通过在当前活跃的标签页中运行内容脚本（content script）处理用户的选择</li> +</ul> + +<pre class="brush: bash line-numbers language-bash"><code class="language-bash"><span class="function token">mkdir</span> popup +<span class="function token">cd</span> popup +<span class="function token">touch</span> choose_beast.html choose_beast.css choose_beast.js</code></pre> + +<h4 id="choose_beast.html">choose_beast.html</h4> + +<p>HTML 文件就像这样:</p> + +<ol> + <li> + <pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_beast.css"/> + </head> + +<body> + <div id="popup-content"> + <div class="button beast">Frog</div> + <div class="button beast">Turtle</div> + <div class="button beast">Snake</div> + <div class="button reset">Reset</div> + </div> + <div id="error-content" class="hidden"> + <p>Can't beastify this web page.</p><p>Try a different page.</p> + </div> + <script src="choose_beast.js"></script> +</body> + +</html></pre> + </li> +</ol> + +<p>我们有一个ID为 <code>"popup-content"</code> 的<a href="/zh-CN/docs/Web/HTML/Element/div"><div></a>元素包含了每个动物选择。我们还有另外一个<code><div></code> 元素，它的ID为 <code>"error-content"</code> ，class为<code>"hidden"</code>。我们将会使用它以防初始化弹窗的时候出问题。</p> + +<p>注意我们引入了CSS和JS文件，就像网页一样。</p> + +<h4 id="choose_beast.css">choose_beast.css</h4> + +<p>CSS 固定了弹出窗的大小，确保3个选择填充满空间，并给了他们基本点样式。同时隐藏了<code>class="hidden"</code>的元素，这意味着我们的<code>"error-content"</code> <code><div></code> 将会被默认隐藏：</p> + +<ol> + <li> + <pre class="brush: css">html, body { + width: 100px; +} + +.hidden { + display: none; +} + +.button { + margin: 3% auto; + padding: 4px; + text-align: center; + font-size: 1.5em; + cursor: pointer; +} + +.beast:hover { + background-color: #CFF2F2; +} + +.beast { + background-color: #E5F2F2; +} + +.reset { + background-color: #FBFBC9; +} + +.reset:hover { + background-color: #EAEA9D; +}</pre> + </li> +</ol> + +<h4 id="choose_beast.js">choose_beast.js</h4> + +<p>我们在弹出窗的脚本中监听点击事件。 如果用户选择其中一个动物，我们在当前标签页中插入一段内容脚本。一旦内容脚本加载，我们发送一条有关动物选择的信息:</p> + +<ol> + <li> + <pre class="brush: js">/** + * CSS to hide everything on the page, + * except for elements that have the "beastify-image" class. + */ +const hidePage = `body > :not(.beastify-image) { + display: none; + }`; + +/** + * Listen for clicks on the buttons, and send the appropriate message to + * the content script in the page. + */ +function listenForClicks() { + document.addEventListener("click", (e) => { + + /** + * Given the name of a beast, get the URL to the corresponding image. + */ + function beastNameToURL(beastName) { + switch (beastName) { + case "Frog": + return browser.extension.getURL("beasts/frog.jpg"); + case "Snake": + return browser.extension.getURL("beasts/snake.jpg"); + case "Turtle": + return browser.extension.getURL("beasts/turtle.jpg"); + } + } + + /** + * Insert the page-hiding CSS into the active tab, + * then get the beast URL and + * send a "beastify" message to the content script in the active tab. + */ + function beastify(tabs) { + browser.tabs.insertCSS({code: hidePage}).then(() => { + let url = beastNameToURL(e.target.textContent); + browser.tabs.sendMessage(tabs[0].id, { + command: "beastify", + beastURL: url + }); + }); + } + + /** + * Remove the page-hiding CSS from the active tab, + * send a "reset" message to the content script in the active tab. + */ + function reset(tabs) { + browser.tabs.removeCSS({code: hidePage}).then(() => { + browser.tabs.sendMessage(tabs[0].id, { + command: "reset", + }); + }); + } + + /** + * Just log the error to the console. + */ + function reportError(error) { + console.error(`Could not beastify: ${error}`); + } + + /** + * Get the active tab, + * then call "beastify()" or "reset()" as appropriate. + */ + if (e.target.classList.contains("beast")) { + browser.tabs.query({active: true, currentWindow: true}) + .then(beastify) + .catch(reportError); + } + else if (e.target.classList.contains("reset")) { + browser.tabs.query({active: true, currentWindow: true}) + .then(reset) + .catch(reportError); + } + }); +} + +/** + * There was an error executing the script. + * Display the popup's error message, and hide the normal UI. + */ +function reportExecuteScriptError(error) { + document.querySelector("#popup-content").classList.add("hidden"); + document.querySelector("#error-content").classList.remove("hidden"); + console.error(`Failed to execute beastify content script: ${error.message}`); +} + +/** + * When the popup loads, inject a content script into the active tab, + * and add a click handler. + * If we couldn't inject the script, handle the error. + */ +browser.tabs.executeScript({file: "/content_scripts/beastify.js"}) +.then(listenForClicks) +.catch(reportExecuteScriptError);</pre> + </li> +</ol> + +<p>从96行开始。只要弹出窗加载完，popup scrpit 就会使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript()</a></code> API在活跃标签页执行 content script。如果执行 content scrpit成功，content script会在页面中一直保持，直到标签被关闭或者用户导航到其他页面。</p> + +<p><code>browser.tabs.executeScript()</code>调用失败的常见原因是你不能在所有页面执行content scripts。例如，你不能在特权浏览器页面执行，像about:debugging，你也不能在<a href="https://addons.mozilla.org/">addons.mozilla.org</a>域执行。如果调用失败，<code>reportExecuteScriptError()</code>会隐藏<code>"popup-content"</code> <code><div></code>，并展示<code>"error-content"</code> <code><div></code>, 然后打印一个错误到<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging">控制台</a>。</p> + +<p>如果成功执行 content script ，我们会调用 <code>listenForClicks()</code>。这个监听了弹窗上的点击事件。</p> + +<ul> + <li>如果点击有 <code>class="beast"</code>的按钮上，将会调用 <code>beastify()</code>.</li> + <li>如果点击有 <code>class="reset"</code>的按钮上，将会调用 <code>reset()</code>.</li> +</ul> + +<p><code>beastify()</code> 函数做了三件事：</p> + +<ul> + <li>将被点击的按钮映射到一个指向特定动物图片的URL</li> + <li>通过<code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS()</a></code> API 向页面注入一些CSS来隐藏整个页面的内容</li> + <li>通过<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">browser.tabs.sendMessage()</a></code> API 向 content script 发送“beastify”信息，要求其 beastify 页面，同时向其传递一个指向动物图片的URL</li> +</ul> + +<p><code>reset()</code> 函数实际上就是撤销 beastify :</p> + +<ul> + <li>通过 <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/removeCSS">browser.tabs.removeCSS()</a></code> API 移除我们添加的CSS</li> + <li>向 content script 发送“reset”信息要求其重置页面</li> +</ul> + +<h3 id="The_content_script">The content script</h3> + +<p>在扩展的根目录下创建一个新的文件夹，叫做"content_scripts"，然后在里面新建一个新的名为 "beastify.js" 的文件，内容如下：</p> + +<ol> + <li> + <pre class="brush: js">(function() { + /** + * Check and set a global guard variable. + * If this content script is injected into the same page again, + * it will do nothing next time. + */ + if (window.hasRun) { + return; + } + window.hasRun = true; + + /** + * Given a URL to a beast image, remove all existing beasts, then + * create and style an IMG node pointing to + * that image, then insert the node into the document. + */ + function insertBeast(beastURL) { + removeExistingBeasts(); + let beastImage = document.createElement("img"); + beastImage.setAttribute("src", beastURL); + beastImage.style.height = "100vh"; + beastImage.className = "beastify-image"; + document.body.appendChild(beastImage); + } + + /** + * Remove every beast from the page. + */ + function removeExistingBeasts() { + let existingBeasts = document.querySelectorAll(".beastify-image"); + for (let beast of existingBeasts) { + beast.remove(); + } + } + + /** + * Listen for messages from the background script. + * Call "beastify()" or "reset()". + */ + browser.runtime.onMessage.addListener((message) => { + if (message.command === "beastify") { + insertBeast(message.beastURL); + } else if (message.command === "reset") { + removeExistingBeasts(); + } + }); + +})();</pre> + </li> +</ol> + +<p>content script做的第一件事是检查全局变量 <code>window.hasRun</code>：如果它被设置了，脚本直接返回，否则设置<code>window.hasRun</code>并继续。原因是每次用户打开弹出窗，弹出窗就会在活跃页面执行一个content script ，所以我们可能会在单个页面运行多个脚本实例。如果是这样的话，我们需要保证只有一个实例在做所有事情。</p> + +<p>然后，从第40行开始，content script 监听来自弹出窗的信息，使用<code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code> API。在上面我们看到弹出窗脚本能够发送两种不同的信息："beastify" and "reset"。</p> + +<ul> + <li>如果信息是 "beastify"，我们期待它包含一个指向动物图片的URL。我们移除先前调用添加的动物图片，然后构造并添加一个 src属性被设置动物图片URL 的<code><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img"><img></a></code> 元素。</li> + <li>如果信息是 "reset"，我们只需要移除所有被添加的动物片。</li> +</ul> + +<h3 id="动物们">动物们</h3> + +<p>最后，我们要加入包含动物们的图像。</p> + +<p>创建"beasts"文件夹，之后将图片放入并命名。你可以从 <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts">the GitHub repository</a>,或这里下载图片:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11459/frog.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11461/snake.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11463/turtle.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"></p> + +<h2 id="测试">测试</h2> + +<p>请仔细确认项目目录如下所示:</p> + +<ol> + <li> + <pre><code>beastify/ + + beasts/ + frog.jpg + snake.jpg + turtle.jpg + + content_scripts/ + beastify.js + + icons/ + beasts-32.png + beasts-48.png + + popup/ + choose_beast.css + choose_beast.html + choose_beast.js + + manifest.json</code></pre> + </li> +</ol> + +<p>Firefox 45开始，你可以临时从硬盘中安装扩展</p> + +<p>在Firefox地址栏中输入：about:debugging，单击“临时载入附加组件”，然后选择你的manifest.json文件。</p> + +<p>然后你应该已经看到扩展图标出现在了Firefox的工具条上：</p> + +<p>{{EmbedYouTube("sAM78GU4P34")}}</p> + +<p>打开一个网页，然后点击图标，选择一个动物，然后观察网页的变化</p> + +<p>{{EmbedYouTube("YMQXyAQSiE8")}}</p> + +<h2 id="用命令行开发">用命令行开发</h2> + +<p>你可以通过使用 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> 工具来将临时安装的工作自动化，试试这个：</p> + +<ol> + <li> + <pre class="brush: bash"><code>cd beastify +web-ext run</code></pre> + </li> +</ol> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/what_are_webextensions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/what_are_webextensions/index.html new file mode 100644 index 0000000000..d327d3bd6a --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/what_are_webextensions/index.html @@ -0,0 +1,61 @@ +--- +title: 扩展是什么？ +slug: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +tags: + - Add-ons + - WebExtensions + - 拓展 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>扩展为浏览器添加特性与功能。它通过熟悉的 web 技术——HTML，CSS 还有 JavaScript 来创建。扩展可以利用网页上的 JavaScript 使用同一批 API，但扩展也可以访问扩展自己专用的 JavaScript API。这意味着，和在网页里编码相比，在扩展中，可以做到更加多的事情。以下是其中一些你可以做的事情的示例：</p> + +<p><strong>提升或补充网站功能：</strong>用扩展来实现额外的浏览器内的特性或者来自于你网站的信息。它允许用户搜集他们访问过的页面细节来提升你所提供的服务。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15808/Amazon_add_on.png"></p> + +<p>示例: <a href="https://addons.mozilla.org/zh-CN/firefox/addon/amazon-browser-bar/">亚马逊助手</a>, <a href="https://addons.mozilla.org/zh-CN/firefox/addon/onenote-clipper/">OneNote Web Clipper</a>, 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/grammarly-1/">Grammarly for Firefox</a></p> + +<p><strong>让用户展现他们的个性：</strong>浏览器扩展可以操控网页的内容；例如，让用户在每个页面上添加他们最喜欢的徽标或者图片。扩展也可以让用户更新火狐浏览器的界面，就像独立的<a href="https://developer.mozilla.org/en-US/Add-ons/Themes/Theme_concepts">主题扩展</a>一样。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15809/MyWeb_New_Tab_add_on.png" style="height: 398px; width: 540px;"></p> + +<p>示例: <a href="https://addons.mozilla.org/zh-CN/firefox/addon/myweb-new-tab/">MyWeb New Tab</a>, <a href="https://addons.mozilla.org/zh-CN/firefox/addon/tabliss/">Tabliss</a>, 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/vivaldifox/">VivaldiFox</a></p> + +<p><strong>从网页中添加或删除内容：</strong>你可能想要帮助用户从网页中阻止一些侵扰的广告，当网页中提到一个国家或者城市时提供旅游指南，或者重组页面内容来提供一个统一的阅读体验。有了可以访问和更新一个页面里的 HTML 和 CSS的能力，扩展可以帮助用户以他们想要的形式来查看网页。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15807/ublock_origin_add_on.png" style="height: 480px; width: 640px;"></p> + +<p>示例: <a href="https://addons.mozilla.org/zh-CN/firefox/addon/ublock-origin/">uBlock Origin</a>, <a href="https://addons.mozilla.org/zh-CN/firefox/addon/reader/">Reader</a>, 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/toolbox-google-play-store/">Toolbox for Google Play Store™</a></p> + +<p><strong>添加工具和新的浏览特性：</strong>给任务面板添加新特性，或者从URL地址，超链接，或者页面文字生成二维码。有了灵活的界面选择和 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions">WebExtensions APIs</a> 你可以轻松的添加新的特性到浏览器。并且，你可以提升几乎任何网站的特性或者功能，不必是你自己的网站。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15806/QR_Code_Image_Generator_add_on.png"></p> + +<p>示例： <a href="https://addons.mozilla.org/zh-CN/firefox/addon/swimlanes-for-trello/">Swimlanes for Trello</a> 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/tomato-clock/">Tomato Clock</a></p> + +<p><strong>游戏：</strong>通过线下游戏的特性，或者探索新游戏的可能性来提供传统计算机游戏功能；例如，把游戏合并入每天网页浏览中。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15805/Asteroids_in_Popup_add_on%20.png" style="height: 438px; width: 700px;"></p> + +<p>示例：<a href="https://addons.mozilla.org/zh-CN/firefox/addon/solitaire-card-game-new-tab/">Solitaire Card Game New Tab</a>, 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/2048-prime/">2048 Prime</a>.</p> + +<p><strong>添加开发工具：</strong>你可以提供网站开发工具给你的公司或者开发一个有用的技术或者你想分享的网站开发技术。无论哪种方式，你可以通过对开发者工具栏添加一个新的标齐那也来提升内置的 Firefox 开发者工具。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15804/aXe_Developer_Tools_add_on.png" style="height: 261px; width: 700px;"></p> + +<p>示例: <a href="https://addons.mozilla.org/zh-CN/firefox/addon/web-developer/">Web Developer</a>, <a href="https://addons.mozilla.org/zh-CN/firefox/addon/react-devtools/">Web React Developer Tools</a>, 和 <a href="https://addons.mozilla.org/zh-CN/firefox/addon/axe-devtools/">aXe Developer Tools</a></p> + +<p>Firefox 扩展使用 WebExtensions API，一种跨浏览器的扩展开发系统，构建而成。 在很大程度上，它与 Google Chrome 和 Opera 所支持的<a class="external-icon external" href="https://developer.chrome.com/extensions">扩展 API</a> 兼容。 在大多数情况下，为这些浏览器所写的扩展只需<a href="/zh-CN/Add-ons/WebExtensions/Porting_from_Google_Chrome">少量修改</a>便可在 FireFox 和 Microsoft Edge 上运行。这些 API 也完全兼容<a href="/zh-CN/Firefox/Multiprocess_Firefox">多线程 Firefox</a>。</p> + +<p>如果你有想法或问题，或者在使用 WebExtensions API 迁移旧式附加组件时需要帮助，您可以在 <a class="external-icon external" href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons 邮件列表</a>或者<a class="external-icon external" href="https://wiki.mozilla.org/Matrix">Matrix</a> 上的 <a href="https://chat.mozilla.org/#/room/#addons:mozilla.org">Add-ons room</a> 与我们联系。</p> + +<h2 id="接下来呢？">接下来呢？</h2> + +<ul> + <li>在<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">你的第一个扩展</a>中开始开发一个简单的扩展。</li> + <li>在<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">解析一个扩展</a>中了解扩展的结构。</li> + <li>在<a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Examples">扩展示例</a>中尝试一些示例扩展。</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/what_next_/index.html b/files/zh-cn/mozilla/add-ons/webextensions/what_next_/index.html new file mode 100644 index 0000000000..91694acf8d --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/what_next_/index.html @@ -0,0 +1,58 @@ +--- +title: What next? +slug: Mozilla/Add-ons/WebExtensions/What_next_ +translation_of: Mozilla/Add-ons/WebExtensions/What_next_ +--- +<div>{{AddonSidebar}}</div> + +<p>You will now be ready to start turning your idea for a browser extension into reality. Before you start that journey, it's worth being aware of a few things that will help to make it a smooth one.</p> + +<h2 id="你的开发环境">你的开发环境</h2> + +<p>你不需要任何特殊的开发或构建环境工具来创建浏览器扩展：只需要一个简单的文本编辑器就可以创建出很好的浏览器扩展。当然，你可能一直在做web开发有一套你想去配置的开发工具和环境。如果是这样，你需要意识到一些事情。</p> + +<p>如果你使用了打包压缩工具来交付你最终的代码，你需要提交你的源码到<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next_$translate?tolocale=zh-CN#The_review_process"> AMO </a>审查。此外，用于压缩、混淆、构建的工具需要是开源的(或提供无限的免费使用), 并且可以在审阅者的计算机（Windows、Mac或Linux）上运行。主要是，我们的审阅者无法使用商业或基于Web的工具。</p> + +<p> </p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission#About_build_tools">学习更多关于构建工具</a></p> + +<h2 id="Third-party_libraries">Third-party libraries</h2> + +<p>Third-party libraries are a great way to add complex features or functionality to your browser extensions quickly. When you submit an extension to the <a href="#The_review_processv">AMO review process</a>, the process will also consider any third-party libraries used. To streamline the review, make sure you always download third-party libraries from their official website or repository, and if the library is minified provide a link to the source code. Please note that third-party libraries cannot be modified in any way.</p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission">Learn more about submitting source code</a></p> + +<h2 id="The_Firefox_Add-on_Distribution_Agreement">The Firefox Add-on Distribution Agreement</h2> + +<p>Browser extensions need to be signed to install into the release or beta versions of Firefox. Signing takes place in addons.mozilla.org (AMO) and is subject to the terms and conditions of the Firefox Add-on Distribution Agreement. The goal of the agreement is to ensure Firefox users get access to well supported, quality add-ons that enhance the Firefox experience.</p> + +<p><a href="/Add-ons/AMO/Policy/Agreement">Read the agreement</a></p> + +<p><a href="/en-US/Add-ons/WebExtensions/Distribution">Learn more about signing</a></p> + +<h2 id="The_review_process">The review process</h2> + +<p>When a browser extension is submitted for signing, it's subject to automated review. It may also be subject to a manual review, when the automated review determines that a manual review is needed. Your browser extension won't be signed until it’s passed the automated review and may have its signing revoked if it fails to pass the manual review. The review process follows a strict set of guidelines, so it’s easy to check and avoid any likely review problems.</p> + +<p><a href="/en-US/Add-ons/AMO/Policy/Reviews">Check out the review policy and guidelines</a></p> + +<h2 id="AMO_featured_browser_extensions">AMO featured browser extensions</h2> + +<p>If you choose to list your browser extension on AMO, your extension could be featured on the AMO website, in the Firefox browser’s add-on manager, or elsewhere on a Mozilla website. We've compiled a list of guidelines about how extensions are selected for featuring, by following these guidelines you give your extension the best chance of being featured.</p> + +<p><a href="/en-US/Add-ons/AMO/Policy/Featured">Learn more about getting your add-ons featured</a></p> + +<h2 id="Continue_your_learning_experience">Continue your learning experience</h2> + +<p>Now you know what lies ahead, it's time to dive into more details about browser extension development. In the sections that follow, you’ll discover:</p> + +<ul> + <li>More about the fundamental concepts behind browser extensions, starting with details on how to <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Using_the_JavaScript_APIs">use the JavaScript APIs</a>.</li> + <li>A guide to the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface">user interface components</a> available to your browser extensions.</li> + <li>A collection of how-to guides on achieving key tasks in your extensions or making use of the JavaScript APIs.</li> + <li>Information on how to port other browser extensions to Firefox.</li> + <li>Details about the Firefox specific workflows you can use to develop browser extensions.</li> + <li>A full reference guide to the JavaScript APIs.</li> + <li>A full reference guide to the Manifest keys.</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.html b/files/zh-cn/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.html new file mode 100644 index 0000000000..e1b5878010 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.html @@ -0,0 +1,634 @@ +--- +title: Working with the Tabs API +slug: Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API +tags: + - 选项卡 + - 附加组件 +translation_of: Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API +--- +<p>{{AddonSidebar}}</p> + +<p><span class="tlid-translation translation" lang="zh-CN"><span title="">选项卡允许用户在其浏览器窗口中打开多个网页，然后在这些网页之间切换。</span> <span title="">使用Tabs API，您可以使用和操作这些选项卡来创建实用程序，为用户提供使用选项卡或提供扩展功能的新方法。</span></span></p> + +<p>在这篇how-to文章中我们将看到：</p> + +<ul> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">使用Tabs API所需的权限。</span></span></li> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">使用{{WebExtAPIRef("tabs.query")}}发现有关标签及其属性的更多信息。</span></span></li> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">创建、复制、移动、更新、重新加载和删除选项卡。</span></span></li> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">操纵标签的缩放大小。</span></span></li> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">操纵选项卡的CSS。</span></span></li> +</ul> + +<p><span class="tlid-translation translation" lang="zh-CN"><span title="">最后，我们通过查看API提供的其他一些其他功能。</span></span></p> + +<div class="blockIndicator note"> +<p><span class="tlid-translation translation" lang="zh-CN"><span title="">注意：其他地方有一些Tab API功能。</span> <span title="">这些是可用于使用脚本操作选项卡内容的方法{{WebExtAPIRef("tabs.connect")}}，{{WebExtAPIRef("tabs.sendMessage")}}和{{WebExtAPIRef("tabs.executeScript")}}</span>。<span title="">如果您需要有关这些方法的更多信息，请参阅概念文章<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">内容脚本</a>和操作指南<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page">修改网页</a>。</span></span></p> +</div> + +<h2 id="权限和选项卡API"><span class="tlid-translation translation" lang="zh-CN"><span title="">权限和选项卡API</span></span></h2> + +<p><span class="tlid-translation translation" lang="zh-CN"><span title="">对于大多数Tabs API函数，您不需要任何权限;</span> <span title="">但是，有一些例外：</span></span></p> + +<ul> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">需要</span></span><code>"tabs"</code><span class="tlid-translation translation" lang="zh-CN"><span title="">权限才能访问Tab对象的<code>Tab.url</code>，<code>Tab.title</code>和<code>Tab.favIconUrl</code>属性。</span> <span title="">在Firefox中，您还需要</span></span><code>"tabs"</code><span class="tlid-translation translation" lang="zh-CN"><span title="">来按URL执行<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">查询</a>。</span></span></li> + <li>{{WebExtAPIRef("tabs.executeScript")}}或{{WebExtAPIRef("tabs.insertCSS")}}需要<a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">主机权限</a>。</li> +</ul> + +<p>以下是您可以在扩展程序的manifest.json文件中请求<code>"tabs"</code>权限的方法：</p> + +<pre class="brush: json">"permissions": [ + "<all_urls>", + "tabs" +], +</pre> + +<p>此请求允许您在用户访问的所有网站上使用所有标签API功能。 还有一种替代方法可以请求权限使用{{WebExtAPIRef("tabs.executeScript")}}或{{WebExtAPIRef("tabs.insertCSS")}}，其中您不需要主机权限，形式为<a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>"activeTab"</code></a>。 此权限与<code><all_urls></code>提供与<code>"tabs"</code>相同的权限，但有两个限制：</p> + +<ul> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">用户必须通过其浏览器或页面操作，上下文菜单或快捷键与扩展进行交互。</span></span></li> + <li><span class="tlid-translation translation" lang="zh-CN"><span title="">它仅在活动选项卡中授予权限。</span></span></li> +</ul> + +<p><span class="tlid-translation translation" lang="zh-CN"><span title="">这种方法的好处是用户不会收到权限警告，也就是说您的扩展程序可以“访问所有网站的数据”。</span> <span title="">这是因为</span></span><code><all_urls></code><span class="tlid-translation translation" lang="zh-CN"><span title="">权限使扩展能够在任何选项卡中随时执行脚本，而</span></span><a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>"activeTab"</code></a><span class="tlid-translation translation" lang="zh-CN"><span title="">仅限于允许扩展在当前选项卡中执行用户请求的操作。</span></span></p> + +<h2 id="Discovering_more_about_tabs_and_their_properties">Discovering more about tabs and their properties</h2> + +<p>There will be occasions when you want to get a list of all the tabs in all the browser windows. Other times you might want to find a subset of tabs that match some specific criteria, such as those opened from a specific tab or displaying pages from a particular domain. And once you have your list of tabs, you’ll probably want to know more about their properties.</p> + +<p>This is where {{WebExtAPIRef("tabs.query")}} comes in. Used alone to get all tabs or taking the <code>queryInfo</code> object—to specify query criteria such as whether the tab is active, in the current window, or one or more of 17 criteria—{{WebExtAPIRef("tabs.query")}} returns an array of {{WebExtAPIRef("tabs.Tab")}} objects containing information about the tabs.</p> + +<p>Where you want information about the current tab only, you can get a {{WebExtAPIRef("tabs.Tab")}} object for that tab using {{WebExtAPIRef("tabs.getCurrent")}}. If you have a tab’s ID, you can get its {{WebExtAPIRef("tabs.Tab")}} object using {{WebExtAPIRef("tabs.get")}}.</p> + +<div class="blockIndicator note"> +<p><strong>Note:</strong></p> + +<ul> + <li><strong>In Chrome,</strong> the user can select multiple tabs in a window, and the Tabs API sees these as highlighted tabs.</li> + <li><strong>In Firefox,</strong> the user can’t select multiple tabs, so “highlighted” and “active” are synonymous.</li> +</ul> +</div> + +<h3 id="How_to_example">How to example</h3> + +<p>To see how {{WebExtAPIRef("tabs.query")}} and {{WebExtAPIRef("tabs.Tab")}} are used, let’s walk through how the <a href="https://github.com/mdn/webextensions-examples/tree/master/tabs-tabs-tabs">tabs-tabs-tabs</a> example adds the list of “switch to tabs” to its toolbar button popup.</p> + +<p><img alt="The tabs tabs tabs toolbar menu showing the switch to tap area" src="https://mdn.mozillademos.org/files/15723/Switch_to_tab.png" style="height: 645px; width: 369px;"></p> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Here is the <a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/manifest.json">manifest.json</a>:</p> + +<pre class="brush: json">{ + "browser_action": { + "browser_style": true, + "default_title": "Tabs, tabs, tabs", + "default_popup": "tabs.html" + }, + "description": "A list of methods you can perform on a tab.", + "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/tabs-tabs-tabs", + "manifest_version": 2, + "name": "Tabs, tabs, tabs", + "permissions": [ + "tabs" + ], + "version": "1.0" +} +</pre> + +<div class="blockIndicator note"> +<p>Note the following:</p> + +<ul> + <li> + <p><strong>tabs.html is defined as the <code>default_popup</code> in <code>browser_action</code>.</strong> It is displayed whenever the user clicks the extension’s toolbar icon.</p> + </li> + <li> + <p><strong>Permissions includes tabs.</strong> This is needed to support the tab list feature, as the extension reads the title of the tabs for display in the popup.</p> + </li> +</ul> +</div> + +<h3 id="tabs.html">tabs.html</h3> + +<p>tabs.html defines the content of the extension’s popup:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="tabs.css"/> + </head> + +<body> + + <div class="panel"> + <div class="panel-section panel-section-header"> + <div class="text-section-header">Tabs-tabs-tabs</div> + </div> + + <a href="#" id="tabs-move-beginning">Move active tab to the beginning of the window</a><br> + + +… + +Define the other menu items +… + + <div class="switch-tabs"> + + <p>Switch to tab</p> + + <div id="tabs-list"></div> + + </div> + </div> + + <script src="tabs.js"></script> + +</body> + +</html> +</pre> + +<p>Here is a summary of the above does:</p> + +<ol> + <li>The menu items are declared. </li> + <li>An empty <code>div</code> with the ID <code>tabs-list</code> is declared to contain the list of tabs.</li> + <li>tabs.js is called.</li> +</ol> + +<h3 id="tabs.js">tabs.js</h3> + +<p>In <a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/tabs.js">tabs.js</a>, we’ll see how the list of tabs is built and added to the popup. </p> + +<h4 id="Creating_the_popup">Creating the popup</h4> + +<p>First, an event handler is added to execute <code>listTabs()</code> when tabs.html is loaded:</p> + +<pre class="brush: js">document.addEventListener("DOMContentLoaded", listTabs);</pre> + +<p>The first thing that <code>listTabs()</code> does is to call <code>getCurrentWindowTabs()</code>. This is where {{WebExtAPIRef("tabs.query")}} is used to get a {{WebExtAPIRef("tabs.Tab")}} object for the tabs in the current window:</p> + +<pre class="brush: js">function getCurrentWindowTabs() { + return browser.tabs.query({currentWindow: true}); +} +</pre> + +<p>Now, <code>listTabs()</code> is ready to create the content for the popup.</p> + +<p>To start with:</p> + +<ol> + <li>Grab the <code>tabs-list</code> <code>div</code>.</li> + <li>Create a document fragment (into which the list will be built).</li> + <li>Set counters.</li> + <li>Clear the content of the <code>tabs-list</code> <code>div</code>.</li> +</ol> + +<pre class="brush: js">function listTabs() { + getCurrentWindowTabs().then((tabs) => { + let tabsList = document.getElementById('tabs-list'); + let currentTabs = document.createDocumentFragment(); + let limit = 5; + let counter = 0; + + tabsList.textContent = ''; +</pre> + +<p>Next, we’ll create the links for each tab:</p> + +<ol> + <li>Loops through the first 5 items from the {{WebExtAPIRef("tabs.Tab")}} object.</li> + <li>For each item, add a hyperlink to the document fragment. + <ul> + <li>The link’s label—that is, its text—is set using the tab’s title (or the ID, if it has no title).</li> + <li>The link’s address is set using the tab’s ID.</li> + </ul> + </li> +</ol> + +<pre class="brush: js"> for (let tab of tabs) { + if (!tab.active && counter <= limit) { + let tabLink = document.createElement('a'); + + tabLink.textContent = tab.title || tab.id; + + tabLink.setAttribute('href', tab.id); + tabLink.classList.add('switch-tabs'); + currentTabs.appendChild(tabLink); + } + + counter += 1; + + } +</pre> + +<p>Finally, the document fragment is written to the <code>tabs-list</code> div:</p> + +<pre class="brush: js"> tabsList.appendChild(currentTabs); + }); +} +</pre> + +<h4 id="Working_with_the_active_tab">Working with the active tab</h4> + +<p>Another related example feature is the “Alert active tab” info option that dumps all the {{WebExtAPIRef("tabs.Tab")}} object properties for the active tab into an alert:</p> + +<pre class="brush: js"> else if (e.target.id === "tabs-alertinfo") { + callOnActiveTab((tab) => { + let props = ""; + for (let item in tab) { + props += `${ item } = ${ tab[item] } \n`; + } + alert(props); + }); + } +</pre> + +<p>Where <code>callOnActiveTab()</code> finds the active tab object by looping through the {{WebExtAPIRef("tabs.Tab")}} objects looking for the item with active set:</p> + +<pre class="brush: js">document.addEventListener("click", function(e) { + function callOnActiveTab(callback) { + getCurrentWindowTabs().then((tabs) => { + for (var tab of tabs) { + if (tab.active) { + callback(tab, tabs); + } + } + }); + } +} + +</pre> + +<h2 id="Creating_duplicating_moving_updating_reloading_and_removing_tabs">Creating, duplicating, moving, updating, reloading, and removing tabs</h2> + +<p>Having gathered information about the tabs you’ll most likely want to do something with them—either to offer users features for manipulating and managing tabs or to implement functionality in your extension.</p> + +<p>The following functions are available:</p> + +<ul> + <li>create a new tab ({{WebExtAPIRef("tabs.create")}}).</li> + <li>duplicate a tab ({{WebExtAPIRef("tabs.duplicate")}}).</li> + <li>remove a tab ({{WebExtAPIRef("tabs.remove")}}).</li> + <li>move a tab ({{WebExtAPIRef("tabs.move")}}).</li> + <li>update the tab’s URL—effectively browse to a new page—({{WebExtAPIRef("tabs.update")}}).</li> + <li>reload the tab’s page ({{WebExtAPIRef("tabs.reload")}}).</li> +</ul> + +<div class="blockIndicator note"> +<p><strong>NOTE: </strong></p> + +<p>These functions all require the ID (or IDs) of the tab they are manipulating:</p> + +<ul> + <li>{{WebExtAPIRef("tabs.duplicate")}}</li> + <li>{{WebExtAPIRef("tabs.remove")}}</li> + <li>{{WebExtAPIRef("tabs.move")}}</li> +</ul> + +<p>Whereas the following functions will act on the active tab (if no tab ID is provided): </p> + +<ul> + <li>{{WebExtAPIRef("tabs.update")}}</li> + <li>{{WebExtAPIRef("tabs.reload")}}</li> +</ul> +</div> + +<h3 id="How_to_example_2">How to example</h3> + +<p>The <a href="https://github.com/mdn/webextensions-examples/tree/master/tabs-tabs-tabs">tabs-tabs-tabs</a> example exercises all of these features except for updating a tab’s URL The way in which these APIs are used is similar, so we’ll look at one of the more involved implementations, that of the “Move active tab to the beginning of the window list” option.</p> + +<p>But first, here is a demonstration of the feature in action:</p> + +<p>{{EmbedYouTube("-lJRzTIvhxo")}}</p> + +<h4 id="manifest.json_2"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/manifest.json">manifest.json</a></h4> + +<p>None of the functions require a permission to operate, so there are no features in the manifest.json file that need to be highlighted.</p> + +<h4 id="tabs.html_2"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/tabs.html">tabs.html</a></h4> + +<p>tabs.html defines the “menu” displayed in the popup, which includes the “Move active tab to the beginning of the window list” option, with a series of <code><a></code> tags grouped by a visual separator. Each menu item is given an ID, which is used in tabs.js to determine which menu item is being requested.</p> + +<pre class="brush: html"> <a href="#" id="tabs-move-beginning">Move active tab to the beginning of the window</a><br> + <a href="#" id="tabs-move-end">Move active tab to the end of the window</a><br> + + <div class="panel-section-separator"></div> + + + <a href="#" id="tabs-duplicate">Duplicate active tab</a><br> + + <a href="#" id="tabs-reload">Reload active tab</a><br> + <a href="#" id="tabs-alertinfo">Alert active tab info</a><br></pre> + +<h4 id="tabs.js_2"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/tabs.js">tabs.js</a></h4> + +<p>To implement the “menu” defined in tabs.html, tabs.js includes a listener for clicks in tabs.html:</p> + +<pre class="brush: js">document.addEventListener("click", function(e) { + function callOnActiveTab(callback) { + + getCurrentWindowTabs().then((tabs) => { + for (var tab of tabs) { + if (tab.active) { + callback(tab, tabs); + } + } + }); +} +} +</pre> + +<p>A series of <code>if</code> statements then look to match the ID of the item clicked.</p> + +<p>This code snippet is for the “Move active tab to the beginning of the window list” option:</p> + +<pre class="brush: js"> if (e.target.id === "tabs-move-beginning") { + callOnActiveTab((tab, tabs) => { + var index = 0; + if (!tab.pinned) { + index = firstUnpinnedTab(tabs); + } + console.log(`moving ${tab.id} to ${index}`) + browser.tabs.move([tab.id], {index}); + }); + } +</pre> + +<p>It's worth noting the use of <code>console.log()</code>. This enables you to output information to the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Debugging">debugger</a> console, which can be useful when resolving issues found during development.</p> + +<p><img alt="Example of the console.log output, from the move tabs feature, in the debugging console" src="https://mdn.mozillademos.org/files/15722/console.png" style="height: 329px; width: 911px;"></p> + +<p>The move code first calls <code>callOnActiveTab()</code> which in turn calls <code>getCurrentWindowTabs()</code> to get a {{WebExtAPIRef("tabs.Tab")}} object containing the active window’s tabs. It then loops through the object to find and return the active tab object:</p> + +<pre class="brush: js"> function callOnActiveTab(callback) { + getCurrentWindowTabs().then((tabs) => { + for (var tab of tabs) { + if (tab.active) { + callback(tab, tabs); + } + } + }); + } +</pre> + +<h5 id="Pinned_tabs">Pinned tabs</h5> + +<p>A feature of tabs is that the user can <dfn>pin</dfn> tabs in a window. Pinned tabs are placed at the start of the tab list and cannot be moved. This means that the earliest position a tab can move to is the first position after any pinned tabs. So, <code>firstUnpinnedTab()</code> is called to find the position of the first unpinned tab by looping through the <code>tabs</code> object:</p> + +<pre class="brush: js">function firstUnpinnedTab(tabs) { + for (var tab of tabs) { + if (!tab.pinned) { + return tab.index; + } + } +} +</pre> + +<p>We now have everything needed to move the tab: the active tab object from which we can get the tab ID and the position the tab is to be moved to. So, we can implement the move:</p> + +<pre class="brush: js"> browser.tabs.move([tab.id], {index});</pre> + +<p>The remaining functions to duplicate, reload, create, and remove tabs are implemented similarly.</p> + +<h2 id="Manipulating_a_tab’s_zoom_level">Manipulating a tab’s zoom level</h2> + +<p>The next set of functions enable you to get ({{WebExtAPIRef("tabs.getZoom")}}) and set ({{WebExtAPIRef("tabs.setZoom")}}) the zoom level within a tab. You can also retrieve the zoom settings ({{WebExtAPIRef("tabs.getZoomSettings")}}) but, at the time of writing, the ability to set the settings ({{WebExtAPIRef("tabs.setZoomSettings")}}) wasn’t available in Firefox.</p> + +<p>The level of zoom can be between 30% and 300% (represented as decimals <code>0.3</code> to <code>3</code>).</p> + +<p>In Firefox the default zoom settings are:</p> + +<ul> + <li><strong>default zoom level: </strong>100%.</li> + <li><strong>zoom mode:</strong> automatic (so the browser manages how zoom levels are set).</li> + <li><strong>scope of zoom changes:</strong> <code>"per-origin"</code>, meaning that when you visit a site again, it takes the zoom level set in your last visit.</li> +</ul> + +<h3 id="How_to_example_3">How to example</h3> + +<p>The <a href="https://github.com/mdn/webextensions-examples/tree/master/tabs-tabs-tabs">tabs-tabs-tabs</a> example includes three demonstrations of the zoom feature: zoom in, zoom out, and reset zoom. Here is the feature in action:</p> + +<p>{{EmbedYouTube("RFr3oYBCg28")}}</p> + +<p>Let’s take a look at how the zoom in is implemented.</p> + +<h4 id="manifest.json_3"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/manifest.json">manifest.json</a></h4> + +<p>None of the zoom functions require permissions, so there are no features in the manifest.json file that need to be highlighted.</p> + +<h4 id="tabs.html_3"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/tabs.html">tabs.html</a></h4> + +<p>We have already discussed how the tabs.html defines the options for this extension, nothing new or unique is done to provide the zoom options.</p> + +<h4 id="tabs.js_3"><a href="https://github.com/mdn/webextensions-examples/blob/master/tabs-tabs-tabs/tabs.js">tabs.js</a></h4> + +<p>tabs.js starts by defining several constants used in the zoom code:</p> + +<pre class="brush: js">const ZOOM_INCREMENT = 0.2; +const MAX_ZOOM = 3; +const MIN_ZOOM = 0.3; +const DEFAULT_ZOOM = 1; +</pre> + +<p>It then uses the same listener we discussed earlier so it can act on clicks in tabs.html.</p> + +<p>For the zoom in feature, this runs:</p> + +<pre class="brush: js"> else if (e.target.id === "tabs-add-zoom") { + callOnActiveTab((tab) => { + var gettingZoom = browser.tabs.getZoom(tab.id); + gettingZoom.then((zoomFactor) => { + //the maximum zoomFactor is 3, it can't go higher + if (zoomFactor >= MAX_ZOOM) { + alert("Tab zoom factor is already at max!"); + } else { + var newZoomFactor = zoomFactor + ZOOM_INCREMENT; + //if the newZoomFactor is set to higher than the max accepted + //it won't change, and will never alert that it's at maximum + newZoomFactor = newZoomFactor > MAX_ZOOM ? MAX_ZOOM : newZoomFactor; + browser.tabs.setZoom(tab.id, newZoomFactor); + } + }); + }); + } +</pre> + +<p>This code uses <code>callOnActiveTab()</code> to get the details of the active tab, then {{WebExtAPIRef("tabs.getZoom")}} gets the tab’s current zoom factor. The current zoom is compared to the defined maximum (<code>MAX_ZOOM</code>) and an alert issued if the tab is already at the maximum zoom. Otherwise, the zoom level is incremented but limited to the maximum zoom, then the zoom is set with {{WebExtAPIRef("tabs.getZoom")}}.</p> + +<h2 id="Manipulating_a_tab’s_CSS">Manipulating a tab’s CSS</h2> + +<p>Another significant capability offered by the Tabs API is the ability to manipulate the CSS within a tab—add new CSS to a tab ({{WebExtAPIRef("tabs.insertCSS")}}) or remove CSS from a tab ({{WebExtAPIRef("tabs.removeCSS")}}).</p> + +<p>This can be useful, for example, if you want to highlight certain page elements or change the default layout of the page.</p> + +<h3 id="How_to_example_4">How to example</h3> + +<p>The <a href="https://github.com/mdn/webextensions-examples/tree/master/apply-css">apply-css</a> example uses these features to add a red border to the web page in the active tab. Here is the feature in action:</p> + +<p>{{EmbedYouTube("bcK-GT2Dyhs")}}</p> + +<p>Let’s walk through how it’s set up.</p> + +<h4 id="manifest.json_4"><a href="https://github.com/mdn/webextensions-examples/blob/master/apply-css/manifest.json">manifest.json</a></h4> + +<p>To use the CSS features you need either:</p> + +<ul> + <li><code>"tabs"</code> permission and <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission</a> or</li> + <li><code>"activeTab"</code> permission.</li> +</ul> + +<p>The latter is the most useful, as it allows an extension to use {{WebExtAPIRef("tabs.insertCSS")}} and {{WebExtAPIRef("tabs.removeCSS")}} in the active tab when run from the extension’s browser or page action, context menu, or a shortcut.</p> + +<pre class="brush: json">{ + "description": "Adds a page action to toggle applying CSS to pages.", + + "manifest_version": 2, + "name": "apply-css", + "version": "1.0", + "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/apply-css", + + "background": { + + "scripts": ["background.js"] + }, + + "page_action": { + + "default_icon": "icons/off.svg", + "browser_style": true + }, + + "permissions": [ + "activeTab", + "tabs" + ] + +} +</pre> + +<p>You will note that <code>"tabs"</code> permission is requested in addition to <code>"activeTab"</code>. This additional permission is needed to enable the extension’s script to access the tab’s URL, the importance of which we’ll see in a moment.</p> + +<p>The other main features in the manifest.json file are the definition of:</p> + +<ul> + <li><strong>a background script</strong>, which starts running as soon as the extension is loaded.</li> + <li><strong>a “page action”</strong>, which defines an icon to be added to the browser’s address bar.</li> +</ul> + +<h4 id="background.js"><a href="https://github.com/mdn/webextensions-examples/blob/master/apply-css/background.js">background.js</a></h4> + +<p>On startup, background.js sets some constants to define the CSS to be applied, titles for the “page action”, and a list of protocols the extension will work in:</p> + +<pre class="brush: js">const CSS = "body { border: 20px solid red; }"; +const TITLE_APPLY = "Apply CSS"; +const TITLE_REMOVE = "Remove CSS"; +const APPLICABLE_PROTOCOLS = ["http:", "https:"]; +</pre> + +<p>When first loaded, the extension uses {{WebExtAPIRef("tabs.query")}} to get a list of all the tabs in the current browser window. It then loops through the tabs calling <code>initializePageAction()</code>.</p> + +<pre class="brush: js">var gettingAllTabs = browser.tabs.query({}); + +gettingAllTabs.then((tabs) => { + for (let tab of tabs) { + initializePageAction(tab); + } +}); +</pre> + +<p><code>initializePageAction</code> uses <code>protocolIsApplicable()</code> to determine whether the active tab’s URL is one the CSS can be applied to:</p> + +<pre class="brush: js">function protocolIsApplicable(url) { + var anchor = document.createElement('a'); + anchor.href = url; + return APPLICABLE_PROTOCOLS.includes(anchor.protocol); +} +</pre> + +<p>Then, if the example can act on the tab, <code>initializePageAction()</code> sets the tab’s <code>pageAction</code> (navigation bar) icon and title to use the “off” versions before making the <code>pageAction</code> visible:</p> + +<pre class="brush: js">function initializePageAction(tab) { + + if (protocolIsApplicable(tab.url)) { + browser.pageAction.setIcon({tabId: tab.id, path: "icons/off.svg"}); + browser.pageAction.setTitle({tabId: tab.id, title: TITLE_APPLY}); + browser.pageAction.show(tab.id); + } +} +</pre> + +<p>Next, a listener on <code>pageAction.onClicked</code> waits for the <code>pageAction</code> icon to be clicked, and calls <code>toggleCSS</code> when it is.</p> + +<pre class="brush: js">browser.pageAction.onClicked.addListener(toggleCSS);</pre> + +<p><code>toggleCSS()</code> gets the title of the <code>pageAction</code> and then takes the action described:</p> + +<ul> + <li><strong>For "Apply CSS”:</strong> + + <ul> + <li>toggles the <code>pageAction</code> icon and title to the “remove” versions.</li> + <li>applies the CSS using {{WebExtAPIRef("tabs.insertCSS")}}.</li> + </ul> + </li> + <li><strong>For “Remove CSS”:</strong> + <ul> + <li>toggles the <code>pageAction</code> icon and title to the “apply” versions.</li> + <li>removes the CSS using {{WebExtAPIRef("tabs.removeCSS")}}.</li> + </ul> + </li> +</ul> + +<pre class="brush: js">function toggleCSS(tab) { + + + function gotTitle(title) { + + if (title === TITLE_APPLY) { + browser.pageAction.setIcon({tabId: tab.id, path: "icons/on.svg"}); + browser.pageAction.setTitle({tabId: tab.id, title: TITLE_REMOVE}); + browser.tabs.insertCSS({code: CSS}); + } else { + browser.pageAction.setIcon({tabId: tab.id, path: "icons/off.svg"}); + browser.pageAction.setTitle({tabId: tab.id, title: TITLE_APPLY}); + browser.tabs.removeCSS({code: CSS}); + } + } + + var gettingTitle = browser.pageAction.getTitle({tabId: tab.id}); + + gettingTitle.then(gotTitle); +} +</pre> + +<p>Finally, to ensure that the <code>pageAction</code> is valid after each update to the tab, a listener on {{WebExtAPIRef("tabs.onUpdated")}} calls <code>initializePageAction()</code> each time the tab is updated to check that the tab is still using a protocol to which the CSS can be applied.</p> + +<pre class="brush: js">browser.tabs.onUpdated.addListener((id, changeInfo, tab) => { + initializePageAction(tab); +}); +</pre> + +<h2 id="Some_other_interesting_abilities">Some other interesting abilities</h2> + +<p>There are a couple of other Tabs API features that don’t fit into one of the earlier sections:</p> + +<ul> + <li>Capture the visible tab content with {{WebExtAPIRef("tabs.captureVisibleTab")}}.</li> + <li>Detect the primary language of the content in a tab using {{WebExtAPIRef("tabs.detectLanguage")}}. This could be used, for example, to match the language in your extension’s UI with that of the page it’s running in.</li> +</ul> + +<h2 id="Learn_more">Learn more</h2> + +<p>If you want to learn more about the Tabs API, check out:</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/API/tabs">Tabs API reference</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Examples">Example extensions</a> (many of which use the Tabs API)</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/your_first_webextension/index.html b/files/zh-cn/mozilla/add-ons/webextensions/your_first_webextension/index.html new file mode 100644 index 0000000000..b08f114ba1 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/your_first_webextension/index.html @@ -0,0 +1,238 @@ +--- +title: 你的第一个拓展 +slug: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +tags: + - WebExtentions + - 指南 +translation_of: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>在这篇文章中，我们将为 Firefox 创建一个扩展。这个扩展只是给从 "firefox.org" 或其任意子域名加载的任何页面添加一个红色边框。</p> + +<p>该示例的源代码位于 GitHub：<a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">https://github.com/mdn/webextensions-examples/tree/master/borderify</a></p> + +<p>首先，你需要 Firefox 45 或更高版本。</p> + +<h2 id="编写扩展">编写扩展</h2> + +<p>创建一个新的目录并切换到该目录。例如，在你的命令行/终端，你可以这么做：</p> + +<pre class="brush: bash">mkdir borderify +cd borderify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>现在，在 "borderify" 目录内直接创建文件 "manifest.json"。文件内容如下：</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="punctuation token">{</span> + + <span class="key token">"manifest_version":</span> <span class="number token">2</span><span class="punctuation token">,</span> + <span class="key token">"name":</span> <span class="string token">"Borderify"</span><span class="punctuation token">,</span> + <span class="key token">"version":</span> <span class="string token">"1.0"</span><span class="punctuation token">,</span> + + <span class="key token">"description":</span> <span class="string token">"Adds a red border to all webpages matching mozilla.org."</span><span class="punctuation token">,</span> + + <span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/border-48.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + + <span class="key token">"content_scripts":</span> <span class="punctuation token">[</span> + <span class="punctuation token">{</span> + <span class="key token">"matches":</span> <span class="punctuation token">[</span><span class="string token">"*://*.mozilla.org/*"</span><span class="punctuation token">]</span><span class="punctuation token">,</span> + <span class="key token">"js":</span> <span class="punctuation token">[</span><span class="string token">"borderify.js"</span><span class="punctuation token">]</span> + <span class="punctuation token">}</span> + <span class="punctuation token">]</span> + +<span class="punctuation token">}</span></code></pre> + +<ul> + <li>前三个键：<code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>、<code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/name">name</a></code> 和 <code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/version">version</a></code> 是强制的，包含有扩展的基本元数据.</li> + <li><code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/description">description</a></code> 是可选的，但建议使用「该描述将显示在附加组件管理器上」.</li> + <li><code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> 是可选的，但建议使用「它允许你给扩展指定一个图标，将显示在附加组件管理器上」.</li> +</ul> + +<p>这里最有意思的键是 <code><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code>，它告诉 Firefox 加载脚本到其 URL 匹配特定模式的网页。本例中，我们要求 Firefox 加载脚本 "borderify.js" 到任何来自 "mozilla.org" 或其子域的 HTTP 或 HTTPS 页面。</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Content_scripts">进一步了解内容脚本 content script</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Match_patterns">进一步了解模式匹配 pattern matching</a></li> +</ul> + +<div class="warning"> +<p><a href="/zh-CN/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_Add-on_ID">某些情况下，你需要给你的扩展指定一个 ID</a>。如果你需要指定一个附加组件 ID，请在 <code>manifest.json</code> 中添加 <code><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings">browser_specific_settings</a></code> 键，并设置其 <code>gecko.id</code> 属性：</p> + +<pre class="brush: json">"browser_specific_settings": { + "gecko": { + "id": "borderify@example.com" + } +}</pre> +</div> + +<h3 id="iconsborder-48.png">icons/border-48.png</h3> + +<p>扩展应该有一个图标。这将显示在附加组件管理器加载项的列表中。我们的 manifest.json 保证了会有一个图标 "icons/border-48.png"。</p> + +<p>在 "borderify" 目录下直接创建 "icons" 目录，并在 "icons" 目录下保存一个名为 "border-48.png"的图标. 你可以使用<a href="https://github.com/mdn/webextensions-examples/blob/master/borderify/icons/border-48.png">我们的示例</a>中的，来自谷歌材料设计中的图标，遵循 <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike</a> 协议。</p> + +<p>如果您选择使用自己的图标，它也应该是 48×48 像素。你也可以为高分辨率显示器提供一个 96x96 的像素图标，在 manifest.json 的 <code>icons</code> 对象中添加 <code>96</code> 属性即可：</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/border-48.png", + "96": "icons/border-96.png"</span> +<span class="punctuation token">}</span></code></pre> + +<p>或者，也可以在这里提供一个 SVG 文件，它会被正确地缩放。(不过：如果你正在使用 SVG 并且你的图标包含文字，有可能想要用你的 SVG 编辑器的“转换为路径”工具来拼和文字，这样图标会以一个恒定的大小/位置来缩放。）</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/manifest.json/icons">了解更多关于指定图标的内容</a></li> +</ul> + +<h3 id="borderify.js">borderify.js</h3> + +<p>最后，在 "borderify" 目录下直接创建 "borderify.js" 文件，并写入下面的内容:</p> + +<pre class="brush: js">document.body.style.border = "5px solid red";</pre> + +<p>manifest.json 文件中 <code>content_scripts</code> 的键给出了一条模式匹配，该脚本便会被加载到匹配的页面中。该脚本会像页面加载自己的脚本一样被加载，可以直接访问该文档。</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Content_scripts">了解更多关于内容脚本的内容。</a></li> +</ul> + +<h2 id="测试一下">测试一下</h2> + +<p>首先，仔细检查文件是否在正确的位置：</p> + +<pre>borderify/ + icons/ + border-48.png + borderify.js + manifest.json</pre> + +<h3 id="安装">安装</h3> + +<p>打开 Firefox 的 <a href="/zh-CN/docs/Tools/about:debugging">about:debugging</a> 页面，点击”This Firefox" (在新版本的Firefox里），点击 "临时加载附加组件（Load Temporary Add-on）" 按钮，并选择你的附加组件目录:</p> + +<p>{{EmbedYouTube("cer9EUKegG4")}}</p> + +<p>附加组件将会被安装，直到下次重启浏览器失效。</p> + +<p>或者，你可以通过 <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> 工具从命令行来运行扩展。</p> + +<h3 id="测试">测试</h3> + +<p>现在尝试访问"mozilla.org", 你将会在页面上看到有个红色的边框</p> + +<p>{{EmbedYouTube("rxBQl2Z9IBQ")}}</p> + +<div class="note"> +<p>不要在 addons.mozilla.org 上尝试！内容脚本（Content Script) 当前在那个域名下是被限制的。</p> +</div> + +<p>尝试一下编辑内容脚本更改边框的颜色，或做页面内容别的修改，保存内容脚本，然后通过单击 <strong>about:debugging</strong> 页面下的 “刷新” 按钮重新加载附加的文件。你可以马上看到的变化：</p> + +<p>{{EmbedYouTube("NuajE60jfGY")}}</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">学习更多关于加载附加组件</a></li> +</ul> + +<h2 id="打包和发布">打包和发布</h2> + +<p>为了给其他人使用你的插件，您需要打包，并将其提交给 Mozilla 进行签名。要了解更多有关，请参考 <a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension">"发布你的扩展"</a>。</p> + +<h2 id="下一步">下一步</h2> + +<p>现在，你已经在开发 Firefox 的一个 Web 扩展的过程中得到了一些想法，尝试：</p> + +<ul> + <li><a href="/zh-CN/Add-ons/WebExtensions/Your_second_WebExtension">写一个更加复杂的WebExtension</a></li> + <li><a href="/zh-CN/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">阅读更多关于WebExtensions的剖析</a></li> + <li><a href="https://wiki.developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/WebExtensions/Examples">探索更多关于扩展的示例</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/What_next_">发现开发，测试，和发布扩展需要的东西</a></li> + <li><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/What_next_#Continue_your_learning_experience">进一步的学习</a></li> +</ul> + +<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%; display: none; opacity: 1; left: 556px; top: 6804px;"></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 selected 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_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"></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/实现一个设置页面/index.html b/files/zh-cn/mozilla/add-ons/webextensions/实现一个设置页面/index.html new file mode 100644 index 0000000000..fe8ac2e0a7 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/实现一个设置页面/index.html @@ -0,0 +1,203 @@ +--- +title: 实现一个设置页面 +slug: Mozilla/Add-ons/WebExtensions/实现一个设置页面 +translation_of: Mozilla/Add-ons/WebExtensions/Implement_a_settings_page +--- +<div>{{AddonSidebar}}</div> + +<p>设置页面可以让用户查看，修改扩展的一些设置。</p> + +<p>对于WebExtensions，设置通常使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code> API 保存. 实现一个设置页面通常包含以下三步:</p> + +<ul> + <li>制作一个HTML 文件用以显示并修改设置</li> + <li>写一个包含于该HTML文件的脚本，其可以使设置页面存储与存储设备中并在用户修改后更新他。</li> + <li>在manifest.json文件 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code> 关键字中 设置HTML文件的路径。通过这种方式，该HTML将会被显示浏览器管理器里该插件名字和描述的旁边。</li> +</ul> + +<div class="note"> +<p>你也可以使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage">runtime.openOptionsPage()</a></code> 打开该页面。</p> +</div> + +<h2 id="简单的_WebExtension">简单的 WebExtension</h2> + +<p>首先，我们写一个向用户访问的所有页面添加一个蓝色边框的扩展。</p> + +<p>创建一个新的文件夹命名为“setting”，然后创建文件“manifest.json”它包含以下内容:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Settings example", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["<all_urls>"], + "js": ["borderify.js"] + } + ] + +}</pre> + +<p>该扩展指示浏览器在用户访问的网站上加载一个名为"borderify.js“的Content Script。</p> + +<p>接下来，在"setting"目录下创建"borderify.js"，然后给予他以下内容:</p> + +<pre class="brush: js">document.body.style.border = "10px solid blue";</pre> + +<p>这只是向网页加入了一一个蓝色边框</p> + +<p>现在 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">安装该扩展</a> 并测试它——打开任意一个网页:</p> + +<p>{{EmbedYouTube("E-WUhihF8fw")}}</p> + +<h2 id="添加设置页面">添加设置页面</h2> + +<p>现在让我们创建一个设置页面来允许用户设置边框的颜色。</p> + +<p>首先更新 "manifest.json" 使他拥有如下内容:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Settings example", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["<all_urls>"], + "js": ["borderify.js"] + } + ], + + "options_ui": { + "page": "options.html" + }, + + "permissions": ["storage"] + +} +</pre> + +<p>我们加入了两个manifest 关键字:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code>: 设置了一个HTML来作为设置页面。</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code>: 我们使用 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code> API 来保存设置, 所以我们需要请求权限来使用该API。</li> +</ul> + +<p>接下来，因为我们承诺提供"options.html"，让我们来创建他，在"setting"目录创建一个该文件并具有以下内容:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + </head> + + <body> + + <form> + <label>Border color<input type="text" id="color" ></label> + <button type="submit">Save</button> + </form> + + <script src="options.js"></script> + + </body> + +</html> +</pre> + +<p>这里定义了一个带有标记文字{{htmlelement("input")}}的 {{htmlelement("form")}} 和一个 提交 {{htmlelement("button")}}. 也包含了一个名为"options.js"的脚本。</p> + +<p>仍然在"settting"目录下创建 "options.js"，并给予他以下内容:</p> + +<pre class="brush: js">function saveOptions(e) { + e.preventDefault(); + browser.storage.local.set({ + color: document.querySelector("#color").value + }); +} + +function restoreOptions() { + + function setCurrentChoice(result) { + document.querySelector("#color").value = result.color || "blue"; + } + + function onError(error) { + console.log(`Error: ${error}`); + } + + var getting = browser.storage.local.get("color"); + getting.then(setCurrentChoice, onError); +} + +document.addEventListener("DOMContentLoaded", restoreOptions); +document.querySelector("form").addEventListener("submit", saveOptions); +</pre> + +<p>它做了两件事:</p> + +<ul> + <li>当网页被加载它使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get">storage.local.get()</a></code> 从存贮设备中获取了名为"color”的值.如果该值未被设置其为默认值blue。</li> + <li>当用户点击提交按钮，使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/set">storage.local.set()</a></code> 存贮颜色值。</li> +</ul> + +<p>最后，更新"borderify.js" 来读取边框颜色:</p> + +<div class="warning"> +<p>因为 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get">browser.storage.local.get()</a> 在火狐52版本之前的一个漏洞 ,以下代码没法起作用。为了使它生效，<code>onGot()中的 item.color 必须改为 item[0].color。</code></p> +</div> + +<pre class="brush: js"> function onError(error) { + console.log(`Error: ${error}`); +} + +function onGot(item) { + var color = "blue"; + if (item.color) { + color = item.color; + } + document.body.style.border = "10px solid " + color; +} + +var getting = browser.storage.local.get("color"); +getting.then(onGot, onError); +</pre> + +<p>最后，完整的扩展看起来是这样:</p> + +<pre>settings/ + borderify.js + manifest.json + options.html + options.js</pre> + +<p>现在:</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">重新载入扩展</a></li> + <li>加载一个网页</li> + <li>打开设置页面并修改边框颜色</li> + <li>重载网页查看变化。</li> +</ul> + +<p>在火狐中你可以通过访问"about:addons"点击扩展旁边的"Preferences"按钮访问设置页面。</p> + +<p>{{EmbedYouTube("ECt9cbWh1qs")}}</p> + +<h2 id="进一步了解">进一步了解</h2> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code> 关键字文档</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code> API 文档</li> + <li>使用<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage">runtime.openOptionsPage()</a></code> 直接打开你的设置页面</li> + <li>另一个设置页面例子: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a></li> + </ul> + </li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/构建一个跨浏览器的扩展插件/index.html b/files/zh-cn/mozilla/add-ons/webextensions/构建一个跨浏览器的扩展插件/index.html new file mode 100644 index 0000000000..6d1a21497c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/构建一个跨浏览器的扩展插件/index.html @@ -0,0 +1,275 @@ +--- +title: 构建一个跨浏览器的扩展程序 +slug: Mozilla/Add-ons/WebExtensions/构建一个跨浏览器的扩展插件 +tags: + - Web插件 + - 扩展 + - 指南 + - 插件 +translation_of: Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension +--- +<p>{{AddonSidebar()}}</p> + +<p>浏览器扩展 API 的引入为浏览器扩展的开发创造了 “一次开发跨浏览器” 的前景。然而，在使用扩展 API 的浏览器中(主要是 Chrome、 Firefox、 Opera 和 Edge) ，API 的实现和覆盖范围都存在差异。除此之外，Safari 使用了它自己的 Safari 扩展脚本系统。</p> + +<p>最大化兼容浏览器扩展意味着至少在两个不同的浏览器上兼容同一个扩展。本文探讨了在创建跨浏览器扩展时所面临的六个主要挑战，并在每种情况下提出了如何应对这些挑战。</p> + +<p>本文不讨论为 Safari 构建浏览器扩展。您可以通过 Safari 扩展共享一些资源，比如图片和 HTML 内容。然而，如果您要进行 JavaScript 部分的编程则需要作为一个单独的开发项目进行，除非您希望创建自己的 polyfill。</p> + +<h2 id="跨平台扩展的开发障碍">跨平台扩展的开发障碍</h2> + +<p>在开发跨平台扩展时，需要注意以下六个方面:</p> + +<ul> + <li>API 命名空间</li> + <li>API 异步事件处理</li> + <li>API 函数覆盖率</li> + <li>Manifest 的字段</li> + <li>打包扩展</li> + <li>发布扩展</li> +</ul> + +<h3 id="API_命名空间">API 命名空间</h3> + +<p>在四大主流浏览器中，有两个 API 命名空间正在使用:</p> + +<ul> + <li><code>browser.* </code>是 Firefox 和 Edge 使用的扩展 API 的标准</li> + <li><code>chrome.*</code> 是 Chrome 和 Opera 使用的扩展 API 的标准</li> +</ul> + +<p>Firefox 也支持 Chrome 浏览器的 <code>chrome.*</code> 名称空间，主要用于协助扩展移植。然而，首选应该使用浏览器 <code>browser.*</code> 命名空间。除了被提议的标准外， <code>browser.*</code> 使用 promises ーー一种现代化且简单的处理异步事件机制。</p> + +<p>只有在非常小的扩展中，命名空间才可能是唯一的跨平台问题。因此，如果你遇到了且试图专门解决这个问题的话，可能很少会有帮助。最好的方法是通过异步事件处理来解决这个问题。</p> + +<h3 id="API_异步事件处理">API 异步事件处理</h3> + +<p>在四个主要浏览器中，有两种方法可以处理异步事件:</p> + +<ul> + <li>promises 是 Firefox 使用的扩展 API 的标准</li> + <li>callbacks 是 Chrome、Edge 和 Opera 使用的扩展 API 的标准</li> +</ul> + +<p>Firefox 还支持 <code>chrome.*</code> 命名空间中的 callbacks 风格的 API，这主要是为了便于从 Chrome <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension">迁移</a>。然而，应该首选使用 promises（以及 <code>browser.*</code> 命名空间），它已被采纳为拟议标准的一部分。它极大地简化了异步事件处理，特别是在需要将事件链接在一起的情况下。</p> + +<div class="blockIndicator note"> +<p>如果你对这两种方法之间的差异不熟悉，可以看一下 <a href="https://medium.com/codebuddies/getting-to-know-asynchronous-javascript-callbacks-promises-and-async-await-17e0673281ee">了解异步 JavaScript: Callbacks、 Promises 和 Async/Await </a>或者 MDN 的 <a href="/en-US/docs/Web/JavaScript/Guide/Using_promises">Using promises</a> 页面。</p> +</div> + +<h4 id="浏览器扩展_API_的垫片（Polyfill）">浏览器扩展 API 的垫片（Polyfill）</h4> + +<p>那么，当 Firefox 是唯一支持它的浏览器时，你如何轻松地使用 promises 呢？解决方案是使用 promises 为 Firefox 编程，并使用<a href="https://github.com/mozilla/webextension-polyfill/">浏览器扩展 API 的垫片（Polyfill）</a>！<br> + <br> + 这个 polyfill 解决了跨 Firefox、 Chrome 和 Opera 的 API 名称空间和异步事件处理。在撰写本报告时(2018年11月) ，Edge 的支持正在开发中。<br> + <br> + 要使用 polyfill，可以使用 npm 安装到开发环境中，或者直接从 <a href="https://github.com/mozilla/webextension-polyfill/releases">GitHub Relase</a> 页面下载。</p> + +<p>然后，引入 <code>browser-polyfill.js</code> 到:</p> + +<ul> + <li><code>manifest.json</code>，修改后使它可以用于 background 和 content 脚本</li> + <li>HTML 文件，例如 <code>browserAction</code> 弹出窗口或标签页</li> + <li>使用 <code>tabs.executeScript</code> 上的 <code>executeScript</code> 动态注入脚本（不需要事先在 manifest.json 的 <code>content_scripts</code> 中申明</li> +</ul> + +<p>例如，这个 <code>manifest.json</code> 代码让你的后台脚本可以使用 polyfill:</p> + +<pre class="brush: json notranslate">{ + // ... + "background": { + "scripts": [ + "browser-polyfill.js", + "background.js" + ] + } +}</pre> + +<p>您的目标是确保在任何其他扩展脚本执行 <code>browser.*</code> API 前执行 polyfill。</p> + +<div class="blockIndicator note"> +<p>关于如何使用模块打包器使用 polyfill 的更多细节和信息，请参阅 <a href="https://github.com/mozilla/webextension-polyfill/blob/master/README.md">GitHub 上的项目自述文件</a>。</p> +</div> + +<p>还有其他的 polyfill 选项，但是在撰写本文时，没有一个提供浏览器扩展 API polyfill 的覆盖范围。所以，如果你没有把 Firefox 作为你的首选，你的选择就是接受 polyfills 的限制，移植到 Firefox 并添加跨浏览器的支持，或者开发你自己的 polyfill。</p> + +<h3 id="API_函数覆盖率">API 函数覆盖率</h3> + +<p>这四个主要浏览器提供的 API 函数的实现差异可分为三大类:</p> + +<ul> + <li><strong>缺乏对整个功能的支持。</strong>例如，在撰写本文时，Edge 没有提供对<a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/privacy#Browser_compatibility">隐私</a>功能的支持。</li> + <li><strong>缺乏对某些特性的支持。</strong>例如，在撰写本文时，Firefox 不支持 <code>onButtonClicked</code>，而只支持 <code>onShown</code>。</li> + <li><strong>专有功能，支持特定于浏览器的特性。</strong>例如，在撰写本文时，容器是一个特定于 firefox 的特性，由 <code>contextualidentity</code> 函数支持。</li> +</ul> + +<p>你可以在 <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Mozilla Developer Network 浏览器对 JavaScript API 页面的支持</a>上找到4个主要浏览器对扩展 API 的支持细节，以及 Firefox for Android 对扩展 API 的支持细节。浏览器兼容性信息也包含在每个函数及其方法、类型和事件的 Mozilla Developer Network <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API">JavaScript APIs</a> 参考页面中。</p> + +<h4 id="处理_API_差异">处理 API 差异</h4> + +<p>解决这些差异的一个简单方法是将扩展中使用的函数限制在没有 API 差异的函数范围内。在实践中，对于大多数扩展，这种方法可能限制性太强。<br> + <br> + 相反，如果 API 之间存在差异，则应该提供替代实现或降级功能。(请记住: 您可能还需要这样考虑同一浏览器的不同版本之间的 API 支持差异。)</p> + +<p>使用运行时检查函数特性的可用性是实现备选或降级功能的推荐方法。执行运行时检查的好处是，如果函数是可用的，您不需要更新和重新分发扩展来使用它。</p> + +<p>下面的代码使您能够执行运行时检查:</p> + +<pre class="brush: js notranslate">if (typeof <function> === "function") { + // safe to use the function +}</pre> + +<h3 id="Manifest_字段">Manifest 字段</h3> + +<p>4个主要浏览器支持的 <code><a href="/zh-CN/docs/https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">manifest.json</a></code> 文件字段的差异大致可分为三类:</p> + +<ul> + <li><strong>扩展信息属性。</strong>例如，在撰写本文时，Firefox 和 Opera 包含和 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/author#Browser_compatibility">author</a></code> 地位相等的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer#Browser_compatibility">developer</a></code> 关键字，以获取扩展的开发者和作者的详细信息。</li> + <li><strong>扩展功能。</strong>例如，在编写本文时，Edge 不支持扩展定义快捷键的 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#Browser_compatibility">commands</a></code> 字段。</li> + <li><strong>字段可选性。</strong>例如，在编写本文时，在 Edge 中 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/author#Browser_compatibility">author</a></code> 字段是必需的，但在其他主要浏览器中是可选的。</li> +</ul> + +<p>浏览器兼容性信息包含在 Mozilla Developer Network <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code> 页的每个字段中。</p> + +<p><code>manifest.json</code> 文件在不同浏览器之间的版本号可能有所不同，为每个浏览器创建和编辑一个静态版本号通常是最简单的方法。</p> + +<h3 id="扩展打包">扩展打包</h3> + +<p>通过浏览器扩展商店打包和分发扩展相对简单。</p> + +<ul> + <li><font>火狐、 Chrome 和 Opera 都使用简单的 zip 格式打包，同时需要 </font><code>manifest.json</code> <font>文件位于压缩包的根目录。</font></li> + <li><font>但是，提交到 Microsoft 扩展商店需要对扩展文件进行额外打包。</font></li> +</ul> + +<p>有关打包的详细信息，请参阅相应扩展的开发人员门户网站上的指南。</p> + +<h3 id="扩展发布">扩展发布</h3> + +<p>这四种主要浏览器都维护有浏览器扩展商店。每个商店还对扩展进行审核，以检查安全漏洞。</p> + +<p>因此，您需要为每个商店分别添加和更新扩展。在某些情况下，您可以使用脚本上传扩展。</p> + +<p>下表总结了每个商店的做法和特点:</p> + +<table> + <tbody> + <tr> + <td></td> + <td> + <p>注册费</p> + </td> + <td> + <p>上传模块</p> + </td> + <td> + <p>发布审核</p> + </td> + <td> + <p>开发者账号需要2FA验证</p> + </td> + </tr> + <tr> + <td> + <p>Firefox</p> + </td> + <td> + <p>否</p> + </td> + <td> + <p><a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference">web-ext</a></p> + </td> + <td> + <p>全自动，仅需要几秒钟<sup>1</sup></p> + </td> + <td> + <p>否</p> + </td> + </tr> + <tr> + <td> + <p>Chrome</p> + </td> + <td> + <p>是</p> + </td> + <td> + <p>是</p> + </td> + <td> + <p>全自动，短于一小时</p> + </td> + <td> + <p>是</p> + </td> + </tr> + <tr> + <td> + <p>Opera</p> + </td> + <td> + <p>否</p> + </td> + <td> + <p>否</p> + </td> + <td> + <p>人工审核，但不需要提供SLA</p> + </td> + <td> + <p>否</p> + </td> + </tr> + <tr> + <td> + <p>Edge</p> + </td> + <td> + <p>是</p> + </td> + <td> + <p>否</p> + </td> + <td> + <p>人工审核，需要72小时<sup>2</sup></p> + </td> + <td> + <p>是</p> + </td> + </tr> + </tbody> +</table> + +<p><sup>1</sup> 在发布后会延期进行一次人工审查，如果发现了需要解决的问题，可能导致扩展被暂停。</p> + +<p><sup>2</sup> 在撰写本文时，微软只允许发布预先批准的扩展。</p> + +<h3 id="其他考虑">其他考虑</h3> + +<h4 id="扩展命名">扩展命名</h4> + +<p>Microsoft 要求扩展具有唯一的名称，并通过 Windows Dev Center 为扩展声明一个或多个名称。因此，即使您不打算立即支持 Edge，为微软保留一个扩展名可能是最谨慎的做法。</p> + +<h4 id="版本号指定">版本号指定</h4> + +<p>Firefox 和 Chrome 商店要求每个上传的扩展发布包都有一个单独的版本号。这意味着如果在线上遇到问题，就不能恢复到之前的版本号。</p> + +<h4 id="在不同的实现中共享资源">在不同的实现中共享资源</h4> + +<p>即使你要支持的平台中包括 Safari，仍然可以在对于不同浏览器的实现中共享许多资源。其中包括:</p> + +<ul> + <li>Images</li> + <li>HTML</li> + <li>CSS</li> +</ul> + +<h2 id="总结">总结</h2> + +<p>在进行跨平台扩展开发时，可以通过对标 Firefox 和使用 <a href="https://github.com/mozilla/webextension-polyfill/">WebExtension API Polyfill</a> 来解决扩展 API 之间的根本差异。遵循这种方法，您将在使用与提议的 WebExtension API 标准紧密结合的 API 特性中受益，并使用 promises 来简单的处理异步事件。</p> + +<p>跨平台工作的主要重点可能是处理主要浏览器支持的 API 特性之间的差异。创建你的 <code>manifest.json</code> 文件应该是相对简单的，你可以手动完成。然后，您将需要考虑扩展包中的打包差异，以及提交到每个扩展商店的过程差异。</p> + +<p>您同时可以使用<a href="https://github.com/notlmn/browser-extension-template"> browser-extension-template</a> 用于快速设置、生成和发布浏览器扩展项目。</p> + +<p>根据本文中的建议，您现在应该能够创建一个在四种主要浏览器上都运行良好的扩展程序，使您能够将扩展功能交付给更多的人。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/用户界面元素/index.html b/files/zh-cn/mozilla/add-ons/webextensions/用户界面元素/index.html new file mode 100644 index 0000000000..1e99cab52c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/用户界面元素/index.html @@ -0,0 +1,162 @@ +--- +title: 用户界面元素 +slug: Mozilla/Add-ons/WebExtensions/用户界面元素 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>该主题概括了所有你能用来创建你扩展的用户界面的组件。</p> + +<h2 id="浏览器行为">浏览器行为</h2> + +<p>浏览器行为是一个你能添加至浏览器工具栏的按钮，用户可以点击该按钮来与你的扩展交互。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="display: block; height: 387px; margin-left: auto; margin-right: auto; width: 782px;"></p> + +<p>有两种方式定义一个浏览器行为: 有一个 <a href="#Popups">弹出菜单</a>, 或者没有弹出菜单。</p> + +<p>当你没有定义一个弹出菜单时，用户点击按钮会导致一个消息被分发至扩展，而你可以使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/BrowserAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>browserAction.onClicked</code></a> 来监听它:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">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>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>如果你定义了弹出菜单，点击事件就不会被分发取而代之的是弹出菜单会显示出来。用户可以跟弹出菜单交互而当用户点击菜单外的区域时它会自动关闭。</p> + +<p>值得注意的是你的扩展只能拥有一个浏览器行为。</p> + +<h3 id="定义浏览器行为">定义浏览器行为</h3> + +<p>你通过使用在manifest.json 文件中使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 关键字定义浏览器行为的属性 - 图标, 标题, 弹出菜单 :</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"browser_action":</span> <span class="punctuation token">{</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span><span class="punctuation token">,</span> + <span class="key token">"default_popup":</span> <span class="string token">"popup/geo.html"</span> +<span class="punctuation token">}</span></code></pre> + +<p>唯一必要的关键字是 <code>default_icon</code>.你可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API 修改任何属性.</p> + +<h3 id="例子">例子</h3> + +<p>在GITHUB上的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> 资源包含了以下使用浏览行为的例子:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> 使用了没有弹出菜单的浏览器行为</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> 使用了由弹出菜单的浏览器行为</li> +</ul> + +<h2 id="页面行为">页面行为</h2> + +<p>页面行为在很多方面类似于 <a href="#Browser_actions">browser actions</a> , 除了:</p> + +<ul> + <li>浏览器行为按钮会一直显现，并且一直可用。</li> + <li>页面行为只会在几个页面并且该页面处于活动标签时显示。</li> +</ul> + +<p>为了强调页面行为只跟部分页面有联系，他们将其显示在地址栏内而不是工具栏:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/12960/page-action.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 850px;"></p> + +<p>不像浏览器行为，页面行为默认是关闭的, 调用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/show" title="Shows the page action for a given tab. The page action is shown whenever the given tab is the active tab."><code>pageAction.show()</code></a> 和<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/hide" title="Hides the page action for a given tab."><code>pageAction.hide()</code></a> 可以显示或隐藏页面行为。</p> + +<h3 id="定义页面行为">定义页面行为</h3> + +<p>通过在manifest.json中使用<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code> 关键字来定义页面行为的属性 —— 图标, 标题, 弹出菜单:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"page_action":</span> <span class="punctuation token">{</span> + <span class="key token">"browser_style":</span> <span class="keyword token">true</span><span class="punctuation token">,</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span><span class="punctuation token">,</span> + <span class="key token">"default_popup":</span> <span class="string token">"popup/geo.html"</span> +<span class="punctuation token">}</span></code></pre> + +<p><code>default_icon 是唯一强制要求的关键字</code>. 你可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">pageAction</a></code> API 修改所有的属性或现实或隐藏页面行为。</p> + +<h3 id="例子_2">例子</h3> + +<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a> 例子使用了一个页面行为。</p> + +<h2 id="弹出菜单">弹出菜单</h2> + +<p>一个弹出菜单是一个绑定至 <a href="#Browser_actions">browser action</a> 或者 <a href="#Page_actions">page action</a> 的对话框。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="display: block; height: 545px; margin-left: auto; margin-right: auto; width: 700px;"></p> + +<p>当用户点击按钮弹出菜单显示，当用户点击弹出菜单外的任何区域弹出菜单关闭。可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/close">window.close()</a></code> 来关闭弹出菜单。</p> + +<p>你可以使用专门的在manifest.json中使用"_execute_browser_action" 和 "_execute_page_action" 来定义一个快捷键打开浏览器行为或页面行为. 详情请看 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands">commands</a></code> manifest.json 关键字。不过你不能在你的扩展脚本中通过编程打开弹出菜单 : 他只能通过用户的行为的被打开。</p> + +<p>弹出菜单像普通网页一样通过HTML文件被定义，你当然也可以在里面包含CSS 和 javascript文件。 而且不像普通网页, 其包含的javascript可以使用所有的已经通过<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>获取了使用权限的 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> 。</p> + +<p>你可以要求浏览器在你的弹出菜单中包含一个样式表以使其看起来与浏览器UI一致。为了达成这一目的，在你的 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 或 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> 关键字中包含<code> "browser_style": true</code> 。</p> + +<p>弹出菜单存在一个限制其可以加载资源的源地址的安全机制， 同时不允许类似 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> 的做法的使用 查看 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> 获取更多细节。</p> + +<p>你可以使用Add-on Debugger来调试弹出菜单标记和脚本，但是你需要一些技巧来设置让弹出菜单不在自动关闭。<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging#Debugging_popups"> 阅读关于调试弹出菜单</a>。</p> + +<h3 id="弹出菜单尺寸重新计算">弹出菜单尺寸重新计算</h3> + +<p>弹出菜单自动根据其内容调整尺寸。其适应算法可能因浏览器而不同。</p> + +<p>在火狐, 尺寸只再弹出菜单显示前被计算，而且在内容变化后至多进行每秒十次的计算。严格来说， 尺寸受 <code><a href="/en-US/docs/Web/HTML/Element/body"><body></a></code> 元素放置尺寸决定。 一种怪异的说法是, 他由 <code><a href="/en-US/docs/Web/HTML/Element/html"><html></a></code> 决定， Firefox 计算该元素的推荐宽度, 重新调整弹出菜单至其宽度， 然后完成尺寸调整所以这里没有上下滚动。 如果适应用户的屏幕他可能会增长到800X600px的尺寸。 如果用户 <a href="https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar">移动弹出菜单对应按钮到菜单面板</a> ，而后弹出菜单会在菜单栏内显示并具有合适的尺寸。</p> + +<h2 id="设置页面">设置页面</h2> + +<p>设置页面允许你定义你的扩展可以被用户修改的选项。 用户从浏览器扩展管理器中访问设置页面:</p> + +<p>{{EmbedYouTube("02oXAcbUv-s")}}</p> + +<p>每个浏览器访问该页面的方法存在区别。</p> + +<ul> +</ul> + +<p>你可以通过调用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Runtime/openOptionsPage" title="If your add-on does not have an options page, or the browser failed to create one for some other reason, runtime.lastError will be set."><code>runtime.openOptionsPage()</code></a> 打开设置页面</p> + +<p>设置页面存在一个限制其可以加载资源的源地址的安全机制， 同时不允许类似 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> 的做法的使用 查看 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> 获取更多细节。</p> + +<h3 id="定义一个设置页面：">定义一个设置页面：</h3> + +<p>创建一个设置页面有以下流程：</p> + +<ul> + <li>写一个HTML文件定义页面。该文件像普通网页一样可以包含CSS和Javascript 文件而且可以使用所有 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> ，特别的你可以使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Storage" title="Enables WebExtensions to store and retrieve data, and listen for changes to stored items."><code>storage</code></a> API 来保存设置。</li> + <li>将这些文件打包至你的扩展。</li> + <li>在manifest.json 文件包含 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code> 关键字， 并给予设置页面的URL。</li> +</ul> + +<h3 id="例子_3">例子</h3> + +<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a> 使用了设置页面。</p> + +<h2 id="上下文菜单项">上下文菜单项</h2> + +<p>使用 {{WebExtAPIRef("contextMenus")}} API, 你可以按你指定的情况向浏览器上下文菜单添加项目, 比如，你可以只在用户点击图片时显示一项，或者在一个可编辑的元素上，或者被选择的页面的一部份。</p> + +<h3 id="指定一个上下文菜单项">指定一个上下文菜单项</h3> + +<p>您可以使用{{WebExtAPIRef("contextMenus")}} API来 程序化地管理上下文菜单项。</p> + +<h3 id="例子_4">例子</h3> + +<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-demo">context-menu-demo</a> 创建了几种不同的上下文菜单项。</p> + +<h2 id="通知">通知</h2> + +<p>使用 {{WebExtAPIRef("notifications")}} API，你通过使用操作系统的通知系统可以创建短时通知:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="display: block; height: 334px; margin-left: auto; margin-right: auto; width: 700px;"></p> + +<h3 id="定义一个通知">定义一个通知</h3> + +<p>使用{{WebExtAPIRef("notifications")}} API 可以程序化地管理通知。</p> + +<h3 id="Examples">Examples</h3> + +<p><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 创建了通知。</p> |