diff options
| author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 21:46:22 -0500 |
|---|---|---|
| committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 21:46:22 -0500 |
| commit | a065e04d529da1d847b5062a12c46d916408bf32 (patch) | |
| tree | fe0f8bcec1ff39a3c499a2708222dcf15224ff70 /files/zh-cn/mozilla/add-ons/sdk | |
| parent | 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 (diff) | |
| download | translated-content-a065e04d529da1d847b5062a12c46d916408bf32.tar.gz translated-content-a065e04d529da1d847b5062a12c46d916408bf32.tar.bz2 translated-content-a065e04d529da1d847b5062a12c46d916408bf32.zip | |
update based on https://github.com/mdn/yari/issues/2028
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/sdk')
40 files changed, 0 insertions, 7993 deletions
diff --git a/files/zh-cn/mozilla/add-ons/sdk/builder/index.html b/files/zh-cn/mozilla/add-ons/sdk/builder/index.html deleted file mode 100644 index 1baa282d43..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/builder/index.html +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Builder -slug: Mozilla/Add-ons/SDK/Builder -translation_of: Archive/Add-ons/Add-on_SDK/Builder ---- -<p>The Add-on Builder was a web-based development environment that allowed developers to create add-ons using the SDK APIs, but without needing to use the <code>cfx</code> command line tool. It was retired on April 1, 2014, and the "builder.addons.mozilla.org" domain now redirects to this page.<br> - <br> - If you have only used the SDK through the Builder, you already know most of what you need to know to develop using just the SDK. The <a href="/en-US/Add-ons/SDK/High-Level_APIs">high-level</a> and <a href="/en-US/Add-ons/SDK/Low-Level_APIs">low-level</a> APIs used for Builder add-ons are exactly the same for Builder and SDK. To switch to the SDK:</p> -<ul> - <li><a href="/en-US/Add-ons/SDK/Tutorials/Installation">install the SDK locally</a></li> - <li>get to know the cfx command line tool, with this <a href="/en-US/Add-ons/SDK/Tutorials/Getting_started">introductory walkthrough</a> and the <a href="/en-US/Add-ons/SDK/Tools/cfx">detailed <code>cfx</code> reference</a></li> - <li>get to know the <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> file used to configure attributes of your add-on</li> -</ul> diff --git a/files/zh-cn/mozilla/add-ons/sdk/guides/content_scripts/index.html b/files/zh-cn/mozilla/add-ons/sdk/guides/content_scripts/index.html deleted file mode 100644 index fa95b15db3..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/guides/content_scripts/index.html +++ /dev/null @@ -1,486 +0,0 @@ ---- -title: Content Scripts（内容脚本） -slug: Mozilla/Add-ons/SDK/Guides/Content_Scripts -translation_of: Archive/Add-ons/Add-on_SDK/Guides/Content_Scripts ---- -<article id="wikiArticle">{{AddonSidebar}} -<p><span class="seoSummary">很多 add-ons 需要访问和修改 web 页面的内容。但是 add-on 的主代码不能直接访问 web 内容。替代方案是, SDK add-ons 需要使用一些分散的脚本代理访问 web 内容，这些脚本被称作<em>内容脚本（content scripts）</em>。本页面描述如何开发和部署内容脚本。 </span></p> - -<p>内容脚本是在使用SDK时很令人疑惑的点，但你很有可能不得不使用它们。下面有五个基本原则：</p> - -<ul> - <li>add-on 的主代码，包括"main.js"和其他"lib"下的模块，可以使用 SDK <a href="/zh-CN/docs/Mozilla/Add-ons/SDK/High-Level_APIs">高层次</a>和<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Low-Level_APIs">低层次</a> APIs，但不能直接访问 web 内容</li> - <li>内容脚本 <a href="/en-US/Add-ons/SDK/Guides/Two_Types_of_Scripts#API_Access_for_Add-on_Code_and_Content_Scripts">不能使用 SDK 的 API</a>（访问不了 globals 的 <code>exports</code>、<code>require</code>），但你可以访问 web 内容</li> - <li>SDK API 可以使用，内容脚本，比如 <a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod">page-mod</a> 和 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs">tabs</a>，提供了一些函数，使得 add-on 的主代码可以将内容脚本载入web页面中。</li> - <li>内容脚本可以作为字符串加载，但是更常见的是分离存储为 add-on 的"data"目录下文件。 jpm 不会默认创建"data"目录，所以你必须添加该目录并把脚本放进去。</li> - <li>一个消息传递 API 允许主代码和内容脚本间相互通信。</li> -</ul> - -<p>这个完整的 add-on 表现出所有的这些原则。它的"main.js"使用 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs">tabs</a> 模块附加了一个内容脚本到当前标签页。本例中内容脚本作为字符串传递，内容脚本简单地替换了页面的内容：</p> - -<pre class="brush: js">// main.js -var tabs = require("sdk/tabs"); -var contentScriptString = 'document.body.innerHTML = "<h1>this page has been eaten</h1>";' - -tabs.activeTab.attach({ - contentScript: contentScriptString -});</pre> - -<p>下面的高层次 SDK 模块能使用内容脚本来修改 web 页面：</p> - -<ul> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod">page-mod</a>：使你能附加一个内容脚本到匹配上特定 URL 模式的web页面。</li> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs">tabs</a>：导出一个 <code>Tab</code> 对象来处理浏览器标签页。<code>Tab</code> 对象包括了一个 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#attach(options)"><code>attach()</code></a> 函数来附加内容脚本到标签页。</li> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs/page-worker">page-worker</a>：让你能够恢复一个 web 页面，但不显示它。你可以附加内容脚本到该页面，来访问和操作该页面的 DOM。</li> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs/context-menu">context-menu</a>：使用内容脚本来和按钮所在的页面交互。</li> -</ul> - -<p>另外，还能使用 HTML 定义了一些 SDK 用户接口组件，并且使用分类的脚本来和这些内容交互。从很多方面来讲，这些脚本就像内容脚本一样，但它们并不是本文的关注点。要学习如何和用户接口模块的内容交互，请参看模块定义文档：<a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panel</a>、<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar">sidebar</a>、<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_frame">frame</a>。</p> - -<p>这篇指南中列出的几乎所有的示例都是完整并且且最小的，可以在 Github 的 <a href="https://github.com/mdn/addon-sdk-content-scripts">addon-sdk-content-scripts repository</a> 页面上获得。</p> - -<h2 id="加载用户脚本">加载用户脚本</h2> - -<article id="wikiArticle"> -<p>你可以声明一个字符串或者指定 <code>contentScript</code> 或 <code>contentScriptFile</code> 选项加载一个单独的脚本。<code>contentScript</code> 选项接受一个作为脚本的字符串：</p> - -<pre class="brush: js">// main.js - -var pageMod = require("sdk/page-mod"); -var contentScriptValue = 'document.body.innerHTML = ' + - ' "<h1>Page matches ruleset</h1>";'; - -pageMod.PageMod({ - include: "*.mozilla.org", - contentScript: contentScriptValue -});</pre> - -<p><code>contentScriptFile</code> 选项接受一个作为 resource:// URL 的字符串，指向一个存储在你的 add-on 的 <code>data</code> 目录中的脚本文件。jpm不会默认创建"data"目录，所以你必须创建该目录并将你的用户脚本放进去。</p> - -<p>本 add-on 提供一个 URL ，指向"content-script.js"文件，存储在 add-on 根目录下的 <code>data</code> 子目录：</p> - -<pre class="brush: js">// main.js - -var data = require("sdk/self").data; -var pageMod = require("sdk/page-mod"); - -pageMod.PageMod({ - include: "*.mozilla.org", - contentScriptFile: data.url("content-script.js") -});</pre> - -<pre class="brush: js">// content-script.js - -document.body.innerHTML = "<h1>Page matches ruleset</h1>";</pre> - -<div class="note"> -<p>从 Firefox 34 开始，你可以使用"./content-script.js"替代 self.data.url("content-script.js")。所以你可以像这样重写：</p> - -<pre class="brush: js">var pageMod = require("sdk/page-mod"); - -pageMod.PageMod({ - include: "*.mozilla.org", - contentScriptFile: "./content-script.js" -}); -</pre> -</div> - -<div class="warning"> -<p>除非你的内容脚本非常简单并且固定是一个静态的字符串，请不要使用 <code>contentScript</code>：否则，你会在从 AMO 获取你的add-on上遇到问题。</p> - -<p>相反，把脚本放到一个单独的文件并用 <code>contentScriptFile</code> 加载它。这回事你的代码更易维护、安全、调试和审核。</p> -</div> - -<p>你可以给 <code>contentScript</code> 或 <code>contentScriptFile</code> 传递字符串数组来加载多个脚本：</p> - -<pre class="brush: js">// main.js - -var tabs = require("sdk/tabs"); - -tabs.on('ready', function(tab) { - tab.attach({ - contentScript: ['document.body.style.border = "5px solid red";', 'window.alert("hi");'] - }); -}); -</pre> - -<pre class="brush: js">// main.js - -var data = require("sdk/self").data; -var pageMod = require("sdk/page-mod"); - -pageMod.PageMod({ - include: "*.mozilla.org", - contentScriptFile: [data.url("jquery.min.js"), data.url("my-content-script.js")] -});</pre> - -<p>如果你这么做，这些脚本之间可以直接交互，就像他们被同一个 web 页面加载一样。</p> - -<p>你也可以把 <code>contentScript</code> 和 <code>contentScriptFile</code> 一起用。如果你这么做，使用 <code>contentScriptFile</code> 定义的脚本会在使用 <code>contentScript</code> 定义的脚本之前加载。这使你能够用 URL 加载比如 jQuery 这样的 JavaScript 库，然后传递一个简单的能够使用jQuery脚本：</p> - -<pre class="brush: js">// main.js - -var data = require("sdk/self").data; -var pageMod = require("sdk/page-mod"); - -var contentScriptString = '$("body").html("<h1>Page matches ruleset</h1>");'; - -pageMod.PageMod({ - include: "*.mozilla.org", - contentScript: contentScriptString, - contentScriptFile: data.url("jquery.js") -});</pre> - -<div class="warning"> -<p>除非你的内容脚本非常简单并且固定是一个静态的字符串，请不要使用 <code>contentScript</code>：否则，在从 AMO 获取你的 add-on 上，你会遇到问题。</p> - -<p>相反，把脚本放到一个单独的文件并用 <code>contentScriptFile</code> 加载它。这回事你的代码更易维护、安全、调试和审核。</p> -</div> - -<h3 id="控制附加脚本的时间">控制附加脚本的时间</h3> - -<p><code>contentScriptWhen</code> 选项指定了什么时候加载内容脚本。从这里选一个：</p> - -<ul> - <li><code>"start"</code>：页面 document 元素插入 DOM 之后，立即加载脚本。这时 DOM 的内容仍未加载，所以脚本不能与其交互。</li> - <li><code>"ready"</code>：页面 DOM 加载完后加载脚本：也就是说，在那个时间点 <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> 事件触发。这时，内容脚本可以和DOM内容交互，但外部引用的样式表和图片可能还没有完成加载。</li> - <li><code>"end"</code>：页面上所有内容（DOM、JS、CSS、images）加载完后，加载脚本，就是在 <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload 事件</a>触发的时候</li> -</ul> - -<p>默认值为 <code>"end"</code>。</p> - -<p>注意 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#attach(options)"><code>tab.attach()</code></a> 不支持 contentScriptWhen，因为它原来就是在页面加载页面的时候被调用的。</p> - -<h3 id="传递配置选项">传递配置选项</h3> - -<p><code>contentScriptOptions</code> 是一个作为只读对象暴露给内容脚本的JSON对象，在 <code><a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/self">self</a>.options</code> 的属性里:</p> - -<pre class="brush: js">// main.js - -var tabs = require("sdk/tabs"); - -tabs.on('ready', function(tab) { - tab.attach({ - contentScript: 'window.alert(self.options.message);', - contentScriptOptions: {"message" : "hello world"} - }); -});</pre> - -<p>这里可以使用任何可以转成json的值（object、array、string等等）。</p> - -<h2 id="访问_DOM">访问 DOM</h2> - -<p>内容脚本可以访问页面的 DOM，就像任何页面中加载的脚本（页面脚本）一样。但是内容脚本和页面脚本之间是隔离的：</p> - -<ul> - <li>内容脚本不能看到任何由页面脚本添加到页面的 JavaScript 对象</li> - <li>如果页面脚本重定义了某个 DOM 对象的行为，但内容脚本只会看到原来的那个行为。</li> -</ul> - -<p>相反也是如此：页面脚本不能看到内容脚本添加的 JavaScript 对象。</p> - -<p>例如，假想一个页面用页面脚本添加变量 <code>foo</code> 到 <code>window</code> 对象：</p> - -<pre class="brush: html"><!DOCTYPE html"> -<html> - <head> - <script> - window.foo = "hello from page script" - </script> - </head> -</html></pre> - -<p>在这个脚本后面加载到页面的其他脚本也可以访问 <code>foo</code>。但是内容脚本不能：</p> - -<pre class="brush: js">// main.js - -var tabs = require("sdk/tabs"); -var mod = require("sdk/page-mod"); -var self = require("sdk/self"); - -var pageUrl = self.data.url("page.html") - -var pageMod = mod.PageMod({ - include: pageUrl, - contentScript: "console.log(window.foo);" -}) - -tabs.open(pageUrl);</pre> - -<pre>console.log: my-addon: null -</pre> - -<p>这种隔离策略有着很合理的理由。首先，这意味着内容脚本不会泄露对象给 web 页面，这样可能会打开安全漏洞。第二，这意味着，在内容脚本创建对象的时候，可以不用担心是否会和页面脚本添加的对象相冲突。</p> - -<p>这种隔离意味着，例如，如果一个 web 页面加载了 jQuery 库，那么内容脚本不能够看到由该库添加的 <code>jQuery</code> 对象——但是可以看到内容脚本添加的自己的 <code>jQuery</code> 对象，并且它不会和页面脚本的 jQuery 版本冲突。</p> - -<h3 id="和页面脚本交互">和页面脚本交互</h3> - -<p>一般来说，这种内容脚本和页面脚本的隔离正是你所希望的。但是有时候你也许会希望和页面脚本交互：你想在内容脚本和页面脚本之间共享对象来，来在它们之间发送消息。如果你需要这么做，请阅读<a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/Interacting_with_page_scripts">和页面脚本交互</a>。</p> - -<h3 id="事件监听器">事件监听器</h3> - -<p>你可以监听 DOM 的事件，就像在页面脚本中一样，但是有两个重要的区别：</p> - -<p>第一，如果你向 <a href="https://developer.mozilla.org/en/DOM/element.setAttribute"><code>setAttribute()</code></a> 传递字符串，来定义了事件监听器，那么此监听器被当做是在页面上下文中的，所以它不能访问任何内容脚本中的变量。</p> - -<p>如下，内容脚本会失败报错"theMessage is not defined"：</p> - -<pre class="brush: js">var theMessage = "Hello from content script!"; -anElement.setAttribute("onclick", "alert(theMessage);");</pre> - -<p>Second, if you define an event listener by direct assignment to a <a href="/en-US/docs/Web/API/GlobalEventHandlers">global event handler</a> like <code>onclick</code>, then the assignment might be overridden by the page. For example, here's an add-on that tries to add a click handler by assignment to <code>window.onclick</code>:</p> - -<pre class="brush: js">var myScript = "window.onclick = function() {" + - " console.log('unsafewindow.onclick: ' + window.document.title);" + - "}"; - -require("sdk/page-mod").PageMod({ - include: "*", - contentScript: myScript, - contentScriptWhen: "start" -});</pre> - -<p>这个示例会在大多数页面上正常工作，但是会在定义 <code>onclick</code> 的页面上失败：</p> - -<pre class="brush: html"><html> - <head> - </head> - <body> - <script> - window.onclick = function() { - window.alert("it's my click now!"); - } - </script> - </body> -</html></pre> - -<p>由于这些原因，最好还是用 <a href="https://developer.mozilla.org/en/DOM/element.addEventListener"><code>addEventListener()</code> 添加一个事件监听器</a>，定义监听器为一个函数：</p> - -<pre class="brush: js">var theMessage = "Hello from content script!"; - -anElement.onclick = function() { - alert(theMessage); -}; - -anotherElement.addEventListener("click", function() { - alert(theMessage); -});</pre> - -<h2 id="和_add-on_通信">和 add-on 通信</h2> - -<p>为了使 add-on 脚本和内容脚本相互通信，任何一通信端都要访问 <code>port</code> 对象。</p> - -<ul> - <li>要从一头发送消息到另一头，使用 <code>port.emit()</code></li> - <li>要从另一头接收消息，使用 <code>port.on()</code></li> -</ul> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7873/content-scripting-overview.png" style="display: block; margin-left: auto; margin-right: auto;">消息是异步的：也就是说，发送方不会等待接收方的回应，而仅仅是发送消息完后继续处理别的事情。</p> - -<p>这里有一个简单的 add-on 使用 <code>port</code> 发送一个消息到内容脚本：</p> - -<pre class="brush: js">// main.js - -var tabs = require("sdk/tabs"); -var self = require("sdk/self"); - -tabs.on("ready", function(tab) { - var worker = tab.attach({ - contentScriptFile: self.data.url("content-script.js") - }); - worker.port.emit("alert", "Message from the add-on"); -}); - -tabs.open("http://www.mozilla.org");</pre> - -<pre class="brush: js">// content-script.js - -self.port.on("alert", function(message) { - window.alert(message); -});</pre> - -<div class="note"> -<p>context-menu 模块没有使用这里描述的通信模型。了解更多关于使用 context-menu 和内容脚本通信的事情，参看 <a href="/en-US/Add-ons/SDK/High-Level_APIs/context-menu">context-menu documentation</a>。</p> -</div> - -<h3 id="在内容脚本中访问_port"><code>在内容脚本中访问 port</code></h3> - -<p>内容脚本中，<code>port</code> 对象是作为global下 <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/self"><code>self</code></a> 对象的属性。所以要从内容脚本中发送消息的话：</p> - -<pre class="brush: js">self.port.emit("myContentScriptMessage", myContentScriptMessagePayload);</pre> - -<p>要从 add-on 代码接收消息</p> - -<pre class="brush: js">self.port.on("myAddonMessage", function(myAddonMessagePayload) { - // Handle the message -});</pre> - -<div class="note"> -<p>注意 global下 <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/self"><code>self</code></a> 对象和 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code> 模块</a>完全不一样，后者提供一个API给 add-on，用来访问它的数据文件和ID。</p> -</div> - -<h3 id="在内容脚本中访问_port_2">在内容脚本中访问 port</h3> - -<p>在 add-on 代码中，联通 add-on 和某一特定内容脚本上下文的通道被封装入 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/content_worker"><code>worker</code></a> 对象。所以和内容脚本通信的 <code>port</code> 对象其实是其相对应的 <code>worker</code> 对象的一个属性。</p> - -<p>但是，这个 worker 没有暴露给 add-on 代码，以及同样所有的模块。</p> - -<h4 id="从_page-worker">从 <code>page-worker</code></h4> - -<p><code>page-worker</code> 对象直接整合了 work API。所以要从一个由 <code>page-worker</code> 关联的内容脚本接收消息的话，你可以使用 <code>pageWorker.port.on()</code>：</p> - -<pre class="brush: js">// main.js - -var self = require("sdk/self"); - -var pageWorker = require("sdk/page-worker").Page({ - contentScriptFile: self.data.url("content-script.js"), - contentURL: "http://en.wikipedia.org/wiki/Internet" -}); - -pageWorker.port.on("first-para", function(firstPara) { - console.log(firstPara); -});</pre> - -<p>要从你的 add-on 发送用户定义的消息，你可以只调用 <code>pageWorker.port.emit()</code>：</p> - -<pre class="brush: js">// main.js - -var self = require("sdk/self"); - -var pageWorker = require("sdk/page-worker").Page({ - contentScriptFile: self.data.url("content-script.js"), - contentURL: "http://en.wikipedia.org/wiki/Internet" -}); - -pageWorker.port.on("first-para", function(firstPara) { - console.log(firstPara); -}); - -pageWorker.port.emit("get-first-para");</pre> - -<pre class="brush: js">// content-script.js - -self.port.on("get-first-para", getFirstPara); - -function getFirstPara() { - var paras = document.getElementsByTagName("p"); - if (paras.length > 0) { - var firstPara = paras[0].textContent; - self.port.emit("first-para", firstPara); - } -}</pre> - -<h4 id="从_page-mod">从<code> page-mod</code></h4> - -<p>单个 <code>page-mod</code> 对象可以附加它的脚本到多个页面，每个页面有它自己的上下文来运行内容脚本，所以每个页面都需要相互隔离的通道（worker）。</p> - -<p>所以 <code>page-mod</code> 没有直接整合 worker 的 API。而是在每次内容脚本被附加到页面时，page-mod 发送一个 <code>attach</code> 事件，它的监听器会给对应的上下文传递一个 worker。通过为 <code>attach</code> 提供一个监听器，你可以访问被一个 page-mod 附加到页面上的内容脚本的 <code>port</code> 对象：</p> - -<pre class="brush: js">// main.js - -var pageMods = require("sdk/page-mod"); -var self = require("sdk/self"); - -var pageMod = pageMods.PageMod({ - include: ['*'], - contentScriptFile: self.data.url("content-script.js"), - onAttach: startListening -}); - -function startListening(worker) { - worker.port.on('click', function(html) { - worker.port.emit('warning', 'Do not click this again'); - }); -}</pre> - -<pre class="brush: js">// content-script.js - -window.addEventListener('click', function(event) { - self.port.emit('click', event.target.toString()); - event.stopPropagation(); - event.preventDefault(); -}, false); - -self.port.on('warning', function(message) { - window.alert(message); -}); -</pre> - -<p>上面的 add-on 里有两条消息：</p> - -<ul> - <li>当用户点击页面元素时，<code>click</code> 从 page-mod 被发送到当前 add-on。</li> - <li><code>warning</code> 发送一条傻气的字符串回给page-mod</li> -</ul> - -<h4 id="从_Tab.attach()">从 <code>Tab.attach()</code></h4> - -<p><code>Tab.attach()</code> 方法返回一个 worker，你可以用来和附加的内容脚本通信。</p> - -<p>这个 add-on 添加了一个按钮到Firefox：等用户点击按钮是，这个 add-on 附加一个内容脚本到当前的标签页，发送给内容脚本一条名为 "my-addon-message"的消息，并且监听名为"my-script-response"的响应：</p> - -<pre class="brush: js">//main.js - -var tabs = require("sdk/tabs"); -var buttons = require("sdk/ui/button/action"); -var self = require("sdk/self"); - -buttons.ActionButton({ - id: "attach-script", - label: "Attach the script", - icon: "./icon-16.png", - onClick: attachScript -}); - -function attachScript() { - var worker = tabs.activeTab.attach({ - contentScriptFile: self.data.url("content-script.js") - }); - worker.port.on("my-script-response", function(response) { - console.log(response); - }); - worker.port.emit("my-addon-message", "Message from the add-on"); -} -</pre> - -<pre class="brush: js">// content-script.js - -self.port.on("my-addon-message", handleMessage); - -function handleMessage(message) { - alert(message); - self.port.emit("my-script-response", "Response from content script"); -}</pre> - -<h3 id="port的API">port的API</h3> - -<p>参看 <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/port"><code>port</code> 对象的参考文档</a>.</p> -</article> - -<h3 id="postMessage的API">postMessage的API</h3> - -<p>在 <code>port</code> 对象加载之前，add-on 代码和内容脚本可以使用另一个 API 通信：</p> - -<ul> - <li>内容脚本调用 <code>self.postMessage()</code> 来发送，并用 <code>self.on()</code> 来接收</li> - <li>内容脚本调用 <code>worker.postMessage()</code> 来发送，并用 <code>worker.on()</code> 来接收</li> -</ul> - -<p>这个API依然可用，并且还有<a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_postMessage">文档</a>，但是没有理由替代前文描述的 <code>port</code> API。 例外是 <a href="/en-US/Add-ons/SDK/High-Level_APIs/context-menu">context-menu</a> 模块，它还是使用 postMessage。</p> - -<h3 id="内容脚本的内容脚本">内容脚本的内容脚本</h3> - -<p>内容脚本可用直接和其他同一个上下文中的内容脚本通信。举个例子，如果一次 <code>Tab.attach()</code> 的调用附加了两个脚本，那么他们可用直接相互查看，就像加载在同一页面内的页面脚本一样。但是如果你调用 <code>Tab.attach()</code> 两次，每次附加一个内容脚本，那么这些内容脚本之间不能通信。你必须使用port API 通过 add-on 的主代码来传递消息。</p> - -<h2 id="跨域的内容脚本">跨域的内容脚本</h2> - -<p>默认情况下，内容脚本没有跨域的权限。特别是，它们不能访问在不同 <code>iframe</code> 中的在另外的域名上的内容，也不能发起跨域的 XMLHttpRequests。</p> - -<p>但是，你可以把需要的域名添加到 <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> 中<code>"permissions"</code>键下的 <code>"cross-domain-content"</code>键下，为这些域名打开这些特性。参阅文章<a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/Cross_Domain_Content_Scripts">跨域内容脚本</a>。</p> -</article> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/guides/index.html b/files/zh-cn/mozilla/add-ons/sdk/guides/index.html deleted file mode 100644 index 51fbdef445..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/guides/index.html +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: 教程 -slug: Mozilla/Add-ons/SDK/Guides -tags: - - NeedsTranslation - - TopicStub -translation_of: Archive/Add-ons/Add-on_SDK/Guides ---- -<p>下面列出了一些文章可以加深你对SDK的理解</p> -<hr> -<h3 id="投稿者的教程"><a name="contributors-guide">投稿者的教程</a></h3> -<div class="column-container"> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Getting_Started">起步</a></dt> - <dd> - 学会如何使用SDK : 编写代码, 调试bug, 提交补丁, 审核项目, 获得帮助.</dd> - <dt> - <a href="Guides/Modules">模块</a></dt> - <dd> - 通过SDK学会模块的使用 (以CommonJS为规范), 懂得如何使用 sandboxes 和compartments 提高安全性, 并且了解内置的 SDK module loader (被称为Cuddlefish).</dd> - <dt> - <a href="Guides/Classes_and_Inheritance">类 和 继承</a></dt> - <dd> - 学会<strong> 类</strong>和<strong>继承</strong>在JavaScript中的运行机制, 使用<strong>构造(constructors)</strong>和<strong>原型(prototypes)</strong>, 并知道如何使用SDK提供的函数帮助器简化它.</dd> - </dl> - </div> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Private_Properties">私有成员</a></dt> - <dd> - 通过 前缀, 闭包, 和WeakMaps 学会私有成员如何在JavaScript中的实现, 使用 命名空间(通常指WeakMaps) 学会SDK如何支持私有成员.</dd> - <dt> - <a href="Guides/Content_Processes">脚本运行流程</a></dt> - <dd> - SDK的设计目的是为了使控制网页内容的扩展脚本可以在不同进程的环境中运行. 这篇文章强调了这一设计的特点.</dd> - </dl> - </div> -</div> -<hr> -<h3 id="SDK的基础结构"><a name="sdk-infrastructure">SDK的基础结构</a></h3> -<div class="column-container"> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Module_structure_of_the_SDK">SDK 模块结构</a></dt> - <dd> - SDK是可重复使用的 JavaScript 模块. 这里解释了什么是模块, 怎样加载模块, 和SDK模块树的构造.</dd> - <dt> - <a href="Guides/SDK_API_Lifecycle">SDK API 生存周期</a></dt> - <dd> - 为SDK的API定义生命周期, 包括API稳定性的排名</dd> - </dl> - </div> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Program_ID">程序 ID</a></dt> - <dd> - 程序ID 是扩展独一无二的标识符. 教程解释了如何定义你自己的程序 ID.</dd> - <dt> - <a href="Guides/Firefox_Compatibility">Firefox 兼容</a></dt> - <dd> - 解决不同版本SDK生成的扩展与不同版本Firefox的兼容问题</dd> - </dl> - </div> -</div> -<hr> -<h3 id="SDK_常用技巧"><a name="sdk-idioms">SDK 常用技巧</a></h3> -<div class="column-container"> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Working_with_Events">善用 事件触发</a></dt> - <dd> - 通过SDK的事件触发框架 写出以事件驱动为基础的代码</dd> - </dl> - </div> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Two_Types_of_Scripts">脚本的两种类型</a></dt> - <dd> - 这篇文章可以帮助你理解扩展中的API和普通脚本的区别</dd> - </dl> - </div> -</div> -<p> </p> -<hr> -<h3 id="XUL_迁移"><a name="xul-migration">XUL 迁移</a></h3> -<div class="column-container"> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/XUL_Migration_Guide">XUL 迁移教程</a></dt> - <dd> - 把XUL扩展迁移到SDK的技巧</dd> - <dt> - <a href="Guides/XUL_vs_SDK">XUL 与 SDK 不同</a></dt> - <dd> - 比较 传统的以XUL为基础的扩展 和 SDK 两者优点和缺点</dd> - </dl> - </div> - <div class="column-half"> - <dl> - <dt> - <a href="Guides/Porting_the_Library_Detector">移植例子</a></dt> - <dd> - 一个简单地教你如何让 基于XUL的扩展 迁移到 SDK中的实例</dd> - </dl> - </div> -</div> -<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/guides/multiprocess_firefox_and_the_sdk/index.html b/files/zh-cn/mozilla/add-ons/sdk/guides/multiprocess_firefox_and_the_sdk/index.html deleted file mode 100644 index c22dd0181e..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/guides/multiprocess_firefox_and_the_sdk/index.html +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: 多进程 Firefox 与 SDK -slug: Mozilla/Add-ons/SDK/Guides/Multiprocess_Firefox_and_the_SDK -translation_of: Archive/Add-ons/Add-on_SDK/Guides/Multiprocess_Firefox_and_the_SDK ---- -<p>我们目前正在使 Firefox 变为多进程，它为浏览器界面使用一个操作系统进程，为运行的网页使用另一个进程来执行代码，这个项目被称为 "electrolysis" 或者 "e10s"。更多信息请参考<a href="/en-US/Firefox/Multiprocess_Firefox">多进程 Firefox 相关页面</a>。</p> - -<p>本文章介绍了开发者如何测试基于 SDK 的附加组件是否与多进程的 Firefox 兼容，以及如何解决出现的问题。</p> - -<h2 id="SDK_的合约">SDK 的合约</h2> - -<p>SDK 为附加组件的开发者承诺了：</p> - -<ul> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs">顶层 API</a> 对多进程 Firefox 完全工作。如果并没有，请报告为 SDK 中的 bug。</li> - <li><a href="/en-US/Add-ons/SDK/Low-Level_APIs">底层 API</a> 也许不工作。如果你在使用底层 API，考虑检查、测试和重构某些代码。</li> -</ul> - -<p>在实践中，大多数底层 API 将正常工作，但可以直接访问网页内容的底层 API 无法正常工作。</p> - -<h2 id="兼容性垫片">兼容性垫片</h2> - -<p>举例来说，你可能认为这是行不通的：</p> - -<pre class="brush: js">var contentDocument = require("sdk/window/utils") - .getMostRecentBrowserWindow().content.document;</pre> - -<p>但是，Firefox 为附加组件提供了许多 API 的兼容性垫片。这意味着许多 API，包括上述例子的那个，仍然工作。虽然有两条警示需注意：</p> - -<ul> - <li>这些垫片不完美：某些附加组件在有垫片的情况下仍然不工作。举例来说，许多垫片通过为内容对象返回跨进称对象包装器来工作，并且这<a href="/en-US/Firefox/Multiprocess_Firefox/Cross_Process_Object_Wrappers#Limitations_of_CPOWs">并非始终以同样的方式</a>作为内容对象。</li> - <li>这些垫片可能对性能有不良影响，我们希望人们最终去除它们。</li> -</ul> - -<p>We don't yet have a complete list of low-level APIs that are not multiprocess compatible: that is, will not work without the shims. Where we know that a low-level API is not multiprocess compatible, we've indicated that in the documentation page for it.</p> - -<h2 id="测试">测试</h2> - -<p>To test whether an add-on works without the shims, use the <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions">"multiprocess" permission</a>.</p> - -<div class="note"> -<p><strong>Note</strong> that you can only do this if you are using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>. You can't use the <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions">"multiprocess" permission</a> if you are using <a href="/en-US/Add-ons/SDK/Tools/cfx">cfx</a>.</p> -</div> - -<p>Setting this permission will disable the shims for your add-on, so you can test to see if it's really multiprocess compatible or not.</p> - -<p>However, there's a catch: some of the SDK's APIs themselves still depend on the shims. So by setting the <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions">"multiprocess" permission</a>, your add-on might not work, even if you are only using high-level APIs. For example:</p> - -<pre class="brush: js">var selection = require("sdk/selection"); - -function myListener() { - console.log(selection.text); -} - -selection.on('select', myListener); -</pre> - -<p>This add-on will not work if you've set the <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions">"multiprocess" permission</a>, because <code><a href="/en-US/Add-ons/SDK/High-Level_APIs/selection">sdk/selection</a></code> depends on the shims. We're working on fixing these problems: see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1004745">bug 1004745</a> and its dependencies.</p> - -<h2 id="使用框架脚本">使用框架脚本</h2> - -<p>If the shims don't enable your add-on to work properly, or you're trying to remove your dependency on the shims, then the solution is the same as it is for all add-ons:</p> - -<ul> - <li>factor the code that needs access to content objects into frame scripts</li> - <li>use the message manager to load the frame scripts into the content process</li> - <li>use the message manager to exchange messages with the frame scripts</li> -</ul> - -<p>In the rest of this section we'll outline some SDK-specific details of using the message manager. However, you'll also need to read the main <a href="/en-US/Firefox/Multiprocess_Firefox/The_message_manager">message manager documentation</a> for the details on working with frame scripts.</p> - -<div class="note"> -<p>If you're used to working with content scripts in the SDK, then frame scripts might feel similar, but they're actually very different. Frame scripts are more like a part of the main add-on code that just happens to be running in the content process.</p> - -<p>Differences between frame scripts and content scripts include:</p> - -<ul> - <li>the <a href="/en-US/Firefox/Multiprocess_Firefox/Frame_script_environment">environment for frame scripts</a> and the <a href="/en-US/Add-ons/SDK/Guides/Two_Types_of_Scripts#API_Access_for_Add-on_Code_and_Content_Scripts">environment for content scripts</a> are totally different: - - <ul> - <li>content scripts have a very similar environment to scripts loaded by web pages, plus the <code><a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/self">self</a></code> global.</li> - <li>frame scripts also have access to web content, but have a different set of APIs for communicating with the chrome process, and access to the <a href="/en-US/docs/Components_object">Components object</a>, which enables them to use privileged <a href="/en-US/docs/Mozilla/Tech/XPCOM">XPCOM</a> APIs and load <a href="/en-US/docs/Mozilla/JavaScript_code_modules">JSMs</a>.</li> - </ul> - </li> - <li>content scripts are reloaded when a new document is loaded. Frame scripts aren't: once a frame script is loaded into a tab it remains loaded until the tab is closed. For more details, see the article on <a href="/en-US/Firefox/Multiprocess_Firefox/Message_Manager/Frame_script_loading_and_lifetime">frame script lifetime</a>.</li> -</ul> -</div> - -<h3 id="访问消息管理器">访问消息管理器</h3> - -<h4 id="全局消息管理器">全局消息管理器</h4> - -<p>To access the <a href="/en-US/Firefox/Multiprocess_Firefox/Message_Manager/Message_manager_overview#Global_frame_message_manager">global message manager</a>, you load the <a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIMessageListenerManager">nsIMessageListenerManager</a> service. Before you can do this in an SDK add-on, you have to <code>require("chrome")</code> to get access to the <code><a href="/en-US/docs/Components_object">Components</a></code> object:</p> - -<pre class="brush: js">const {Cc, Ci} = require("chrome"); - -var globalMM = Cc["@mozilla.org/globalmessagemanager;1"] - .getService(Ci.nsIMessageListenerManager);</pre> - -<h4 id="窗口消息管理器">窗口消息管理器</h4> - -<p>The <a href="/en-US/Firefox/Multiprocess_Firefox/Message_Manager/Message_manager_overview#Window_message_manager">window message manager</a> is available as the <code>messageManager</code> property of a chrome window. To understand what a chrome window is, you need to distinguish three sorts of windows:</p> - -<ul> - <li>a content window is the <a href="/en-US/docs/Web/API/Window">Window</a> object familiar to Web developers as the global object for JavaScript loaded from an HTML document. This is the same window that content scripts in the SDK access.</li> - <li>a chrome window, also called a browser window. This is a Firefox application window, hosting the Firefox UI as well as a collection of tabs, each of which can in turn host a DOM window to display web content. This is the global for traditional overlay-based add-ons. In the SDK, the low-level <a href="/en-US/Add-ons/SDK/Low-Level_APIs/window_utils">window/utils</a> module works with these sorts of windows.</li> - <li>an SDK window, as made available by the high level <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows">windows</a> module. Each SDK window maps to a chrome window, but omits most of the chrome window's properties, including <code>messageManager</code>. If you have an SDK window you can convert it to a chrome window using <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#Converting_to_chrome_windows">viewFor</a>.</li> -</ul> - -<p>So to get a window message manager from the SDK, you have a couple of options:</p> - -<p>(1) Use the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/window_utils">window/utils</a> module:</p> - -<pre class="brush: js">// Note that although this code uses window/utils, -// it's safe to run in the chrome process because -// it only accesses chrome objects. - -// get the active chrome window -var browserWindow = require("sdk/window/utils").getMostRecentBrowserWindow(); - -var windowMM = browserWindow.messageManager;</pre> - -<p>(2) Use <code>viewFor</code> to convert an SDK window to a chrome window:</p> - -<pre class="brush: js">// get the active SDK window -var windows = require("sdk/windows").browserWindows; -var activeWindow = windows.activeWindow; - -// convert it to a chrome window -var browserWindow = require("sdk/view/core").viewFor(activeWindow); - -var windowMM = browserWindow.messageManager;</pre> - -<h4 id="浏览器消息管理器">浏览器消息管理器</h4> - -<p>The <a href="/en-US/Firefox/Multiprocess_Firefox/Message_Manager/Message_manager_overview#Browser_message_manager">browser message manager</a> is available as the <code>messageManager</code> property of an XUL <code><a href="/en-US/docs/XUL/browser">browser</a></code>.</p> - -<p>In the SDK, to get a <code>browser</code> for a given tab, you can use the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/tabs_utils">tabs/utils</a> module's <code><a href="/en-US/Add-ons/SDK/Low-Level_APIs/tabs_utils#getBrowserForTab%28tab%29">getBrowserForTab</a></code> function. <code>getBrowserForTab</code> expects an XUL tab as an argument, so if you have an <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs">SDK tab</a> object, you'll need to convert it to an XUL tab using <code><a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#Converting_to_XUL_tabs">viewFor</a></code>:</p> - -<pre class="brush: js">// get the active SDK tab -var tab = require("sdk/tabs").activeTab; -// convert it to an XUL tab -var xulTab = require("sdk/view/core").viewFor(tab); -// get the XUL browser for this tab -var xulBrowser = require("sdk/tabs/utils").getBrowserForTab(xulTab); - -var browserMM = xulBrowser.messageManager;</pre> - -<p>Again, although this code uses tabs/utils, it's safe to run in the chrome process because it only accesses chrome objects.</p> - -<h3 id="载入框架脚本">载入框架脚本</h3> - -<p>You can load frame scripts using the message manager, passing in a chrome:// or resource:// URL pointing to the script. With the SDK, the simplest approach is to keep frame scripts under your add-on's data directory, and pass in a resource:// URL created using <a href="/en-US/Add-ons/SDK/High-Level_APIs/self#data.url(name)">self.data.url</a>:</p> - -<pre class="brush: js">const self = require("sdk/self"); - -messageManager.loadFrameScript(self.data.url("frame-script.js"), false);</pre> - -<p>Note that unlike the APIs to load content scripts, you can only load a single frame script here.</p> - -<h3 id="例子">例子</h3> - -<p>For example, this add-on trivially accesses content directly using a low-level API:</p> - -<pre class="brush: js">function logContent() { - var contentDocument = require("sdk/window/utils") - .getMostRecentBrowserWindow().content.document; - console.log(contentDocument.body.innerHTML); -} - -require("sdk/ui/button/action").ActionButton({ - id: "log-content", - label: "Log Content", - icon: "./icon-16.png", - onClick: logContent -});</pre> - -<p>This add-on will work by default due to the shims, but will break if you set multiprocessCompatible. So you could rewrite the add-on to use frame scripts:</p> - -<pre class="brush: js">/* -frame-script.js is in the "data" directory, and has this content: - -sendAsyncMessage("sdk-low-level-apis-e10s@jetpack:got-content", - content.document.body.innerHTML); - -*/ - -const self = require("sdk/self"); - -function logContentAsync() { - var tab = require("sdk/tabs").activeTab; - var xulTab = require("sdk/view/core").viewFor(tab); - var xulBrowser = require("sdk/tabs/utils").getBrowserForTab(xulTab); - - var browserMM = xulBrowser.messageManager; - browserMM.loadFrameScript(self.data.url("frame-script.js"), false); - browserMM.addMessageListener("sdk-low-level-apis-e10s@jetpack:got-content", - logContent); -} - -function logContent(message) { - console.log(message.data); -} - -require("sdk/ui/button/action").ActionButton({ - id: "log-content", - label: "Log Content", - icon: "./icon-16.png", - onClick: logContentAsync -});</pre> - -<p>现在附加组件能正常工作了，即使你设置了 multiprocessCompatible。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/guides/working_with_events/index.html b/files/zh-cn/mozilla/add-ons/sdk/guides/working_with_events/index.html deleted file mode 100644 index 4c24b84e13..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/guides/working_with_events/index.html +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Working with Events -slug: Mozilla/Add-ons/SDK/Guides/Working_with_Events -translation_of: Archive/Add-ons/Add-on_SDK/Guides/Working_with_Events ---- -<p>The Add-on SDK supports event-driven programming.</p> -<p>Objects emit events on state changes that might be of interest to add-on code, such as browser windows opening, pages loading, network requests completing, and mouse clicks. By registering a listener function to an event emitter an add-on can receive notifications of these events.</p> -<p><span>We talk about content scripts in more detail in the <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Working with Content Scripts</a> guide.</span></p> -<p>Additionally, if you're using content scripts to interact with web content, you can define your own events and use them to communicate between the main add-on code and the content scripts. In this case one end of the conversation emits the events, and the other end listens to them.</p> -<p>So there are two main ways you will interact with the EventEmitter framework:</p> -<ul> - <li> - <p><strong>listening to built-in events</strong> emitted by objects in the SDK, such as tabs opening, pages loading, mouse clicks</p> - </li> - <li> - <p><strong>sending and receiving user-defined events</strong> between content scripts and add-on code</p> - </li> -</ul> -<p>This guide only covers the first of these; the second is explained in the <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Working with Content Scripts</a> guide.</p> -<h2 id="Adding_Listeners">Adding Listeners</h2> -<p>You can add a listener to an event emitter by calling its <code>on(type, listener)</code> method.</p> -<p>It takes two parameters:</p> -<ul> - <li> - <p><strong><code>type</code></strong>: the type of event we are interested in, identified by a string. Many event emitters may emit more than one type of event: for example, a browser window might emit both <code>open</code> and <code>close</code> events. The list of valid event types is specific to an event emitter and is included with its documentation.</p> - </li> - <li> - <p><strong><code>listener</code></strong>: the listener itself. This is a function which will be called whenever the event occurs. The arguments that will be passed to the listener are specific to an event type and are documented with the event emitter.</p> - </li> -</ul> -<p>For example, the following add-on registers a listener with the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> module to listen for the <code>ready</code> event, and logs a string to the console reporting the event:</p> -<pre class="brush: js">var tabs = require("sdk/tabs"); - -tabs.on("ready", function () { - console.log("tab loaded"); -}); -</pre> -<p>It is not possible to enumerate the set of listeners for a given event.</p> -<p>The value of <code>this</code> in the listener function is the object that emitted the event.</p> -<h3 id="Listening_to_all_events">Listening to all events</h3> -<div class="note"> - <p>This example uses the <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> API, which is only available from Firefox 29 onwards.</p> -</div> -<p>From Firefox 28 onwards, you can pass the wildcard "*" as the <code>type</code> argument. If you do this, the listener will be called for any event emitted by that object, and its argument will be the name of the event:</p> -<pre class="brush: js">var ui = require('sdk/ui'); -var panels = require("sdk/panel"); -var self = require("sdk/self"); - -var panel = panels.Panel({ - contentURL: self.data.url("panel.html") -}); - -panel.on("*", function(e) { - console.log("event " + e + " was emitted"); -}); - -var button = ui.ActionButton({ - id: "my-button", - label: "my button", - icon: "./icon-16.png", - onClick: handleClick -}); - -function handleClick(state) { - panel.show({ - position: button - }); -}</pre> -<p>This wildcard feature does not yet work for the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> or <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows"><code>windows</code></a> modules.</p> -<h3 id="Adding_Listeners_in_Constructors">Adding Listeners in Constructors</h3> -<p>Event emitters may be modules, as is the case for the <code>ready</code> event above, or they may be objects returned by constructors.</p> -<p>In the latter case the <code>options</code> object passed to the constructor typically defines properties whose names are the names of supported event types prefixed with "on": for example, "onOpen", "onReady" and so on. Then in the constructor you can assign a listener function to this property as an alternative to calling the object's <code>on()</code> method.</p> -<p>For example: the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action"><code>ActionButton</code></a> object emits an event when the button is clicked.</p> -<p>The following add-on creates a button and assigns a listener to the <code>onClick</code> property of the <code>options</code> object supplied to the button's constructor. The listener loads https://developer.mozilla.org/:</p> -<pre class="brush: js">require("sdk/ui/button/action").ActionButton({ - id: "visit-mozilla", - label: "Visit Mozilla", - icon: "./icon-16.png", - onClick: function() { - require("sdk/tabs").open("https://developer.mozilla.org/"); - } -}); -</pre> -<p>This is exactly equivalent to constructing the button and then calling the button's <code>on()</code> method:</p> -<pre class="brush: js">var button = require("sdk/ui/button/action").ActionButton({ - id: "visit-mozilla", - label: "Visit Mozilla", - icon: "./icon-16.png" -}); - -button.on("click", function() { - require("sdk/tabs").open("https://developer.mozilla.org/"); -}); -</pre> -<h2 id="Removing_Event_Listeners">Removing Event Listeners</h2> -<p>Event listeners can be removed by calling <code>removeListener(type, listener)</code>, supplying the type of event and the listener to remove.</p> -<p>The listener must have been previously been added using one of the methods described above.</p> -<p>In the following add-on, we add two listeners to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#ready"><code>tabs</code> module's <code>ready</code> event</a>. One of the handler functions removes the listener again.</p> -<p>Then we open two tabs.</p> -<pre class="brush: js">var tabs = require("sdk/tabs"); - -function listener1() { - console.log("Listener 1"); - tabs.removeListener("ready", listener1); -} - -function listener2() { - console.log("Listener 2"); -} - -tabs.on("ready", listener1); -tabs.on("ready", listener2); - -tabs.open("https://www.mozilla.org"); -tabs.open("https://www.mozilla.org"); -</pre> -<p>We should see output like this:</p> -<pre>info: tabevents: Listener 1 -info: tabevents: Listener 2 -info: tabevents: Listener 2 -</pre> -<p>Listeners will be removed automatically when the add-on is unloaded.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/base64/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/base64/index.html deleted file mode 100644 index bbde3e418f..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/base64/index.html +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: base64 -slug: Mozilla/Add-ons/SDK/High-Level_APIs/base64 -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/base64 ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>不稳定</p> -</div> - -<p>使用Base64算法编码和解码数据</p> - -<pre class="brush: js">var base64 = require("sdk/base64"); - -var encodedData = base64.encode("Hello, World");//"SGVsbG8sIFdvcmxk" -var decodedData = base64.decode(encodedData);//"Hello, World"</pre> - -<h2 id="Globals">Globals</h2> - -<h3 id="函数">函数</h3> - -<h4 class="addon-sdk-api-name" id="encode(data_charset)"><code>encode(data, charset)</code></h4> - -<p>将数据编码成ASCII的Base64字符串。</p> - -<h5 id="参数">参数</h5> - -<p><strong>data : string</strong><br> - 需要被编码的字符串</p> - -<p><strong>charset : string</strong><br> - 字符串的编码字符集（可选）。唯一能接受的值<code>“UTF-8”</code>。为了进行编码和解码Unicode字符串，需要设置字符集参数：</p> - -<pre class="brush: js">var base64 = require("sdk/base64"); - -var encodedData = base64.encode(unicodeString, "utf-8"); -</pre> - -<h5 id="返回">返回</h5> - -<p><strong>string</strong> : 编码后的Base64字符串。</p> - -<h4 class="addon-sdk-api-name" id="decode(data_charset)"><code>decode(data, charset)</code></h4> - -<p>解码一个已使用base-64编码的数据字符串</p> - -<h5 id="参数_2">参数</h5> - -<p><strong>data : string</strong><br> - 需要被解码的字符串</p> - -<p><strong>charset : string</strong><br> - 字符串的编码字符集（可选）。唯一能接受的值<code>“UTF-8”</code>。为了进行编码和解码Unicode字符串，需要设置字符集参数：</p> - -<pre class="brush: js">var base64 = require("sdk/base64"); - -var decodedData = base64.decode(encodedData, "utf-8"); -</pre> - -<h5 id="返回_2">返回</h5> - -<p><strong>string</strong> : 解码后的字符串</p> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/clipboard/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/clipboard/index.html deleted file mode 100644 index e56a9223cd..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/clipboard/index.html +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: clipboard（剪贴板） -slug: Mozilla/Add-ons/SDK/High-Level_APIs/clipboard -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/clipboard ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>稳定版</p> -</div> - -<p><span class="seoSummary">操作系统剪贴板，设置或获取其内容</span></p> - -<h2 id="用法">用法</h2> - -<p>你可以选择性地设置将要获取或设置的内容的格式. 支持一下格式:</p> - -<ul> - <li><code>text</code> (纯文本)</li> - <li><code>html</code> (HTML标记语言)</li> - <li><code>image</code> (经过base-64编码过的png图片)</li> -</ul> - -<p>如果没有提供格式参数的话，剪贴板模块会自动检测。</p> - -<p>现在在Windows操作系统下，"image"格式并不支持透明度。</p> - -<h3 id="示例">示例</h3> - -<p>设置和获取剪贴板内容。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); -clipboard.set("Lorem ipsum dolor sit amet"); -var contents = clipboard.get();</pre> - -<p>将剪贴板内容设置为某些html。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); -clipboard.set("<blink>Lorem ipsum dolor sit amet</blink>", "html");</pre> - -<p>如果剪贴板内容中包含有html，则将其在新标签页中打开。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); -if (clipboard.currentFlavors.indexOf("html") != -1) - require("sdk/tabs").open("data:text/html;charset=utf-8," + clipboard.get("html"));</pre> - -<p>将剪贴板内容设置为一幅图片。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); -clipboard.set("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYA" + - "AABzenr0AAAASUlEQVRYhe3O0QkAIAwD0eyqe3Q993AQ3cBSUKpygfsNTy" + - "N5ugbQpK0BAADgP0BRDWXWlwEAAAAAgPsA3rzDaAAAAHgPcGrpgAnzQ2FG" + - "bWRR9AAAAABJRU5ErkJggg%3D%3D");</pre> - -<p>如果剪贴板内容中包含图片，则将其在新标签页中打开。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); -if (clipboard.currentFlavors.indexOf("image") != -1) - require("sdk/tabs").open(clipboard.get());</pre> - -<p>如前所述，图片的参数类型很容易被忽略，例如在网页中选中复制一张图片，得到的格式会是html而不是所预期的image。如果你是想将剪贴板的内容设置成像data URL这样的文本字符串而不是图片的话，可以通过将格式设置为text实现。</p> - -<pre class="brush: js">var clipboard = require("sdk/clipboard"); - -clipboard.set("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYA" + - "AABzenr0AAAASUlEQVRYhe3O0QkAIAwD0eyqe3Q993AQ3cBSUKpygfsNTy" + - "N5ugbQpK0BAADgP0BRDWXWlwEAAAAAgPsA3rzDaAAAAHgPcGrpgAnzQ2FG" + - "bWRR9AAAAABJRU5ErkJggg%3D%3D", "text");</pre> - -<h2 id="Globals">Globals</h2> - -<h3 id="函数">函数</h3> - -<h4 class="addon-sdk-api-name" id="set(data_datatype)"><code>set(data, datatype)</code></h4> - -<p>将用户剪贴板上的内容用data替换。</p> - -<h5 id="参数">参数</h5> - -<p><strong>data : string</strong><br> - 要放入剪贴板的内容。</p> - -<p><strong>datatype : string</strong><br> - 内容的格式 ，为"text"或"html" 或 "image"。可选参数.</p> - -<h4 class="addon-sdk-api-name" id="get(datatype)"><code>get(datatype)</code></h4> - -<p>获取用户当前剪贴板的内容。</p> - -<h5 id="参数_2">参数</h5> - -<p><strong>datatype : string</strong><br> - 只有当剪贴板中的内容格式为datatype指定的格式时才获取 (可选).。当剪贴板中的内容非所提供的datatype指定的格式时，函数回返回null。</p> - -<h3 id="属性">属性</h3> - -<h4 class="addon-sdk-api-name" id="currentFlavors"><code>currentFlavors</code></h4> - -<p>剪贴板上的内容有时会是多种格式。例如，HTML内容即能匹配HTML格式(html)，又能匹配纯文本格式(text)。这个属性为一个数组，数组中的元素是剪贴板内容所匹配的所有格式，如["text","html"]。</p> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/index.html deleted file mode 100644 index d0d7bd569a..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/index.html +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: High-Level APIs -slug: Mozilla/Add-ons/SDK/High-Level_APIs -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs ---- -<p>{{AddonSidebar}}</p> - -<p>此页面列出的模块使用的是高级的API：创建用户界面，与网络进行交互并与浏览器交互。</p> - -<p>除非文件明确说明，否则这些API是稳定的，我们避免做出不兼容的改变。 - -{{ LandingPageListSubpages ("/en-US/Add-ons/SDK/High-Level_APIs", 5) }}</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/notifications/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/notifications/index.html deleted file mode 100644 index 415450dca7..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/notifications/index.html +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: notifications（通知） -slug: Mozilla/Add-ons/SDK/High-Level_APIs/notifications -tags: - - Add-on SDK - - 通知 -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/notifications ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>Stable</p> -</div> - -<p><span class="seoSummary">向用户展示短暂的 <a href="http://en.wikipedia.org/wiki/Toast_%28computing%29">toaster</a> 风格的桌面消息。</span></p> - -<h2 id="用法">用法</h2> - -<p>本 API 支持Windows、使用<a href="http://growl.info/">Growl</a>(或者像OS X 10.9 Mavericks那样的通知中心)的 OS X 的桌面通知，以及使用 libnotify 的Linux系统</p> - -<p>这儿有个典型的例子。当消息被点击，控制台上回记录一个字符串。</p> - -<pre class="brush: js">var notifications = require("sdk/notifications"); -notifications.notify({ - title: "Jabberwocky", - text: "'Twas brillig, and the slithy toves", - data: "did gyre and gimble in the wabe", - onClick: function (data) { - console.log(data); - // console.log(this.data) would produce the same result. - } -}); -</pre> - -<p>下面这个示例用来展示一个保存在 add-on 的 <code>data</code> 目录下的图标。参看 <a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a> 模块文档以获取更多信息。</p> - -<pre class="brush: js">var notifications = require("sdk/notifications"); -var self = require("sdk/self"); -var myIconURL = self.data.url("myIcon.png"); - -notifications.notify({ - text: "I have an icon!", - iconURL: myIconURL -});</pre> - -<div class="note"> -<p>从 Firefox 34 起，你能使用 <code>"./myIcon.png"</code> 作为 <code>self.data.url("myIcon.png")</code> 的别名。所以你也可以把上面的代码重写成这样：</p> - -<pre class="brush: js">var notifications = require("sdk/notifications"); -var myIconURL = "./myIcon.png"; - -notifications.notify({ - text: "I have an icon!", - iconURL: myIconURL -});</pre> -</div> - -<p>本模块依赖于底层系统的通知服务。如果用户的系统不支持桌面通知或者通知服务没有运行：</p> - -<ul> - <li>如果 Firefox 正常运行，通知会记录在 Firefox 的错误控制台</li> - <li>如果用户从命令行启动 Firefox，通知会记录到终端。</li> -</ul> - -<h2 id="Globals">Globals</h2> - -<h3 id="函数">函数</h3> - -<h4 class="addon-sdk-api-name" id="notify(options)"><code>notify(options)</code></h4> - -<p>向用户展示一个短暂的通知</p> - -<h5 id="参数">参数</h5> - -<p><strong>options : object</strong><br> - 可选项：</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>title</td> - <td>string</td> - <td> - <p>作为消息标题的字符串。</p> - </td> - </tr> - <tr> - <td>text</td> - <td>作为消息体的字符串。</td> - <td> - <p> </p> - </td> - </tr> - <tr> - <td>iconURL</td> - <td>string</td> - <td> - <p>消息里的图标的 URL 。可以是个远程的、本地的或者使用 <a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a> 模块的 URL。</p> - </td> - </tr> - <tr> - <td>onClick</td> - <td>function</td> - <td> - <p>用户点击消息是调用的函数。它会传递一个 <code>data</code> 值。</p> - </td> - </tr> - <tr> - <td>data</td> - <td>string</td> - <td> - <p>传递给 <code>onClick</code> 的字符串。</p> - </td> - </tr> - </tbody> -</table> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/panel/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/panel/index.html deleted file mode 100644 index 3a86fb0c61..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/panel/index.html +++ /dev/null @@ -1,899 +0,0 @@ ---- -title: panel -slug: Mozilla/Add-ons/SDK/High-Level_APIs/panel -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/panel ---- -<div class="note"> -<p>稳定版本</p> -</div> - -<p><span class="seoSummary">创建临时的 add-on's 用户界面对话框.</span></p> - -<h2 id="用法">用法</h2> - -<p>该模块导出了一个单独的构造函数函数 <code>Panel()</code> 构建一个Panel对话框 .</p> - -<p>面板是一个对话框。其内容是指定的HTML，你可以在它执行脚本，所以面板的外观和行为是有限的只有你可以使用HTML，CSS，JavaScript。</p> - -<p>下面的截图显示了一个面板，其内容是从当前打开的选项卡的列表中构建的：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6595/panel-tabs-osx.png" style="display: block; height: 238px; margin-left: auto; margin-right: auto; width: 307px;"></p> - -<p>面板是呈现临时用户界面中容易忽视和解聘的用户比模态对话框的方式，是有用的，因为面板隐藏瞬间用户交互部分的应用程序接口外。</p> - -<p><br> - 面板的内容加载快作为它是创建，面板显示之前，和内容仍然加载时面板是隐藏的，所以它是可能保持面板周围的背景，更新其内容适当地准备下一次显示。</p> - -<p><br> - 您的插件可以接收通知，当面板显示或隐藏通过听其显示和隐藏事件。<br> - 打开面板将关闭已打开的面板。</p> - -<h3 id="Panel_内容">Panel 内容</h3> - -<p>该面板的内容指定为HTML，它是在contenturl选项面板的构造函数提供的URL加载。</p> - -<p><br> - 你可以加载远程HTML到面板：</p> - -<pre class="brush: js">var panel = require("sdk/panel").Panel({ - width: 180, - height: 180, - contentURL: "https://en.wikipedia.org/w/index.php?title=Jetpack&useformat=mobile" -}); - -panel.show();</pre> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6597/wikipedia-jetpack-panel.png" style="display: block; height: 411px; margin-left: auto; margin-right: auto; width: 494px;"></p> - -<p>你也可以加载HTML已经打包你的 add-on，这可能是你将如何创建对话框。要做到这一点，在你的 add-on 的 <em><strong>data </strong></em>目录中保存的HTML 和加载使用 <strong><em><code>data.url()</code></em></strong>方法，由 <em><strong><a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a></strong></em> 模块导出, 像下面:</p> - -<pre class="brush: js">var panel = require("sdk/panel").Panel({ - contentURL: require("sdk/self").data.url("myFile.html") -}); - -panel.show();</pre> - -<div class="note"> -<p>从Firefox 34以后, 你可以使用 <code>"./myFile.html" 作为</code><code>self.data.url("myFile.html")</code> 的<code>别名</code>. 所以你可以重写成下面的示例:</p> - -<pre class="brush: js">var panel = require("sdk/panel").Panel({ - contentURL: "./myFile.html" -}); - -panel.show(); -</pre> -</div> - -<h3 id="Panel_positioning">Panel positioning</h3> - -<p>By default the panel appears in the center of the currently active browser window. You can position the panel by passing a <code>position</code> to the panel's <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#Panel(options)">constructor</a> or to its <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#show(options)"><code>show()</code></a> method.</p> - -<h3 id="Attaching_panels_to_buttons">Attaching panels to buttons</h3> - -<p>You can attach a panel to a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">toggle button</a> by passing the button itself as the <code>position</code> option to the panel's <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#show(options)"><code>show()</code></a> method or to its constructor:</p> - -<pre class="brush: js">var { ToggleButton } = require('sdk/ui/button/toggle'); -var panels = require("sdk/panel"); -var self = require("sdk/self"); - -var button = ToggleButton({ - id: "my-button", - label: "my button", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onChange: handleChange -}); - -var panel = panels.Panel({ - contentURL: self.data.url("panel.html"), - onHide: handleHide -}); - -function handleChange(state) { - if (state.checked) { - panel.show({ - position: button - }); - } -} - -function handleHide() { - button.state('window', {checked: false}); -}</pre> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7615/panel-button.png" style="display: block; height: 332px; margin-left: auto; margin-right: auto; width: 397px;"></p> - -<h3 id="Updating_panel_content">Updating panel content</h3> - -<p>You can update the panel's content by:</p> - -<ul> - <li>sending a message to a content script that updates the DOM in the same document. This is usually the best approach.</li> - <li>embedding an <a href="/en-US/docs/Web/HTML/Element/iframe">iframe</a> in the panel, and changing its document</li> - <li>setting the panel's <code>contentURL</code> property. However, doing this will cause any content scripts to be unloaded and then reloaded, so it may be less efficient, and you'll lose any state associated with the scripts.</li> -</ul> - -<h3 id="Scripting_panel_content">Scripting panel content</h3> - -<p>You can't directly access your panel's content from your main add-on code. To access the panel's content, you need to load a script into the panel. In the SDK these scripts are called "content scripts" because they're explicitly used for interacting with web content.</p> - -<p>While content scripts can access the content they're attached to, they can't use the SDK's APIs. So implementing a complete solution usually means you have to send messages between the content script and the main add-on code.</p> - -<ul> - <li> - <p>You can specify one or more content scripts to load into a panel using the <code>contentScript</code> or <code>contentScriptFile</code> options to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#Panel(options)"><code>Panel()</code> constructor</a>.</p> - </li> - <li> - <p>You can communicate with the script using either the <a href="/en-US/Add-ons/SDK/Guides/using_postMessage"><code>postMessage()</code></a> API or (preferably, usually) the <a href="/en-US/Add-ons/SDK/Guides/using_port"><code>port</code></a> API.</p> - </li> -</ul> - -<p>For example, here's an add-on whose content script intercepts mouse clicks on links inside the panel, and sends the target URL to the main add-on code. The content script sends messages using <code>self.port.emit()</code> and the add-on script receives them using <code>panel.port.on()</code>.</p> - -<pre class="brush: js">var myScript = "window.addEventListener('click', function(event) {" + - " var t = event.target;" + - " if (t.nodeName == 'A')" + - " self.port.emit('click-link', t.toString());" + - "}, false);" - -var panel = require("sdk/panel").Panel({ - contentURL: "http://www.bbc.co.uk/mobile/index.html", - contentScript: myScript -}); - -panel.port.on("click-link", function(url) { - console.log(url); -}); - -panel.show();</pre> - -<p>This example uses <code>contentScript</code> to supply the script as a string. It's usually better practice to use <code>contentScriptFile</code>, which is a URL pointing to a script file saved under your add-on's <code>data</code> directory.</p> - -<div class="warning"> -<p><strong>Warning:</strong> Unless your content script is extremely simple and consists only of a static string, don't use <code>contentScript</code>: if you do, you may have problems getting your add-on approved on AMO.</p> - -<p>Instead, keep the script in a separate file and load it using <code>contentScriptFile</code>. This makes your code easier to maintain, secure, debug and review.</p> -</div> - -<h3 id="Getting_user_input">Getting user input</h3> - -<div class="note"> -<p><strong>Note:</strong> This example uses the <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> API, which is only available from Firefox 29 onwards.</p> -</div> - -<p>The following add-on adds a button which displays a panel when clicked. The panel just contains a {{HTMLElement("textarea")}} element: when the user presses the <code>return</code> key, the contents of the <code><textarea></code> is sent to the main add-on code.</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7647/panel.png" style="display: block; margin-left: auto; margin-right: auto;"></p> - -<p>The add-on consists of six files:</p> - -<ul> - <li><code>main.js</code>: the main add-on code, that creates the button and panel</li> - <li><code>get-text.js</code>: the content script that interacts with the panel content</li> - <li><code>text-entry.html</code>: the panel content itself, specified as HTML</li> - <li><code>icon-16.png</code>, <code>icon-32.png</code>, and <code>icon-64.png</code>: icons for the button in three different sizes</li> -</ul> - -<p>"main.js" is saved in your add-on's <code>lib</code> directory, and the other files go in your add-on's <code>data</code> directory:</p> - -<pre>my-addon/ - data/ - get-text.js - icon-16.png - icon-32.png - icon-64.png - text-entry.html - lib/ - main.js -</pre> - -<p>The "main.js" looks like this:</p> - -<pre class="brush: js">var data = require("sdk/self").data; -// Construct a panel, loading its content from the "text-entry.html" -// file in the "data" directory, and loading the "get-text.js" script -// into it. -var text_entry = require("sdk/panel").Panel({ - contentURL: data.url("text-entry.html"), - contentScriptFile: data.url("get-text.js") -}); - -// Create a button -require("sdk/ui/button/action").ActionButton({ - id: "show-panel", - label: "Show Panel", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -// Show the panel when the user clicks the button. -function handleClick(state) { - text_entry.show(); -} - -// When the panel is displayed it generated an event called -// "show": we will listen for that event and when it happens, -// send our own "show" event to the panel's script, so the -// script can prepare the panel for display. -text_entry.on("show", function() { - text_entry.port.emit("show"); -}); - -// Listen for messages called "text-entered" coming from -// the content script. The message payload is the text the user -// entered. -// In this implementation we'll just log the text to the console. -text_entry.port.on("text-entered", function (text) { - console.log(text); - text_entry.hide(); -});</pre> - -<p>The content script "get-text.js" looks like this:</p> - -<pre class="brush: js">// When the user hits return, send the "text-entered" -// message to main.js. -// The message payload is the contents of the edit box. -var textArea = document.getElementById("edit-box"); -textArea.addEventListener('keyup', function onkeyup(event) { - if (event.keyCode == 13) { - // Remove the newline. - text = textArea.value.replace(/(\r\n|\n|\r)/gm,""); - self.port.emit("text-entered", text); - textArea.value = ''; - } -}, false); -// Listen for the "show" event being sent from the -// main add-on code. It means that the panel's about -// to be shown. -// -// Set the focus to the text area so the user can -// just start typing. -self.port.on("show", function onShow() { - textArea.focus(); -});</pre> - -<p>Finally, the "text-entry.html" file defines the <code><textarea></code> element:<code> </code></p> - -<pre class="brush: html"><html> -<head> - <style type="text/css" media="all"> - textarea { - margin: 10px; - } - body { - background-color: gray; - } - </style> - </head> -<body> - <textarea rows="13" cols="33" id="edit-box"></textarea> - </body> -</html></pre> - -<p>Finally, save these three icon files to the "data" directory:</p> - -<table class="standard-table"> - <tbody> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7635/icon-16.png" style="height: 16px; width: 16px;"></td> - <td>icon-16.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7637/icon-32.png" style="height: 32px; width: 32px;"></td> - <td>icon-32.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7639/icon-64.png" style="height: 64px; width: 64px;"></td> - <td>icon-64.png</td> - </tr> - </tbody> -</table> - -<p>To learn much more about content scripts, see the <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Working with Content Scripts</a> guide.</p> - -<h3 id="Scripting_trusted_panel_content">Scripting trusted panel content</h3> - -<div class="note"> -<p><strong>Note:</strong> This example uses the <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> API, which is only available from Firefox 29 onwards.</p> -</div> - -<p>We've already seen that you can package HTML files in your add-on's <code>data</code> directory and use them to define the panel's content. We can call this "trusted" content, because unlike content loaded from a source outside the add-on, the add-on author knows exactly what it's doing. To interact with trusted content you don't need to use content scripts: you can just include a script from the HTML file in the normal way, using <code>script</code> tags.</p> - -<p>Like a content script, these scripts can communicate with the add-on code using the <a href="/en-US/Add-ons/SDK/Guides/using_postMessage"><code>postMessage()</code></a> API or the <a href="/en-US/Add-ons/SDK/Guides/using_port"><code>port</code></a> API. The crucial difference is that these scripts access the <code>postMessage</code> and <code>port</code> objects through the <code>addon</code> object, whereas content scripts access them through the <code>self</code> object.</p> - -<p>To show the difference, we can easily convert the <code>text-entry</code> add-on above to use normal page scripts instead of content scripts.</p> - -<p>The main add-on code is exactly the same as the main add-on code in the previous example, except that we don't attach a content script:</p> - -<pre class="brush: js">var data = require("sdk/self").data; -// Construct a panel, loading its content from the "text-entry.html" -// file in the "data" directory, and loading the "get-text.js" script -// into it. -var text_entry = require("sdk/panel").Panel({ - contentURL: data.url("text-entry.html") -}); - -// Create a button -require("sdk/ui/button/action").ActionButton({ - id: "show-panel", - label: "Show Panel", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -// Show the panel when the user clicks the button. -function handleClick(state) { - text_entry.show(); -} - -// When the panel is displayed it generated an event called -// "show": we will listen for that event and when it happens, -// send our own "show" event to the panel's script, so the -// script can prepare the panel for display. -text_entry.on("show", function() { - text_entry.port.emit("show"); -}); - -// Listen for messages called "text-entered" coming from -// the content script. The message payload is the text the user -// entered. -// In this implementation we'll just log the text to the console. -text_entry.port.on("text-entered", function (text) { - console.log(text); - text_entry.hide(); -});</pre> - -<p>The page script is exactly the same as the content script above, except that instead of <code>self</code>, we use <code>addon</code> to access the messaging APIs:</p> - -<pre class="brush: js">// When the user hits return, send the "text-entered" -// message to main.js. -// The message payload is the contents of the edit box. -var textArea = document.getElementById("edit-box"); -textArea.addEventListener('keyup', function onkeyup(event) { - if (event.keyCode == 13) { - // Remove the newline. - text = textArea.value.replace(/(\r\n|\n|\r)/gm,""); - addon.port.emit("text-entered", text); - textArea.value = ''; - } -}, false); -// Listen for the "show" event being sent from the -// main add-on code. It means that the panel's about -// to be shown. -// -// Set the focus to the text area so the user can -// just start typing. -addon.port.on("show", function onShow() { - textArea.focus(); -});</pre> - -<p>Finally, the HTML file now references "get-text.js" inside a {{HTMLElement("script")}} tag:</p> - -<pre class="brush: html"><html> -<head> - <style type="text/css" media="all"> - textarea { - margin: 10px; - } - body { - background-color: gray; - } - </style> - </head> - <body> - <script src="get-text.js"></script> - <textarea rows="13" cols="33" id="edit-box"></textarea> - </body> -</html> -</pre> - -<h3 id="Styling_panel_content">Styling panel content</h3> - -<p>The panel's default style is different for each operating system:</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/8001/panel-styles-os.png" style="display: block; margin-left: auto; margin-right: auto;">This helps to ensure that the panel's style is consistent with the dialogs displayed by Firefox and other applications, but means you need to take care when applying your own styles.</p> - -<p>If the panel's content is packaged along with your add-on and specified using an HTML file in your <code>data</code> directory, you can style it by embedding CSS directly in the HTML file or by referencing a CSS file stored under <code>data</code>:</p> - -<pre class="brush: html"><!DOCTYPE HTML> -<html> - <head> - <link href="panel-style.css" type="text/css" rel="stylesheet"> - </head> - <body> - My panel content - </body> -</html></pre> - -<p>From Firefox 31 onwards, you can style panel content using the <code>contentStyle</code> or <code>contentStyleFile</code> options. You can use these options even if the panel content is not packaged along with the add-on:</p> - -<pre class="brush: js">var panel = require("sdk/panel").Panel({ - contentURL: "https://en.wikipedia.org/w/index.php?title=Jetpack&useformat=mobile", - contentStyle: "body { border: 3px solid blue; }" -}); - -panel.show();</pre> - -<pre class="brush: js">var self = require("sdk/self"); - -var panel = require("sdk/panel").Panel({ - contentURL: "https://en.wikipedia.org/w/index.php?title=Jetpack&useformat=mobile", - contentStyleFile: self.data.url("panel-style.css") -}); - -panel.show();</pre> - -<h3 id="Private_browsing">Private browsing</h3> - -<p>If your add-on has not <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing">opted into private browsing</a>, and it calls <code>panel.show()</code> when the currently active window is a <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing#Per-window_private_browsing">private window</a>, then the panel will not be shown.</p> - -<h3 id="Panel_limitations">Panel limitations</h3> - -<p>Although panels can host HTML documents, they are not implemented as browser tabs, so many things that work in normal web pages do not work inside panels:</p> - -<ul> - <li>Prior to Firefox 33, you don't get a context menu. From Firefox 33 you can enable a context menu by passing <code>contextMenu: true</code> to the panel's constructor.</li> - <li>The HTML {{HTMLElement("select")}} element doesn't work.</li> - <li>The HTML {{HTMLElement("datalist")}} element doesn't give you autocomplete suggestions (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=918600">bug 918600</a>).</li> - <li>You can't embed Flash (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=952578">bug 952578</a>).</li> - <li>You can't provide tooltips using <a href="/en-US/docs/Web/HTML/Global_attributes#attr-title"><code>title</code> attributes</a> (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=918600">bug 918600</a>).</li> - <li>Security warning pages (the <a href="https://support.mozilla.org/en-US/kb/connection-untrusted-error-message">"This Connection is Untrusted" warning</a>) does not work, so panels which trigger it will be broken (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1031554">bug 1031554</a>).</li> - <li>Mouse button shortcuts, such as using the middle button to open a link in a new page, don't work.</li> - <li>Scrolling using keyboard doesn't work properly (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1001914">bug 1001914</a>)</li> -</ul> - -<h2 id="Globals">Globals</h2> - -<h3 id="Constructors">Constructors</h3> - -<h4 class="addon-sdk-api-name" id="Panel(options)"><code>Panel(options)</code></h4> - -<p>Creates a panel.</p> - -<h5 id="Parameters">Parameters</h5> - -<p><strong>options : object</strong><br> - Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td><code>width</code></td> - <td>number</td> - <td> - <p>The width of the panel in pixels. Optional.</p> - </td> - </tr> - <tr> - <td><code>height</code></td> - <td>number</td> - <td> - <p>The height of the panel in pixels. Optional.</p> - </td> - </tr> - <tr> - <td><code>position</code></td> - <td> - <p>object, button, widget</p> - </td> - <td> - <p>The position of the panel. Ignored if the panel is opened by a widget.</p> - - <p>This may be one of three things:</p> - - <ul> - <li>a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">toggle button</a>. If this is supplied the panel will be shown attached to the button. See the section on <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#Attaching_panels_to_buttons">attaching panels to buttons</a>.</li> - <li>a <a href="/en-US/Add-ons/SDK/High-Level_APIs/widget">widget</a> object. If this is supplied the panel will be shown attached to the widget.</li> - <li>an object which specifies where in the window the panel should be shown. The rest of this section describes this object.</li> - </ul> - - <p>The position object has one or more of the following properties: <code>top</code>, <code>right</code>, <code>bottom</code> and <code>left</code>. Their values are expressed in pixels. Any other properties will be ignored.</p> - - <p>The default alignment along each axis is centered: so to display a panel centred along the vertical or horizontal axis, just omit that axis:</p> - - <pre class="brush: js"> -// Show the panel centered horizontally and -// aligned to the bottom of the content area -require("sdk/panel").Panel({ - position: { - bottom: 0 - } -}).show(); - -// Show the panel centered vertically and -// aligned to the left of the content area -require("sdk/panel").Panel({ - position: { - left: 0 - } -}).show(); - -// Centered panel, default behavior -require("sdk/panel").Panel({}).show();</pre> - - <p>As with the CSS <code>top</code>, <code>bottom</code>, <code>left</code>, and <code>right</code> properties, setting both <code>top</code> and <code>bottom</code> or both <code>left</code> and <code>right</code> will implicitly set the panel's <code>height</code> or <code>width</code> relative to the content window:</p> - - <pre class="brush: js"> -// Show the panel centered horizontally, with: -// - the top edge 40px from the top -// of the content window -// - the bottom edge 100px from the bottom -// of the content window -require("sdk/panel").Panel({ - position: { - top: 40, - bottom: 100 - } -}).show();</pre> - - <p>If you set both <code>top</code> and <code>bottom</code>, but also set the panel's height explicitly using the <code>height</code> property, then the panel will ignore <code>bottom</code>, just as CSS does for its properties with the same name:</p> - - <pre class="brush: js"> -// Show the panel centered horizontally, with: -// - the top edge 40px from the top -// of the content window -// - a height of 400px -require("sdk/panel").Panel({ - position: { - top: 40, - bottom: 100, - }, - height: 400 -}).show(); - -// This is equivalent to: - -require("panel").Panel({ - position { - top: 40 - }, - height: 400 -}).show();</pre> - - <p>The same principle is applied in the horizontal axis with <code>width</code>, <code>left</code> and <code>right</code>.</p> - </td> - </tr> - <tr> - <td><code>focus</code></td> - <td>boolean</td> - <td> - <p>Set to <code>false</code> to prevent taking the focus away when the panel is shown. Only turn this off if necessary, to prevent accessibility issue. Optional, default to <code>true</code>.</p> - </td> - </tr> - <tr> - <td><code>contentURL</code></td> - <td>string,URL</td> - <td> - <p>The URL of the content to load in the panel. That is, they can't refer to remote scripts. The URLs are usually constructed using <a href="/en-US/Add-ons/SDK/High-Level_APIs/self#data.url(name)"><code>self.data.url()</code></a>.</p> - - <div class="note"> - <p>From Firefox 34, you can use <code>"./my-file.html"</code> as an alias for <code>self.data.url("my-<code>file.html</code>")</code>.</p> - </div> - </td> - </tr> - <tr> - <td><code>allow</code></td> - <td>object</td> - <td> - <p>An optional object describing permissions for the content. It should contain a single key named <code>script</code> whose value is a boolean that indicates whether or not to execute script in the content. <code>script</code> defaults to true.</p> - </td> - </tr> - <tr> - <td><code>contentScriptFile</code></td> - <td>string,array</td> - <td> - <p>A URL or an array of URLs. The URLs point to scripts to load into the panel.</p> - - <p>The scripts must be packaged with the add-on under the add-on's <code>data</code> directory. That is, they can't refer to remote scripts. The URLs are usually constructed using <a href="/en-US/Add-ons/SDK/High-Level_APIs/self#data.url(name)"><code>self.data.url()</code></a>.</p> - - <div class="note"> - <p>From Firefox 34, you can use <code>"./my-script.js"</code> as an alias for <code>self.data.url("my-script.js")</code>.</p> - </div> - - <p>Content scripts specified by this property are loaded <em>before</em> those specified by the <code>contentScript</code> property.</p> - </td> - </tr> - <tr> - <td><code>contentScript</code></td> - <td>string,array</td> - <td> - <p>A string or an array of strings containing the texts of content scripts to load. Content scripts specified by this property are loaded <em>after</em> those specified by the <code>contentScriptFile</code> property.</p> - </td> - </tr> - <tr> - <td><code>contentStyleFile</code></td> - <td>string, array</td> - <td> - <p>A URL or an array of URLs. The URLs point to CSS stylesheets to load into the panel.</p> - - <p>The stylesheets must be packaged with the add-on under the add-on's <code>data</code> directory. That is, they can't refer to remote stylesheets. The URLs are usually constructed using <a href="/en-US/Add-ons/SDK/High-Level_APIs/self#data.url(name)"><code>self.data.url()</code></a>.</p> - - <p>Stylesheets specified by this property are loaded <em>before</em> those specified by the <code>contentStyle</code> property.</p> - </td> - </tr> - <tr> - <td><code>contentStyle</code></td> - <td>string, array</td> - <td> - <p>A string or an array of strings containing the texts of stylesheets to load. Stylesheets specified by this property are loaded <em>after</em> those specified by the <code>contentStyleFile</code> property.</p> - </td> - </tr> - <tr> - <td><code>contentScriptWhen</code></td> - <td>string</td> - <td> - <p>When to load the content scripts. This may take one of the following values:</p> - - <ul> - <li>"start": load content scripts immediately after the document element for the panel is inserted into the DOM, but before the DOM content itself has been loaded</li> - <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li> - <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the panel has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li> - </ul> - - <p>This property is optional and defaults to "end".</p> - </td> - </tr> - <tr> - <td><code>contentScriptOptions</code></td> - <td>object</td> - <td> - <p>Read-only value exposed to content scripts under <code>addon.options</code> property.</p> - - <p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p> - </td> - </tr> - <tr> - <td><code>contextMenu</code></td> - <td>boolean</td> - <td> - <div class="geckoVersionNote"> - <p>New in Firefox 33</p> - </div> - - <p>Whether to show a context menu when the user context-clicks in the panel. The context menu will be the same one that's displayed in web pages. Optional, defaults to <code>false</code>.</p> - </td> - </tr> - <tr> - <td><code>onMessage</code></td> - <td>function</td> - <td> - <p>Include this to listen to the panel's <code>message</code> event.</p> - </td> - </tr> - <tr> - <td><code>onShow</code></td> - <td>function</td> - <td> - <p>Include this to listen to the panel's <code>show</code> event.</p> - </td> - </tr> - <tr> - <td><code>onHide</code></td> - <td>function</td> - <td> - <p>Include this to listen to the panel's <code>hide</code> event.</p> - </td> - </tr> - </tbody> -</table> - -<h2 id="Panel">Panel</h2> - -<p>The Panel object represents a floating modal dialog that can by an add-on to present user interface content.</p> - -<p>Once a panel object has been created it can be shown and hidden using its <code>show()</code> and <code>hide()</code> methods. Once a panel is no longer needed it can be deactivated using <code>destroy()</code>.</p> - -<p>The content of a panel is specified using the <code>contentURL</code> option. An add-on can interact with the content of a panel using content scripts which it supplies in the <code>contentScript</code> and/or <code>contentScriptFile</code> options. For example, a content script could create a menu and send the user's selection to the add-on.</p> - -<h3 id="Methods">Methods</h3> - -<h4 class="addon-sdk-api-name" id="destroy()"><code>destroy()</code></h4> - -<p>Destroys the panel, unloading any content that was loaded in it. Once destroyed, the panel can no longer be used. If you just want to hide the panel and might show it later, use <code>hide</code> instead.</p> - -<h4 class="addon-sdk-api-name" id="postMessage(message)"><code>postMessage(message)</code></h4> - -<p>Sends a message to the content scripts.</p> - -<h5 id="Parameters_2">Parameters</h5> - -<p><strong>message : value</strong><br> - The message to send. Must be stringifiable to JSON.</p> - -<h4 class="addon-sdk-api-name" id="show(options)"><code>show(options)</code></h4> - -<p>Displays the panel.</p> - -<p>If the <code>options</code> argument is given, it will be shallow merged with the options provided in the constructor: the <code>options</code> passed in the <code>show</code> method takes precedence.</p> - -<p>Passing options here is useful for making temporary changes without touching the default values.</p> - -<h5 id="Parameters_3">Parameters</h5> - -<p><strong>options : object</strong><br> - Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>width</td> - <td>number</td> - <td> - <p>The width of the panel in pixels. Optional.</p> - </td> - </tr> - <tr> - <td>height</td> - <td>number</td> - <td> - <p>The height of the panel in pixels. Optional.</p> - </td> - </tr> - <tr> - <td>position</td> - <td>object</td> - <td> - <p>The position of the panel. Optional. See <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel#Panel(options)">Panel's options</a> for further details.</p> - </td> - </tr> - <tr> - <td>focus</td> - <td>boolean</td> - <td> - <p>Set to <code>false</code> to prevent taking the focus away when the panel is shown.</p> - </td> - </tr> - </tbody> -</table> - -<h4 class="addon-sdk-api-name" id="hide()"><code>hide()</code></h4> - -<p>Stops displaying the panel.</p> - -<h4 class="addon-sdk-api-name" id="resize(width_height)"><code>resize(width, height)</code></h4> - -<p>Resizes the panel.</p> - -<h5 id="Parameters_4">Parameters</h5> - -<p><strong>width : number</strong><br> - The new width of the panel in pixels.</p> - -<p><strong>height : number</strong><br> - The new height of the panel in pixels.</p> - -<h4 class="addon-sdk-api-name" id="on(type_listener)"><code>on(type, listener)</code></h4> - -<p>Registers an event listener with the panel.</p> - -<h5 id="Parameters_5">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event to listen for.</p> - -<p><strong>listener : function</strong><br> - The listener function that handles the event.</p> - -<h4 class="addon-sdk-api-name" id="removeListener(type_listener)"><code>removeListener(type, listener)</code></h4> - -<p>Unregisters an event listener from the panel.</p> - -<h5 id="Parameters_6">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event for which <code>listener</code> was registered.</p> - -<p><strong>listener : function</strong><br> - The listener function that was registered.</p> - -<h3 id="Properties">Properties</h3> - -<h4 class="addon-sdk-api-name" id="port"><code>port</code></h4> - -<p>EventEmitter object that allows you to:</p> - -<ul> - <li>send events to the content script using the <code>port.emit</code> function</li> - <li>receive events from the content script using the <code>port.on</code> function</li> -</ul> - -<p>See the guide to <a href="/en-US/Add-ons/SDK/Guides/using_port"> communicating using <code>port</code></a> for details.</p> - -<h4 class="addon-sdk-api-name" id="isShowing"><code>isShowing</code></h4> - -<p>Tells if the panel is currently shown or not. This property is read-only.</p> - -<h4 class="addon-sdk-api-name" id="height"><code>height</code></h4> - -<p>The height of the panel in pixels.</p> - -<h4 class="addon-sdk-api-name" id="width"><code>width</code></h4> - -<p>The width of the panel in pixels.</p> - -<h4 class="addon-sdk-api-name" id="focus"><code>focus</code></h4> - -<p>Whether or not focus will be taken away when the panel is shown. This property is read-only.</p> - -<h4 class="addon-sdk-api-name" id="contentURL"><code>contentURL</code></h4> - -<p>The URL of content loaded into the panel. This can point to local content loaded from your add-on's "data" directory or remote content. Setting it updates the panel's content immediately.</p> - -<h4 class="addon-sdk-api-name" id="allow"><code>allow</code></h4> - -<p>An object describing permissions for the content. It contains a single key named <code>script</code> whose value is a boolean that indicates whether or not to execute script in the content.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptFile"><code>contentScriptFile</code></h4> - -<p>A local file URL or an array of local file URLs of content scripts to load. Content scripts specified by this property are loaded <em>before</em> those specified by the <code>contentScript</code> property.</p> - -<h4 class="addon-sdk-api-name" id="contentScript"><code>contentScript</code></h4> - -<p>A string or an array of strings containing the texts of content scripts to load. Content scripts specified by this property are loaded <em>after</em> those specified by the <code>contentScriptFile</code> property.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptWhen"><code>contentScriptWhen</code></h4> - -<p>When to load the content scripts. This may have one of the following values:</p> - -<ul> - <li>"start": load content scripts immediately after the document element for the panel is inserted into the DOM, but before the DOM content itself has been loaded</li> - <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li> - <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the panel has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li> -</ul> - -<h4 class="addon-sdk-api-name" id="contentScriptOptions"><code>contentScriptOptions</code></h4> - -<p>Read-only value exposed to content scripts under <code>addon.options</code> property.</p> - -<p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p> - -<h3 id="Events">Events</h3> - -<h4 class="addon-sdk-api-name" id="show"><code>show</code></h4> - -<p>This event is emitted when the panel is shown.</p> - -<h4 class="addon-sdk-api-name" id="hide"><code>hide</code></h4> - -<p>This event is emitted when the panel is hidden.</p> - -<h4 class="addon-sdk-api-name" id="message"><code>message</code></h4> - -<p>If you listen to this event you can receive message events from content scripts associated with this panel. When a content script posts a message using <code>self.postMessage()</code>, the message is delivered to the add-on code in the panel's <code>message</code> event.</p> - -<h5 id="Arguments">Arguments</h5> - -<p><strong>value</strong> : Listeners are passed a single argument which is the message posted from the content script. The message can be any <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port#JSON-Serializable_Values">JSON-serializable value</a>.</p> - -<h4 class="addon-sdk-api-name" id="error"><code>error</code></h4> - -<p>This event is emitted when an uncaught runtime error occurs in one of the panel's content scripts.</p> - -<h5 id="Arguments_2">Arguments</h5> - -<p><strong>Error</strong> : Listeners are passed a single argument, the <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> object.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/tabs/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/tabs/index.html deleted file mode 100644 index b85bb94ab3..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/tabs/index.html +++ /dev/null @@ -1,669 +0,0 @@ ---- -title: tabs -slug: Mozilla/Add-ons/SDK/High-Level_APIs/tabs -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/tabs ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>Stable</p> -</div> - -<p><span class="seoSummary">打开、操作和访问标签页，以及接收标签页事件</span></p> - -<h2 id="用法">用法</h2> - -<h3 id="打开标签页">打开标签页</h3> - -<p>你可以注册事件监听器，以便在标签打开、关闭、完成DOM内容加载、被激活或被闲置时接收通知：</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.open("http://www.example.com");</pre> - -<h3 id="跟踪标签页">跟踪标签页</h3> - -<p>You can register event listeners to be notified when tabs open, close, finish loading DOM content, or are made active or inactive:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); - -// Listen for tab openings. -tabs.on('open', function onOpen(tab) { - myOpenTabs.push(tab); -}); - -// Listen for tab content loads. -tabs.on('ready', function(tab) { - console.log('tab is loaded', tab.title, tab.url); -});</pre> - -<h3 id="访问标签页">访问标签页</h3> - -<p>The module itself can be used as a list of all opened tabs across all windows. In particular, you can enumerate it:</p> - -<pre class="brush: js">var tabs = require('sdk/tabs'); -for (let tab of tabs) - console.log(tab.title);</pre> - -<p>You can also access individual tabs by index:</p> - -<pre class="brush: js">var tabs = require('sdk/tabs'); - -tabs.on('ready', function () { - console.log('first: ' + tabs[0].title); - console.log('last: ' + tabs[tabs.length-1].title); -});</pre> - -<p>You can access the currently active tab:</p> - -<pre class="brush: js">var tabs = require('sdk/tabs'); - -tabs.on('activate', function () { - console.log('active: ' + tabs.activeTab.url); -});</pre> - -<h3 id="跟踪单个标签页">跟踪单个标签页</h3> - -<p>Given a tab, you can register event listeners to be notified when the tab is closed, activated or deactivated, or when the page hosted by the tab is loaded or retrieved from the <a href="https://developer.mozilla.org/en-US/docs/Working_with_BFCache">"back-forward cache"</a>:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); - -function onOpen(tab) { - console.log(tab.url + " is open"); - tab.on("pageshow", logShow); - tab.on("activate", logActivate); - tab.on("deactivate", logDeactivate); - tab.on("close", logClose); -} - -function logShow(tab) { - console.log(tab.url + " is loaded"); -} - -function logActivate(tab) { - console.log(tab.url + " is activated"); -} - -function logDeactivate(tab) { - console.log(tab.url + " is deactivated"); -} - -function logClose(tab) { - console.log(tab.url + " is closed"); -} - -tabs.on('open', onOpen);</pre> - -<h3 id="操作标签页">操作标签页</h3> - -<p>You can get and set various properties of tabs (but note that properties relating to the tab's content, such as the URL, will not contain valid values until after the tab's <code>ready</code> event fires). By setting the <code>url</code> property you can load a new page in the tab:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.on('activate', function(tab) { - tab.url = "http://www.example.com"; -});</pre> - -<h3 id="在标签页中运行脚本">在标签页中运行脚本</h3> - -<p>You can attach a <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">content script</a> to the page hosted in a tab, and use that to access and manipulate the page's content (see the <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">Modifying the Page Hosted by a Tab</a> tutorial):</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); - -tabs.on('activate', function(tab) { - var worker = tab.attach({ - contentScript: 'self.port.emit("html", document.body.innerHTML);' - }); - worker.port.on("html", function(message) { - console.log(message) - }) -});</pre> - -<p>Note that <code>tab.attach</code> is tab-centric: if the user navigates to a new page in the same tab, then the worker and content scripts will be reattached to the new page.</p> - -<h3 id="附加样式表">附加样式表</h3> - -<div class="geckoVersionNote"> -<p>Firefox 34 新增。</p> -</div> - -<p>You can't attach style sheets to a tab using <code>tab.attach()</code>, but from Firefox 34 onwards you can attach and detach them using the low-level <a href="/en-US/Add-ons/SDK/Low-Level_APIs/stylesheet_style">stylesheet/style</a> and <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_mod">content/mod</a> APIs. Here's an add-on that uses a toggle button to attach a stylesheet to the active tab, and detach it again. The stylesheet is called "style.css" and is located in the add-on's "data" directory:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -var { attach, detach } = require('sdk/content/mod'); -var { Style } = require('sdk/stylesheet/style'); -var { ToggleButton } = require("sdk/ui/button/toggle"); - -var style = Style({ - uri: './style.css' -}); - -var button = ToggleButton({ - id: "stylist", - label: "stylist", - icon: "./icon-16.png", - onChange: function(state) { - if (state.checked) { - attach(style, tabs.activeTab); - } - else { - detach(style, tabs.activeTab); - } - } -});</pre> - -<h3 id="隐私窗口">隐私窗口</h3> - -<p>If your add-on has not opted into private browsing, then you won't see any tabs that are hosted by private browser windows.</p> - -<p>Tabs hosted by private browser windows won't be seen if you enumerate the <code>tabs</code> module itself, and you won't receive any events for them.</p> - -<p>To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing">documentation for the <code>private-browsing</code> module</a>.</p> - -<h3 id="转为XUL标签页">转为XUL标签页</h3> - -<p>To convert from the high-level <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#Tab"><code>Tab</code></a> objects used in this API to the low-level <a href="/en-US/docs/Mozilla/Tech/XUL/tab">XUL <code>tab</code></a> objects used in the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/tabs_utils"><code>tabs/utils</code></a> API and by traditional add-ons, use the <code>viewFor()</code> function exported by the <code>viewFor</code> module.</p> - -<p>To convert back the other way, from a XUL <code>tab</code> to a high-level <code>Tab</code> object, use the <code>modelFor()</code> function, exported by the <code>modelFor</code> module.</p> - -<p>Here's an example converting from a high-level <code>Tab</code> to a XUL <code>tab</code> and then back the other way:</p> - -<pre class="brush: js">var { modelFor } = require("sdk/model/core"); -var { viewFor } = require("sdk/view/core"); - -var tabs = require("sdk/tabs"); -var tab_utils = require("sdk/tabs/utils"); - -function mapHighLevelToLowLevel(tab) { - // get the XUL tab that corresponds to this high-level tab - var lowLevelTab = viewFor(tab); - // now we can, for example, access the tab's content directly - var browser = tab_utils.getBrowserForTab(lowLevelTab); - console.log(browser.contentDocument.body.innerHTML); - // get the high-level tab back from the XUL tab - var highLevelTab = modelFor(lowLevelTab); - console.log(highLevelTab.url); -} - -tabs.on("ready", mapHighLevelToLowLevel); -</pre> - -<p>Note that directly accessing XUL objects and web content like this means you're no longer protected by the compatibility guarantees made by the SDK's high-level APIs. In particular, your code might not work with <a href="http://billmccloskey.wordpress.com/2013/12/05/multiprocess-firefox/">multiprocess Firefox</a>.</p> - -<h2 id="全局变量">全局变量</h2> - -<h3 id="函数">函数</h3> - -<h4 class="addon-sdk-api-name" id="open(options)"><code>open(options)</code></h4> - -<p>Opens a new tab. The new tab will open in the active window or in a new window, depending on the <code>inNewWindow</code> option.</p> - -<p><strong>示例</strong></p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); - -// Open a new tab on active window and make tab active. -tabs.open("http://www.mysite.com"); - -// Open a new tab in a new window and make it active. -tabs.open({ - url: "http://www.mysite.com", - inNewWindow: true -}); - -// Open a new tab on active window in the background. -tabs.open({ - url: "http://www.mysite.com", - inBackground: true -}); - -// Open a new tab as an app tab and do something once it's open. -tabs.open({ - url: "http://www.mysite.com", - isPinned: true, - onOpen: function onOpen(tab) { - // do stuff like listen for content - // loading. - } -});</pre> - -<h5 id="参数">参数</h5> - -<p><strong>options : object</strong><br> - 必选项：</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>url</td> - <td>string</td> - <td> - <p>String URL to be opened in the new tab. This is a required property.</p> - </td> - </tr> - </tbody> -</table> - -<p>可选项：</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>isPrivate</td> - <td>boolean</td> - <td> - <p>Boolean which will determine whether the new tab should be private or not. If your add-on does not support private browsing this will have no effect. See the <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing">private-browsing</a> documentation for more information. Defaults to <code>false</code>.</p> - </td> - </tr> - <tr> - <td>inNewWindow</td> - <td>boolean</td> - <td> - <p>If present and true, a new browser window will be opened and the URL will be opened in the first tab in that window. This is an optional property.</p> - </td> - </tr> - <tr> - <td>inBackground</td> - <td>boolean</td> - <td> - <p>If present and true, the new tab will be opened to the right of the active tab and will not be active. This is an optional property.</p> - </td> - </tr> - <tr> - <td>isPinned</td> - <td>boolean</td> - <td> - <p>If present and true, then the new tab will be pinned as an <a href="http://support.mozilla.com/en-US/kb/what-are-app-tabs">app tab</a>.</p> - </td> - </tr> - <tr> - <td>onOpen</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'open' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onClose</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'close' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onReady</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'ready' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onLoad</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'load' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onPageShow</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'pageshow' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onActivate</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'activate' event. This is an optional property.</p> - </td> - </tr> - <tr> - <td>onDeactivate</td> - <td>function</td> - <td> - <p>A callback function that will be registered for the 'deactivate' event. This is an optional property.</p> - </td> - </tr> - </tbody> -</table> - -<h3 id="属性">属性</h3> - -<h4 class="addon-sdk-api-name" id="activeTab"><code>activeTab</code></h4> - -<p>The currently active tab in the active window. This property is read-only. To activate a <code>Tab</code> object, call its <code>activate</code> method.</p> - -<p><strong>示例</strong></p> - -<pre class="brush: js">// Get the active tab's title. -var tabs = require("sdk/tabs"); -console.log("title of active tab is " + tabs.activeTab.title);</pre> - -<h4 class="addon-sdk-api-name" id="length"><code>length</code></h4> - -<p>The number of open tabs across all windows.</p> - -<h3 id="事件">事件</h3> - -<h4 class="addon-sdk-api-name" id="open"><code>open</code></h4> - -<p>This event is emitted when a new tab is opened. This does not mean that the content has loaded, only that the browser tab itself is fully visible to the user.</p> - -<p>Properties relating to the tab's content (for example: <code>title</code>, <code>favicon</code>, and <code>url</code>) will not be correct at this point. If you need to access these properties, listen for the <code>ready</code> event:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.on('open', function(tab){ - tab.on('ready', function(tab){ - console.log(tab.url); - }); -});</pre> - -<h5 id="参数_2">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object that just opened.</p> - -<h4 class="addon-sdk-api-name" id="close"><code>close</code></h4> - -<p>This event is emitted when a tab is closed. When a window is closed this event will be emitted for each of the open tabs in that window.</p> - -<h5 id="参数_3">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object that has closed.</p> - -<h4 class="addon-sdk-api-name" id="ready"><code>ready</code></h4> - -<p>This event is emitted when the DOM for a tab's content is ready. It is equivalent to the <code>DOMContentLoaded</code> event for the given content page.</p> - -<p>A single tab will emit this event every time the DOM is loaded: so it will be emitted again if the tab's location changes or the content is reloaded.</p> - -<p>After this event has been emitted, all properties relating to the tab's content can be used.</p> - -<h5 id="参数_4">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object that has loaded.</p> - -<h4 class="addon-sdk-api-name" id="activate"><code>activate</code></h4> - -<p>This event is emitted when an inactive tab is made active.</p> - -<h5 id="参数_5">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object that has become active.</p> - -<h4 class="addon-sdk-api-name" id="deactivate"><code>deactivate</code></h4> - -<p>This event is emitted when the active tab is made inactive.</p> - -<h5 id="参数_6">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object that has become inactive.</p> - -<h2 id="Tab">Tab</h2> - -<p>A <code>Tab</code> instance represents a single open tab. It contains various tab properties, several methods for manipulation, as well as per-tab event registration.</p> - -<p>Tabs emit all the events described in the Events section. Listeners are passed the <code>Tab</code> object that triggered the event.</p> - -<h3 id="方法">方法</h3> - -<h4 class="addon-sdk-api-name" id="pin()"><code>pin()</code></h4> - -<p>Pins this tab as an <a href="http://support.mozilla.com/en-US/kb/what-are-app-tabs">app tab</a>.</p> - -<h4 class="addon-sdk-api-name" id="unpin()"><code>unpin()</code></h4> - -<p>Unpins this tab.</p> - -<h4 class="addon-sdk-api-name" id="close(callback)"><code>close(callback)</code></h4> - -<p>Closes this tab.</p> - -<h5 id="参数_7">参数</h5> - -<p><strong>callback : function</strong><br> - A function to be called when the tab finishes its closing process. This is an optional argument.</p> - -<h4 class="addon-sdk-api-name" id="reload()"><code>reload()</code></h4> - -<p>Reloads this tab.</p> - -<h4 class="addon-sdk-api-name" id="activate()"><code>activate()</code></h4> - -<p>Makes this tab active, which will bring this tab to the foreground.</p> - -<h4 class="addon-sdk-api-name" id="getThumbnail()"><code>getThumbnail()</code></h4> - -<p>Returns thumbnail data URI of the page currently loaded in this tab.</p> - -<h4 class="addon-sdk-api-name" id="attach(options)"><code>attach(options)</code></h4> - -<p>Attach one or more scripts to the document loaded in the tab. Note that by attaching inside <em>ready</em> event, this becomes tab-centric: if the user navigates to a new page in the same tab, then the content scripts will be reattached to the new page.</p> - -<p><strong>示例</strong></p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); - -tabs.on('ready', function(tab) { - var worker = tab.attach({ - contentScript: - 'document.body.style.border = "5px solid red";' - }); -});</pre> - -<h5 id="参数_8">参数</h5> - -<p><strong>options : object</strong><br> - 可选项:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>contentScriptFile</td> - <td>string,array</td> - <td> - <p>The local file URLs of content scripts to load. Content scripts specified by this option are loaded <em>before</em> those specified by the <code>contentScript</code> option. Optional.</p> - </td> - </tr> - <tr> - <td>contentScript</td> - <td>string,array</td> - <td> - <p>A string or an array of strings of code to be evaluated in the context. Content scripts specified by this option are loaded <em>after</em> those specified by the <code>contentScriptFile</code> option. Optional.</p> - </td> - </tr> - <tr> - <td>contentScriptOptions</td> - <td>object</td> - <td> - <p>You can use this option to define read-only values for your content scripts.</p> - - <p>The option consists of an object literal listing <code>name:value</code> pairs for the values you want to provide to the content script. For example:</p> - - <pre class="brush: js"> -// main.js - -const tabs = require("sdk/tabs"); - -tabs.open({ - url: "./page.html", - onReady: function(tab) { - tab.attach({ - contentScriptFile: "./content-script.js", - contentScriptOptions: { - a: "blah" - } - }); - } -});</pre> - - <p>The values are accessible to content scripts via the <code>self.options</code> property:</p> - - <pre class="brush: js"> -// content-script.js - -alert(self.options.a);</pre> - </td> - </tr> - <tr> - <td>onMessage</td> - <td>function</td> - <td> - <p>A function called when the content worker receives a message from content scripts. Listeners are passed a single argument, the message posted from the content script. Optional.</p> - </td> - </tr> - <tr> - <td>onError</td> - <td>function</td> - <td>A function called when the content worker receives an error from content scripts. Listeners are passed a single argument, <code>error</code>, which is the error posted from the content script and an object of type <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>. Optional</td> - </tr> - </tbody> -</table> - -<h5 id="返回">返回</h5> - -<p><strong>Worker</strong> : <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker">Worker</a> 对象能够用来和内容脚本通信。查看 <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Content Scripts guide</a> 了解详细信息。</p> - -<h3 id="属性_2">属性</h3> - -<h4 class="addon-sdk-api-name" id="id"><code>id</code></h4> - -<p>The unique id for the tab. This property is read-only.</p> - -<h4 class="addon-sdk-api-name" id="title"><code>title</code></h4> - -<p>The title of the tab (usually the title of the page currently loaded in the tab) This property can be set to change the tab title.</p> - -<h4 class="addon-sdk-api-name" id="url"><code>url</code></h4> - -<p>The URL of the page currently loaded in the tab. This property can be set to load a different URL in the tab.</p> - -<h4 class="addon-sdk-api-name" id="favicon"><code>favicon</code></h4> - -<p>The URL of the favicon for the page currently loaded in the tab. This property is read-only.</p> - -<div class="warning">This property is deprecated. From version 1.15, use the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_favicon">favicon module's <code>getFavicon()</code></a> function instead.</div> - -<h4 class="addon-sdk-api-name" id="contentType"><code>contentType</code></h4> - -<div class="note"> -<p><strong>This is currently an experimental API, so we might change it in future releases.</strong></p> - -<p>Returns the MIME type that the document currently loaded in the tab is being rendered as. This may come from HTTP headers or other sources of MIME information, and might be affected by automatic type conversions performed by either the browser or extensions. This property is read-only.</p> -</div> - -<h4 class="addon-sdk-api-name" id="index"><code>index</code></h4> - -<p>The index of the tab relative to other tabs in the application window. This property can be set to change its relative position.</p> - -<h4 class="addon-sdk-api-name" id="isPinned"><code>isPinned</code></h4> - -<p>Whether or not this tab is pinned as an <a href="http://support.mozilla.com/en-US/kb/what-are-app-tabs">app tab</a>. This property is read-only.</p> - -<h4 class="addon-sdk-api-name" id="window"><code>window</code></h4> - -<p><code>标签页的</code><a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow"><code>window</code></a>对象.</p> - -<h4 class="addon-sdk-api-name" id="readyState"><code>readyState</code></h4> - -<div class="geckoVersionNote"> -<p>Firefox 33 新增。</p> -</div> - -<p>A string telling you the load state of the document hosted by this tab. This corresponds directly to <a href="/en-US/docs/Web/API/document.readyState"><code>Document.readyState</code></a>. It has one of four possible values:</p> - -<ul> - <li>"uninitialized": the tab's document is not yet loading</li> - <li>"loading": the tab's document is still in the process of loading</li> - <li>"interactive": the tab's document has loaded and is parsed, but resources such as images and stylesheets may still be loading</li> - <li>"complete": the tab's document and all resources are fully loaded</li> -</ul> - -<p>Once a tab's <code>readyState</code> has entered "interactive", you can retrieve properties such as the document's URL.</p> - -<h3 id="事件_2">事件</h3> - -<h4 class="addon-sdk-api-name" id="close_2"><code>close</code></h4> - -<p>This event is emitted when the tab is closed. It's also emitted when the tab's window is closed.</p> - -<h5 id="参数_9">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> - -<h4 class="addon-sdk-api-name" id="ready_2"><code>ready</code></h4> - -<p>This event is emitted when the DOM for the tab's content is ready. It is equivalent to the <a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/DOMContentLoaded"><code>DOMContentLoaded</code></a> event for the given content page. At this point the document itself is fully loaded and parsed, but resources such as stylesheets and images may still be loading.</p> - -<p>A single tab will emit this event every time the DOM is loaded: so it will be emitted again if the tab's location changes or the content is reloaded. After this event has been emitted, all properties relating to the tab's content can be used.</p> - -<h5 id="参数_10">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> - -<h4 class="addon-sdk-api-name" id="load"><code>load</code></h4> - -<p>This event is emitted when the page for the tab's content is loaded. It is equivalent to the <a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/load"><code>load</code></a> event for the given content page. At this point the document and its resources, such as images and stylesheets, have finished loading.</p> - -<p>This event can be used for pages that do not have a <code>DOMContentLoaded</code> event, like images. For pages that have a <code>DOMContentLoaded</code> event, <code>load</code> is fired after <code>ready</code>.</p> - -<p>A single tab will emit this event every time the page is loaded: so it will be emitted again if the tab's location changes or the content is reloaded. After this event has been emitted, all properties relating to the tab's content can be used.</p> - -<h5 id="参数_11">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> - -<h4 class="addon-sdk-api-name" id="pageshow"><code>pageshow</code></h4> - -<p>The <code>pageshow</code> event is emitted when the page for a tab's content is loaded. It is equivalent to the <a href="https://developer.mozilla.org/en-US/docs/DOM/Mozilla_event_reference/pageshow"><code>pageshow</code></a> event for the given content page.</p> - -<p>This event is similar to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#load"><code>load</code></a> and <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#ready"><code>ready</code></a> events, except unlike <code>load</code> and <code>ready</code>, <code>pageshow</code> is triggered if the page was retrieved from the <a href="https://developer.mozilla.org/en-US/docs/Working_with_BFCache">bfcache</a>. This means that if the user loads a page, loads a new page, then moves back to the previous page using the "Back" button, the <code>pageshow</code> event is emitted when the user moves back to the previous page, while the <code>load</code> and <code>ready</code> events are not.</p> - -<p>This event is <em>not</em> emitted when the tab is made the active tab: to get notified about that, you need to listen to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#activate"><code>activate</code></a> event.</p> - -<p>After this event has been emitted, all properties relating to the tab's content can be used. It is emitted after <code>load</code> and <code>ready</code>.</p> - -<h5 id="参数_12">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> - -<p><strong>persisted</strong> : Listeners are passed a boolean value indicating whether or not the page was loaded from the <a href="https://developer.mozilla.org/en-US/docs/Working_with_BFCache">bfcache</a>.</p> - -<h4 class="addon-sdk-api-name" id="activate_2"><code>activate</code></h4> - -<p>This event is emitted when the tab is made active.</p> - -<p>Note that you cannot guarantee that a tab's content, or even its <code>url</code>, are initialized at the time <code>activate</code> is emitted. This is because when a new tab is opened, its <code>activate</code> event may be emitted before the content is loaded.</p> - -<p>You can use the tab's <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#readyState"><code>readyState</code></a> property to determine whether the tab's content and <code>url</code> will be available: if <code>readyState</code> is <code>uninitialized</code> or <code>loading</code>, then you can't access the tab's properties and must wait for the tab's <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#ready_2"><code>ready</code></a> event.</p> - -<h5 id="参数_13">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> - -<h4 class="addon-sdk-api-name" id="deactivate_2"><code>deactivate</code></h4> - -<p>This event is emitted when the tab is made inactive.</p> - -<h5 id="参数_14">参数</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/url/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/url/index.html deleted file mode 100644 index f98da9baf9..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/url/index.html +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: url -slug: Mozilla/Add-ons/SDK/High-Level_APIs/url -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/url ---- -<div class="note"> -<p>实验性的</p> -</div> - -<p><span class="seoSummary">构建，验证，解析URL</span></p> - -<h2 id="Globals">Globals</h2> - -<h3 id="构造函数">构造函数</h3> - -<h4 class="addon-sdk-api-name" id="URL(source_base)"><code>URL(source, base)</code></h4> - -<p>URL构造函数可以创建一个URL对象，并验证提供的字符串是否是有效的URL。SDK中，任何接受URL参数的API，除非特殊说明，均接受的是此对象而不是字符串。</p> - -<h5 id="参数">参数</h5> - -<p><strong>source : string</strong><br> - 一个表示URL的字符串，如果接受的参数不是有效的URL字符串，此构造函数会抛出一个异常。</p> - -<p><strong>base : string</strong><br> - 一个设置的字符串，用来表示一个相对路径的源。</p> - -<h4 class="addon-sdk-api-name" id="DataURL(uri)"><code>DataURL(uri)</code></h4> - -<p>DataURL构造函数创建一个data: URL对象, 并验证提供的字符串是否是一个有效的data: URL。</p> - -<h5 id="参数_2">参数</h5> - -<p><strong>uri : string</strong><br> - 一个表示Data URL的字符串。如果它不是一个合法的URL字符串，此构造函数会抛出一个错误。</p> - -<h3 id="函数">函数</h3> - -<h4 class="addon-sdk-api-name" id="toFilename(url)"><code>toFilename(url)</code></h4> - -<p>尝试将给定的URL转换成本地文件路径。这个方法会自动尝试解决非文件协议, such as the <code>resource:</code> protocol, to their place on the file system. 除非URL无法转换，否则，本方法会将本地路径作为字符串返回。</p> - -<h5 id="参数_3">参数</h5> - -<p><strong>url : string</strong><br> - 字符串格式的URL。</p> - -<h5 id="返回">返回</h5> - -<p><strong>string</strong> : 转换后的本地路径字符串</p> - -<h4 class="addon-sdk-api-name" id="fromFilename(path)"><code>fromFilename(path)</code></h4> - -<p>讲一个给定的路径转换成 <code>file:</code> URL.</p> - -<h5 id="参数_4">参数</h5> - -<p><strong>path : string</strong><br> - 需要被转换的本地文件路径字符串。</p> - -<h5 id="Returns">Returns</h5> - -<p><strong>string</strong> : 转换后的字符串。</p> - -<h4 class="addon-sdk-api-name" id="isValidURI(uri)"><code>isValidURI(uri)</code></h4> - -<p>检查一个URL字符串是合法。 <code>isValidURI("http://mozilla.org")</code> 将返回 <code>true</code>, 而 <code>isValidURI("mozilla.org")</code> 将返回 <code>false</code>。</p> - -<h5 id="参数_5">参数</h5> - -<p><strong>uri : string</strong><br> - 需要被测试的URL。</p> - -<h5 id="Returns_2">Returns</h5> - -<p><strong>boolean</strong> : 代表字符串是否有效的布尔值。</p> - -<h4 class="addon-sdk-api-name" id="getTLD(url)"><code>getTLD(url)</code></h4> - -<p>返回给定域名的顶级域名： 内部使用的是 <a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIEffectiveTLDService#getPublicSuffix()"><code>getPublicSuffix()</code></a> 。</p> - -<pre class="brush: js">var urls = require("sdk/url"); -console.log(urls.getTLD("http://www.bbc.co.uk/")); // "co.uk" -console.log(urls.getTLD("https://developer.mozilla.org/")); // "org"</pre> - -<h5 id="参数_6">参数</h5> - -<p><strong>url : string</strong><br> - 给定的URL字符串</p> - -<h5 id="返回_2">返回</h5> - -<p><strong>string</strong> : 对应的顶级域名。</p> - -<h2 id="URL">URL</h2> - -<h3 id="方法">方法</h3> - -<h4 class="addon-sdk-api-name" id="toString()"><code>toString()</code></h4> - -<p>返回URL的字符表示形式。</p> - -<h5 id="返回_3">返回</h5> - -<p><strong>string</strong> : 字符串格式的URL。</p> - -<h3 id="属性">属性</h3> - -<h4 class="addon-sdk-api-name" id="scheme"><code>scheme</code></h4> - -<p>URL使用的协议</p> - -<h4 class="addon-sdk-api-name" id="userPass"><code>userPass</code></h4> - -<p>URL中的username:password 部分，<code>null</code> 表示不存在。</p> - -<h4 class="addon-sdk-api-name" id="host"><code>host</code></h4> - -<p>URL的主机部分。 <code>null</code> 表示无此部分。例子：</p> - -<pre class="brush: js">var url = require("sdk/url").URL("https://developer.mozilla.org/en-US/Add-ons"); -console.log(url.host); // developer.mozilla.org</pre> - -<h4 class="addon-sdk-api-name" id="port"><code>port</code></h4> - -<p>URL使用的端口。 <code>null</code> 表示不存在。</p> - -<h4 class="addon-sdk-api-name" id="path"><code>path</code></h4> - -<p>URL的路径部分，例子：</p> - -<pre class="brush: js">var url = require("sdk/url").URL("https://developer.mozilla.org/en-US/Add-ons"); -console.log(url.path); // /en-US/Add-ons</pre> - -<h4 class="addon-sdk-api-name" id="hostname"><code>hostname</code></h4> - -<p>表示URL的域的字符串。参见 <a href="/en-US/docs/Web/API/URLUtils.hostname"><code>window.location.hostname</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="pathname"><code>pathname</code></h4> - -<p>从 <code>'/'</code>开始的路径字符串。参见 <a href="/en-US/docs/Web/API/URLUtils.pathname"><code>window.location.pathname</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="hash"><code>hash</code></h4> - -<p>从 <code>'#'</code> 开始的hash字符串，参见 <a href="/en-US/docs/Web/API/URLUtils.hash"><code>window.location.hash</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="href"><code>href</code></h4> - -<p>整个URL字符串，参见 <a href="/en-US/docs/Web/API/URLUtils.href"><code>window.location.href</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="origin"><code>origin</code></h4> - -<p>该URL的源的字符串，参见 <a href="/en-US/docs/Web/API/URLUtils.origin"><code>window.location.origin</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="protocol"><code>protocol</code></h4> - -<p>该URL使用的协议字符串，包括最后的<code>':'，参见</code> <a href="/en-US/docs/Web/API/URLUtils.protocol"><code>window.location.protocol</code></a>。</p> - -<h4 class="addon-sdk-api-name" id="search"><code>search</code></h4> - -<p>以'?'开始的URL的参数段，包括最开始的<code>'?'</code>。 <code>参见</code><a href="/en-US/docs/Web/API/URLUtils.search"><code>window.location.search</code></a>.</p> - -<h2 id="DataURL">DataURL</h2> - -<h3 id="方法_2">方法</h3> - -<h4 class="addon-sdk-api-name" id="toString()_2"><code>toString()</code></h4> - -<p>返回数据的URL字符串形式。如果是 <code>base64</code> 的URL，数据会以base64编码方式编码。</p> - -<h5 id="返回_4">返回</h5> - -<p><strong>string</strong> : URL字符串</p> - -<h3 id="属性_2">属性</h3> - -<h4 class="addon-sdk-api-name" id="mimeType"><code>mimeType</code></h4> - -<p>数据的MIME类型，默认为空字符串。</p> - -<h4 class="addon-sdk-api-name" id="parameters"><code>parameters</code></h4> - -<p>一个HashMap的数据包含URL参数。默认情况下是一个空对象。</p> - -<h4 class="addon-sdk-api-name" id="base64"><code>base64</code></h4> - -<p><span>定义了</span><span>数据</span><span>属性</span><span>值</span><span>的编码。</span></p> - -<h4 class="addon-sdk-api-name" id="data"><code>data</code></h4> - -<p>包含数据的URL字符串。如果<code>URI</code>给构造函数包含<code>Base64</code>参数，这个字符串会被解码。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/widget/index.html b/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/widget/index.html deleted file mode 100644 index 3d374a0752..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/high-level_apis/widget/index.html +++ /dev/null @@ -1,839 +0,0 @@ ---- -title: widget -slug: Mozilla/Add-ons/SDK/High-Level_APIs/widget -tags: - - ZH -translation_of: Archive/Add-ons/Add-on_SDK/High-Level_APIs/widget ---- -<p>{{LegacyAddonsNotice}}{{AddonSidebar}}</p> - -<div class="warning"> -<p>Deprecated in Firefox 29 and removed in Firefox 38.</p> - -<p>The widget API is deprecated from Firefox 29 onwards. Please see the <a href="/en-US/Add-ons/SDK/High-Level_APIs/ui">ui module</a> for replacements. In particular, for a simple button, try the <a href="/en-US/Add-ons/SDK/High-Level_APIs/ui#ActionButton">action button</a> or <a href="/en-US/Add-ons/SDK/High-Level_APIs/ui#ToggleButton">toggle button</a> APIs, and for a more complex widget try the <a href="/en-US/Add-ons/SDK/High-Level_APIs/ui#Toolbar">toolbar</a> or <a href="/en-US/Add-ons/SDK/High-Level_APIs/ui#Sidebar">sidebar</a> APIs.</p> -</div> - -<p><span class="seoSummary">Create a simple user interface for an add-on in Firefox's add-on bar.</span></p> - -<h2 id="Usage">Usage</h2> - -<p>"Widgets" are small pieces of content that live in the Firefox 4 <a href="https://developer.mozilla.org/en/The_add-on_bar">add-on bar</a>. They can be simple icons or complex web pages. You can attach <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panels</a> to them that open when they're clicked, or you can define a custom click handler to perform some other action, like opening a web page in a tab.</p> - -<p>There are a few advantages to using widgets over an ad hoc user interface. First, your users will be accustomed to interacting with add-ons via widgets and the add-on bar. Second, it allows Firefox to treat your interface as a first-class citizen. For example, in the future Firefox may allow the user to drag widgets from the add-on bar to other toolbars. By exposing your interface as a widget, your add-on would automatically inherit such functionality.</p> - -<h3 id="Creation_and_content">Creation and content</h3> - -<p>Widgets can contain images or arbitrary web content. You can include this content inline as a string by using the <code>content</code> property, or point to content using a URL with the <code>contentURL</code> property.</p> - -<p>Upon creation, the widget is automatically added to the add-on bar. You can set the width of a widget, but the height is fixed so as to fit in the add-on bar. If the content is an image, it is automatically scaled to be 16x16 pixels.</p> - -<p>For example, this widget contains an image, so it looks like a simple icon:</p> - -<pre class="brush: js">require("sdk/widget").Widget({ - id: "mozilla-icon", - label: "My Mozilla Widget", - contentURL: "http://www.mozilla.org/favicon.ico" -});</pre> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6695/widget-mozilla.png" style="display: block; height: 184px; margin-left: auto; margin-right: auto; width: 464px;">You can make <code>contentURL</code> point to an HTML or icon file which you have packaged inside your add-on. Just save the file in your add-on's <code>data</code> directory, and reference it using the <code>data.url()</code> method of the <a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a> module:</p> - -<pre class="brush: js">var data = require("sdk/self").data; - -require("sdk/widget").Widget({ - id: "my-widget", - label: "My Widget", - contentURL: data.url("my-content.html") -});</pre> - -<p>This widget contains an entire web page:</p> - -<pre class="brush: js">require("sdk/widget").Widget({ - id: "hello-display", - label: "My Hello Widget", - content: "Hello!", - width: 50 -});</pre> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6605/widget-hello-text.png" style="display: block; height: 132px; margin-left: auto; margin-right: auto; width: 282px;">Widgets are quite small by default, so this example used the <code>width</code> property to grow it in order to show all the text.</p> - -<h3 id="Scripting_widget_content">Scripting widget content</h3> - -<p>To interact with the widget's content you need to load a separate script into the panel. In the SDK these scripts are called "content scripts" because they're explicitly used for interacting with web content.</p> - -<p>While content scripts can access the content they're attached to, they can't use the SDK's APIs. So implementing a complete solution usually means you have to send messages between the content script and the main add-on code.</p> - -<ul> - <li> - <p>You can specify one or more content scripts to load into the widget using the <code>contentScript</code> or <code>contentScriptFile</code> options to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/widget#Widget(options)"><code>Widget()</code> constructor</a>.</p> - </li> - <li> - <p>You can communicate with the script using either the <a href="/en-US/Add-ons/SDK/Guides/using_postMessage"><code>postMessage()</code></a> API or (preferably, usually) the <a href="/en-US/Add-ons/SDK/Guides/using_port"><code>port</code></a> API.</p> - </li> -</ul> - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a static string, don't use <code>contentScript</code>: if you do, you may have problems getting your add-on approved on AMO.</p> - -<p>Instead, keep the script in a separate file and load it using <code>contentScriptFile</code>. This makes your code easier to maintain, secure, debug and review.</p> -</div> - - -<p><img alt="" src="https://mdn.mozillademos.org/files/6607/widget-player-buttons.png" style="float: right; height: 132px; width: 282px;">For example, suppose we want to implement a media player as an add-on. We could implement the main user interface as a widget hosting an array of buttons to control play/pause/stop functions.</p> - -<p>We can then use a content script to listen for clicks on those buttons. But because content scripts can't use the SDK's APIs, we'll want the content script to send messages to the main add-on code, which can then implement the media player functions using the SDK.</p> - -<p>The widget's content is specified using HTML like this:</p> - -<pre class="brush: html"><code class="brush: js"><html> - <body> - <img src="play.png" id="play-button"> - <img src="pause.png" id="pause-button"> - <img src="stop.png" id="stop-button"> - </body> -</html></code></pre> - -<p>We just include three icons, and assign an ID to each one. This HTML file, and the icon files it references, are saved in the add-on's <code>data</code> directory.</p> - -<p>Next, we write a content script that listens for click events on each icon and sends the corresponding message to the main add-on code:</p> - -<pre class="brush: js">var play_button = document.getElementById("play-button"); -play_button.onclick = function() { - self.port.emit("play"); -} - -var pause_button = document.getElementById("pause-button"); -pause_button.onclick = function() { - self.port.emit("pause"); -} - -var stop_button = document.getElementById("stop-button"); -stop_button.onclick = function() { - self.port.emit("stop"); -}</pre> - -<p>We save this file in the add-on's <code>data</code> directory as "button-script.js". Finally. in the add-on's "main.js" file, we create the widget, assign it the HTML file and the content script, and listen for events from the content script:</p> - -<pre class="brush: js">const widgets = require("sdk/widget"); -const data = require("sdk/self").data; - -var player = widgets.Widget({ - id: "player", - width: 72, - label: "Player", - contentURL: data.url("buttons.html"), - contentScriptFile: data.url("button-script.js") -}); - -player.port.on("play", function() { - console.log("playing"); -}); - -player.port.on("pause", function() { - console.log("pausing"); -}); - -player.port.on("stop", function() { - console.log("stopping"); -});</pre> - -<p>To learn much more about content scripts, see the <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Working with Content Scripts</a> guide.</p> - -<h3 id="Scripting_trusted_widget_content">Scripting trusted widget content</h3> - -<p>We've already seen that you can package HTML files in your add-on's <code>data</code> directory and use them to define the widget's content. We can call this "trusted" content, because unlike content loaded from a source outside the add-on, the add-on author knows exactly what it's doing. To interact with trusted content you don't need to use content scripts: you can just include a script from the HTML file in the normal way, using <code>script</code> tags.</p> - -<p>Like a content script, these scripts can communicate with the add-on code using the <a href="/en-US/Add-ons/SDK/Guides/using_postMessage"><code>postMessage()</code></a> API or the <a href="/en-US/Add-ons/SDK/Guides/using_port"><code>port</code></a> API. The crucial difference is that these scripts access the <code>postMessage</code> and <code>port</code> objects through the <code>addon</code> object, whereas content scripts access them through the <code>self</code> object.</p> - -<p>To show the difference, convert the <code>player</code> add-on above to use normal page scripts instead of content scripts.</p> - -<p>First, in the content script, change <code>self</code> to <code>addon</code>, and wrap it in a function:</p> - -<pre class="brush: js">function init() { - var play_button = document.getElementById("play-button"); - play_button.onclick = function() { - addon.port.emit("play"); - } - - var pause_button = document.getElementById("pause-button"); - pause_button.onclick = function() { - addon.port.emit("pause"); - } - - var stop_button = document.getElementById("stop-button"); - stop_button.onclick = function() { - addon.port.emit("stop"); - } -}</pre> - -<p>Next, add a <code>script</code> tag to reference "button-script.js", and call its <code>init()</code> function on load:</p> - -<pre class="brush: html"><html> - <head> - <script src="button-script.js"></script> - </head> - <body onLoad="init()"> - <img src="play.png" id="play-button"> - <img src="pause.png" id="pause-button"> - <img src="stop.png" id="stop-button"> - </body> -</html> -</pre> - -<p>Finally, remove the line attaching the content script from "main.js":</p> - -<pre class="brush: js">const widgets = require("sdk/widget"); -const data = require("sdk/self").data; - -var player = widgets.Widget({ - id: "player", - width: 72, - label: "Player", - contentURL: data.url("buttons.html") -}); - -player.port.emit("init"); - -player.port.on("play", function() { - console.log("playing"); -}); - -player.port.on("pause", function() { - console.log("pausing"); -}); - -player.port.on("stop", function() { - console.log("stopping"); -});</pre> - -<h3 id="Attaching_panels_to_widgets">Attaching panels to widgets</h3> - -<p>You can supply a <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panel</a> to the widget's constructor: if you do this, the panel is automatically displayed when the user clicks the widget.</p> - - -<p><img alt="" src="https://mdn.mozillademos.org/files/6609/widget-panel-clock.png" style="float: right; height: 222px; width: 214px;"></p> - -<pre class="brush: js">data = require("sdk/self").data - -var clockPanel = require("sdk/panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") -}); - -require("sdk/widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png"), - panel: clockPanel -});</pre> - -<p>Note that this is, at the moment, the only way you can attach a panel to a widget.</p> - -<p>You must supply the panel in the widget's constructor for it to work. If you assign the panel to the widget after construction, the panel can still be shown but will not be anchored to the widget:</p> - -<pre class="brush: js">data = require("sdk/self").data - -var clockPanel = require("sdk/panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") -}); - -widget = require("sdk/widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png") -}); - -widget.panel = clockPanel; - -// Will not be anchored -widget.panel.show();</pre> - -<p>Also, if you try to call <code>panel.show()</code> inside your widget's <code>click</code> event listener, the panel will not be anchored:</p> - -<pre class="brush: js">data = require("sdk/self").data - -var clockPanel = require("sdk/panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") -}); - -require("sdk/widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png"), - panel: clockPanel, - onClick: function() { - // Will not be anchored - this.panel.show(); - } -});</pre> - -<p>See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=638142">bug 638142</a>.</p> - -<h3 id="Private_windows">Private windows</h3> - -<p>If your add-on has not opted into private browsing, then your widget will not appear in any private browser windows.</p> - -<p>To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing">documentation for the <code>private-browsing</code> module</a>.</p> - -<h3 id="Examples">Examples</h3> - -<p>For conciseness, these examples create their content scripts as strings and use the <code>contentScript</code> property. In your own add-ons, you will probably want to create your content scripts in separate files and pass their URLs using the <code>contentScriptFile</code> property. See <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Working with Content Scripts</a> for more information.</p> - -<pre class="brush: js">var widgets = require("sdk/widget"); - -// A basic click-able image widget. -widgets.Widget({ - id: "google-link", - label: "Widget with an image and a click handler", - contentURL: "http://www.google.com/favicon.ico", - onClick: function() { - require("sdk/tabs").activeTab.url = "http://www.google.com/"; - } -});</pre> - -<pre class="brush: js">// A widget that changes display on mouseover. -widgets.Widget({ - id: "mouseover-effect", - label: "Widget with changing image on mouseover", - contentURL: "http://www.yahoo.com/favicon.ico", - onMouseover: function() { - this.contentURL = "http://www.bing.com/favicon.ico"; - }, - onMouseout: function() { - this.contentURL = "http://www.yahoo.com/favicon.ico"; - } -});</pre> - -<pre class="brush: js">// A widget that updates content on a timer. -widgets.Widget({ - id: "auto-update-widget", - label: "Widget that updates content on a timer", - content: "0", - contentScript: 'setTimeout(function() {' + - ' document.body.innerHTML++;' + - '}, 2000)', - contentScriptWhen: "ready" -});</pre> - -<pre class="brush: js">// A widget created with a specified width, that grows. -var myWidget = widgets.Widget({ - id: "widget-effect", - label: "Wide widget that grows wider on a timer", - content: "I'm getting longer.", - width: 50, -}); -require("sdk/timers").setInterval(function() { - myWidget.width += 10; -}, 1000);</pre> - -<pre class="brush: js">// A widget communicating bi-directionally with a content script. -var widget = widgets.Widget({ - id: "message-test", - label: "Bi-directional communication!", - content: "<foo>bar</foo>", - contentScriptWhen: "ready", - contentScript: 'self.on("message", function(message) {' + - ' alert("Got message: " + message);' + - '});' + - 'self.postMessage("ready");', - onMessage: function(message) { - if (message == "ready") - widget.postMessage("me too"); - } -});</pre> - -<h2 id="Globals">Globals</h2> - -<h3 id="Constructors">Constructors</h3> - -<h4 class="addon-sdk-api-name" id="Widget(options)"><code>Widget(options)</code></h4> - -<p>Creates a new widget. The widget is immediately added to the add-on bar.</p> - -<h5 id="Parameters">Parameters</h5> - -<p><strong>options : object</strong><br> - Required options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>label</td> - <td>string</td> - <td> - <p>A string description of the widget used for accessibility, title bars, and error reporting.</p> - </td> - </tr> - <tr> - <td>id</td> - <td>string</td> - <td> - <p>A string used to identify your widget in order to save its location when the user moves it in the browser. This string has to be unique and must not be changed over time.</p> - </td> - </tr> - </tbody> -</table> - -<p>Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>content</td> - <td>string</td> - <td> - <p>An optional string value containing the displayed content of the widget. It may contain HTML. Widgets must have either the <code>content</code> property or the <code>contentURL</code> property set.</p> - - <p>If the content is an image, it is automatically scaled to be 16x16 pixels.</p> - </td> - </tr> - <tr> - <td>contentURL</td> - <td>string</td> - <td> - <p>An optional string URL to content to load into the widget. This can be local content or remote content, an image or web content. Widgets must have either the <code>content</code> property or the <code>contentURL</code> property set.</p> - - <p>If the content is an image, it is automatically scaled to be 16x16 pixels.</p> - </td> - </tr> - <tr> - <td>panel</td> - <td>Panel</td> - <td> - <p>An optional <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panel</a> to open when the user clicks on the widget. Note: If you also register a "click" listener, it will be called instead of the panel being opened. However, you can show the panel from the listener by calling <code>this.panel.show()</code>.</p> - </td> - </tr> - <tr> - <td>width</td> - <td>integer</td> - <td> - <p>Optional width in pixels of the widget. If not given, a default width is used.</p> - </td> - </tr> - <tr> - <td>onClick</td> - <td>function</td> - <td> - <p>Include this to listen to the widget's <code>click</code> event.</p> - </td> - </tr> - <tr> - <td>onMessage</td> - <td>function</td> - <td> - <p>Include this to listen to the widget's <code>message</code> event.</p> - </td> - </tr> - <tr> - <td>onMouseover</td> - <td>function</td> - <td> - <p>Include this to listen to the widget's <code>mouseover</code> event.</p> - </td> - </tr> - <tr> - <td>onMouseout</td> - <td>function</td> - <td> - <p>Include this to listen to the widget's <code>mouseout</code> event.</p> - </td> - </tr> - <tr> - <td>onAttach</td> - <td>function</td> - <td> - <p>Include this to listen to the widget's <code>attach</code> event.</p> - </td> - </tr> - <tr> - <td>tooltip</td> - <td>string</td> - <td> - <p>Optional text to show when the user's mouse hovers over the widget. If not given, the <code>label</code> is used.</p> - </td> - </tr> - <tr> - <td>allow</td> - <td>object</td> - <td> - <p>An optional object describing permissions for the content. It should contain a single key named <code>script</code> whose value is a boolean that indicates whether or not to execute script in the content. <code>script</code> defaults to true.</p> - </td> - </tr> - <tr> - <td>contentScriptFile</td> - <td>string,array</td> - <td> - <p>A local file URL or an array of local file URLs of content scripts to load. Content scripts specified by this property are loaded <em>before</em> those specified by the <code>contentScript</code> property.</p> - </td> - </tr> - <tr> - <td>contentScript</td> - <td>string,array</td> - <td> - <p>A string or an array of strings containing the texts of content scripts to load. Content scripts specified by this property are loaded <em>after</em> those specified by the <code>contentScriptFile</code> property.</p> - </td> - </tr> - <tr> - <td>contentScriptWhen</td> - <td>string</td> - <td> - <p>When to load the content scripts. This may take one of the following values:</p> - - <ul> - <li>"start": load content scripts immediately after the document element for the widget is inserted into the DOM, but before the DOM content itself has been loaded</li> - <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li> - <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the widget has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li> - </ul> - - <p>This property is optional and defaults to "end".</p> - </td> - </tr> - <tr> - <td>contentScriptOptions</td> - <td>object</td> - <td> - <p>Read-only value exposed to content scripts under <code>self.options</code> property.</p> - - <p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p> - </td> - </tr> - </tbody> -</table> - -<h2 id="Widget">Widget</h2> - -<p>Represents a widget object.</p> - -<h3 id="Methods">Methods</h3> - -<h4 class="addon-sdk-api-name" id="destroy()"><code>destroy()</code></h4> - -<p>Removes the widget from the add-on bar.</p> - -<h4 class="addon-sdk-api-name" id="postMessage(data)"><code>postMessage(data)</code></h4> - -<p>Sends a message to the widget's content scripts.</p> - -<h5 id="Parameters_2">Parameters</h5> - -<p><strong>data : value</strong><br> - The message to send. The message can be any <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port#JSON-Serializable_Values">JSON-serializable value</a>.</p> - -<h4 class="addon-sdk-api-name" id="on(type_listener)"><code>on(type, listener)</code></h4> - -<p>Registers an event listener with the widget.</p> - -<h5 id="Parameters_3">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event to listen for.</p> - -<p><strong>listener : function</strong><br> - The listener function that handles the event.</p> - -<h4 class="addon-sdk-api-name" id="removeListener(type_listener)"><code>removeListener(type, listener)</code></h4> - -<p>Unregisters an event listener from the widget.</p> - -<h5 id="Parameters_4">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event for which <code>listener</code> was registered.</p> - -<p><strong>listener : function</strong><br> - The listener function that was registered.</p> - -<h4 class="addon-sdk-api-name" id="getView(window)"><code>getView(window)</code></h4> - -<p>Retrieve a <code>WidgetView</code> instance of this widget relative to a browser window.</p> - -<h5 id="Parameters_5">Parameters</h5> - -<p><strong>window : BrowserWindow</strong><br> - The <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow">BrowserWindow</a> instance to match.</p> - -<h5 id="Returns">Returns</h5> - -<p><strong>WidgetView</strong> : A <code>WidgetView</code> instance associated with the browser window. Any changes subsequently applied to this object will only be applied to the widget attached to that window.</p> - -<h3 id="Properties">Properties</h3> - -<h4 class="addon-sdk-api-name" id="label"><code>label</code></h4> - -<p>The widget's label. Read-only.</p> - -<h4 class="addon-sdk-api-name" id="content"><code>content</code></h4> - -<p>A string containing the widget's content. It can contain HTML. Setting it updates the widget's appearance immediately. However, if the widget was created using <code>contentURL</code>, then this property is meaningless, and setting it has no effect.</p> - -<h4 class="addon-sdk-api-name" id="contentURL"><code>contentURL</code></h4> - -<p>The URL of content to load into the widget. This can point to local content loaded from your add-on's "data" directory or remote content, an image or web content. Setting it updates the widget's appearance immediately. However, if the widget was created using <code>content</code>, then this property is meaningless, and setting it has no effect.</p> - -<p>Setting the <code>contentURL</code> property will break the channel of communication between this widget and any content scripts it contains. Messages sent from the content script will no longer be received by the main add-on code, and vice versa. This issue is currently tracked as <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=825434">bug 825434</a>.</p> - -<h4 class="addon-sdk-api-name" id="panel"><code>panel</code></h4> - -<p>A <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panel</a> to open when the user clicks on the widget.</p> - -<h4 class="addon-sdk-api-name" id="width"><code>width</code></h4> - -<p>The widget's width in pixels. Setting it updates the widget's appearance immediately.</p> - -<h4 class="addon-sdk-api-name" id="tooltip"><code>tooltip</code></h4> - -<p>The text of the tooltip that appears when the user hovers over the widget.</p> - -<h4 class="addon-sdk-api-name" id="allow"><code>allow</code></h4> - -<p>A object describing permissions for the content. It contains a single key named <code>script</code> whose value is a boolean that indicates whether or not to execute script in the content.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptFile"><code>contentScriptFile</code></h4> - -<p>A local file URL or an array of local file URLs of content scripts to load.</p> - -<h4 class="addon-sdk-api-name" id="contentScript"><code>contentScript</code></h4> - -<p>A string or an array of strings containing the texts of content scripts to load.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptWhen"><code>contentScriptWhen</code></h4> - -<p>When to load the content scripts. This may have one of the following values:</p> - -<ul> - <li>"start": load content scripts immediately after the document element for the widget is inserted into the DOM, but before the DOM content itself has been loaded</li> - <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li> - <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the widget has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li> -</ul> - -<h4 class="addon-sdk-api-name" id="contentScriptOptions"><code>contentScriptOptions</code></h4> - -<p>Read-only value exposed to content scripts under <code>self.options</code> property.</p> - -<p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p> - -<h4 class="addon-sdk-api-name" id="port"><code>port</code></h4> - -<p>Object that allows you to:</p> - -<ul> - <li>send events to the content script using the <code>port.emit</code> function</li> - <li>receive events from the content script using the <code>port.on</code> function</li> -</ul> - -<p>See the guide to <a href="/en-US/Add-ons/SDK/Guides/using_port"> communicating using <code>port</code></a> for details.</p> - -<h3 id="Events">Events</h3> - -<h4 class="addon-sdk-api-name" id="attach"><code>attach</code></h4> - -<p>This event is emitted when a browser window is opened and a new <code>WidgetView</code> object is created. If the widget has a content script, this event is fired only when the content script is applied according to the <code>contentScriptWhen</code> attribute.</p> - -<h5 id="Arguments">Arguments</h5> - -<p><strong>WidgetView</strong> : The related <code>WidgetView</code> object.</p> - -<h4 class="addon-sdk-api-name" id="click"><code>click</code></h4> - -<p>This event is emitted when the widget is clicked.</p> - -<h5 id="Arguments_2">Arguments</h5> - -<p><strong>WidgetView</strong> : Listeners are passed a single argument which is the <code>WidgetView</code> that triggered the click event.</p> - -<h4 class="addon-sdk-api-name" id="message"><code>message</code></h4> - -<p>If you listen to this event you can receive message events from content scripts associated with this widget. When a content script posts a message using <code>self.postMessage()</code>, the message is delivered to the add-on code in the widget's <code>message</code> event.</p> - -<h5 id="Arguments_3">Arguments</h5> - -<p><strong>value</strong> : Listeners are passed a single argument which is the message posted from the content script. The message can be any <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port#JSON-Serializable_Values">JSON-serializable value</a>.</p> - -<h4 class="addon-sdk-api-name" id="mouseover"><code>mouseover</code></h4> - -<p>This event is emitted when the user moves the mouse over the widget.</p> - -<h4 class="addon-sdk-api-name" id="mouseout"><code>mouseout</code></h4> - -<p>This event is emitted when the user moves the mouse away from the widget.</p> - -<h2 id="WidgetView">WidgetView</h2> - -<p>Represents a widget instance specific to one browser window.</p> - -<p>Anything you do to an instance of this object will only be applied to the instance attached to its browser window: widget instances attached to other browser windows will be unaffected.</p> - -<p>By contrast, any changes you make to an instance of the normal <code>Widget</code> class will be applied across all browser windows.</p> - -<p>This class has all the same methods, attributes and events as the <code>Widget</code> class except for the <code>getView</code> method and the <code>attach</code> event.</p> - -<p>In this example <code>WidgetView</code> is used to display different content for <code>http</code> and <code>https</code> schemes:</p> - -<pre class="brush: js">// A widget that update its content specifically to each window. -var tabs = require("sdk/tabs"); -var windows = require("sdk/windows").browserWindows; -var widget = require("sdk/widget").Widget({ - id: "window-specific-test", - label: "Widget with content specific to each window", - content: " ", - width: 50 -}); -// Observe tab switch or document changes in each existing tab: -function updateWidgetState(tab) { - var view = widget.getView(tab.window); - if (!view) return; - // Update widget displayed text: - view.content = tab.url.match(/^https/) ? "Secured" : "Unsafe"; -} -tabs.on('ready', updateWidgetState); -tabs.on('activate', updateWidgetState);</pre> - -<h3 id="Methods_2">Methods</h3> - -<h4 class="addon-sdk-api-name" id="destroy()_2"><code>destroy()</code></h4> - -<p>Removes the widget view from the add-on bar.</p> - -<h4 class="addon-sdk-api-name" id="postMessage(data)_2"><code>postMessage(data)</code></h4> - -<p>Sends a message to the widget view's content scripts.</p> - -<h5 id="Parameters_6">Parameters</h5> - -<p><strong>data : value</strong><br> - The message to send. The message can be any <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port#JSON-Serializable_Values">JSON-serializable value</a>.</p> - -<h4 class="addon-sdk-api-name" id="on(type_listener)_2"><code>on(type, listener)</code></h4> - -<p>Registers an event listener with the widget view.</p> - -<h5 id="Parameters_7">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event to listen for.</p> - -<p><strong>listener : function</strong><br> - The listener function that handles the event.</p> - -<h4 class="addon-sdk-api-name" id="removeListener(type_listener)_2"><code>removeListener(type, listener)</code></h4> - -<p>Unregisters an event listener from the widget view.</p> - -<h5 id="Parameters_8">Parameters</h5> - -<p><strong>type : string</strong><br> - The type of event for which <code>listener</code> was registered.</p> - -<p><strong>listener : function</strong><br> - The listener function that was registered.</p> - -<h3 id="Properties_2">Properties</h3> - -<h4 class="addon-sdk-api-name" id="label_2"><code>label</code></h4> - -<p>The widget view's label. Read-only.</p> - -<h4 class="addon-sdk-api-name" id="content_2"><code>content</code></h4> - -<p>A string containing the widget view's content. It can contain HTML. Setting it updates the widget view's appearance immediately. However, if the widget view was created using <code>contentURL</code>, then this property is meaningless, and setting it has no effect.</p> - -<h4 class="addon-sdk-api-name" id="contentURL_2"><code>contentURL</code></h4> - -<p>The URL of content to load into the widget. This can point to local content loaded from your add-on's "data" directory or remote content, an image or web content. Setting it updates the widget's appearance immediately. However, if the widget was created using <code>content</code>, then this property is meaningless, and setting it has no effect.</p> - -<p>Setting the <code>contentURL</code> property will break the channel of communication between this widget and any content scripts it contains. Messages sent from the content script will no longer be received by the main add-on code, and vice versa. This issue is currently tracked as <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=825434">bug 825434</a>.</p> - -<h4 class="addon-sdk-api-name" id="panel_2"><code>panel</code></h4> - -<p>A <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">panel</a> to open when the user clicks on the widget view.</p> - -<h4 class="addon-sdk-api-name" id="width_2"><code>width</code></h4> - -<p>The widget view's width in pixels. Setting it updates the widget view's appearance immediately.</p> - -<h4 class="addon-sdk-api-name" id="tooltip_2"><code>tooltip</code></h4> - -<p>The text of the tooltip that appears when the user hovers over the widget view.</p> - -<h4 class="addon-sdk-api-name" id="allow_2"><code>allow</code></h4> - -<p>A object describing permissions for the content. It contains a single key named <code>script</code> whose value is a boolean that indicates whether or not to execute script in the content.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptFile_2"><code>contentScriptFile</code></h4> - -<p>A local file URL or an array of local file URLs of content scripts to load.</p> - -<h4 class="addon-sdk-api-name" id="contentScript_2"><code>contentScript</code></h4> - -<p>A string or an array of strings containing the texts of content scripts to load.</p> - -<h4 class="addon-sdk-api-name" id="contentScriptWhen_2"><code>contentScriptWhen</code></h4> - -<p>When to load the content scripts. This may have one of the following values:</p> - -<ul> - <li>"start": load content scripts immediately after the document element for the widget view is inserted into the DOM, but before the DOM content itself has been loaded</li> - <li>"ready": load content scripts once DOM content has been loaded, corresponding to the <a href="https://developer.mozilla.org/en/Gecko-Specific_DOM_Events">DOMContentLoaded</a> event</li> - <li>"end": load content scripts once all the content (DOM, JS, CSS, images) for the widget view has been loaded, at the time the <a href="https://developer.mozilla.org/en/DOM/window.onload">window.onload event</a> fires</li> -</ul> - -<h4 class="addon-sdk-api-name" id="contentScriptOptions_2"><code>contentScriptOptions</code></h4> - -<p>Read-only value exposed to content scripts under <code>self.options</code> property.</p> - -<p>Any kind of jsonable value (object, array, string, etc.) can be used here. Optional.</p> - -<h4 class="addon-sdk-api-name" id="port_2"><code>port</code></h4> - -<p>Object that allows you to:</p> - -<ul> - <li>send events to the content script using the <code>port.emit</code> function</li> - <li>receive events from the content script using the <code>port.on</code></li> -</ul> - -<p>See the guide to <a href="/en-US/Add-ons/SDK/Guides/using_port"> communicating using <code>port</code></a> for details.</p> - -<h3 id="Events_2">Events</h3> - -<h4 class="addon-sdk-api-name" id="detach"><code>detach</code></h4> - -<p>The <code>detach</code> event is fired when the widget view is removed from its related window. This can occur if the window is closed, Firefox exits, or the add-on is disabled.</p> - -<h4 class="addon-sdk-api-name" id="click_2"><code>click</code></h4> - -<p>This event is emitted when the widget view is clicked.</p> - -<h4 class="addon-sdk-api-name" id="message_2"><code>message</code></h4> - -<p>If you listen to this event you can receive message events from content scripts associated with this widget view. When a content script posts a message using <code>self.postMessage()</code>, the message is delivered to the add-on code in the widget view's <code>message</code> event.</p> - -<h5 id="Arguments_4">Arguments</h5> - -<p><strong>value</strong> : Listeners are passed a single argument which is the message posted from the content script. The message can be any <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/using_port#JSON-Serializable_Values">JSON-serializable value</a>.</p> - -<h4 class="addon-sdk-api-name" id="mouseover_2"><code>mouseover</code></h4> - -<p>This event is emitted when the user moves the mouse over the widget view.</p> - -<h4 class="addon-sdk-api-name" id="mouseout_2"><code>mouseout</code></h4> - -<p>This event is emitted when the user moves the mouse away from the widget view.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/index.html b/files/zh-cn/mozilla/add-ons/sdk/index.html deleted file mode 100644 index 3c6398ed48..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/index.html +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: 附加组件 SDK -slug: Mozilla/Add-ons/SDK -tags: - - More Example - - Need Tanslate - - TopicStub -translation_of: Archive/Add-ons/Add-on_SDK ---- -<div class="warning"> -<p>Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.</p> - -<p>Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use <a href="/en-US/Add-ons/WebExtensions">WebExtensions</a> instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.</p> - -<p><strong>Starting from <a href="https://wiki.mozilla.org/RapidRelease/Calendar">Firefox 53</a>, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.</strong></p> - -<p><strong>Starting from <a href="https://wiki.mozilla.org/RapidRelease/Calendar">Firefox 57</a>, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android. </strong></p> - -<p>Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the <a href="https://blog.mozilla.org/addons/2017/02/16/the-road-to-firefox-57-compatibility-milestones/">"Compatibility Milestones" document</a> for more information.</p> - -<p>A wiki page containing <a href="https://wiki.mozilla.org/Add-ons/developer/communication">resources, migration paths, office hours, and more</a>, is available to help developers transition to the new technologies.</p> -</div> - -<p>你可以使用Add-on SDK来开发Firefox的附加组件。你可以使用各种各样的标准Web技术：JavaScript, HTML和CSS。该SDK不仅包括一些用来创建附加组件的 JavaScript API，还提供了开发、运行、测试、打包附加组件的一些工具。</p> - -<hr> -<h3 id="教程">教程</h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><code><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials#getting-started">快速入门</a></code></dt> - <dd>如何<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/SDK/Tools/jpm">安装SDK</a>并<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_started">使用jpm工具</a>开发、测试、打包附加组件</dd> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials#interact-with-the-browser">与浏览器交互</a></dt> - <dd><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Open_a_Web_Page">打开网页</a>，<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Listen_for_Page_Load">监听页面加载</a>，<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/List_Open_Tabs">列出打开的标签页</a>。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials#development-techniques">开发技术</a></dt> - <dd>学习常用开发技术，如<a href="/zh-CN/Add-ons/SDK/Tutorials/Unit_testing">单元测试</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/Logging">日志</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/Creating_Reusable_Modules">创建可复用模块</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/l10n">本地化</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/Mobile_development">移动开发</a></dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials#create-user-interfaces">创建用户界面组件</a></dt> - <dd>创建用户界面组件如<a href="/zh-CN/Add-ons/SDK/Tutorials/Adding_a_Button_to_the_Toolbar">工具条按钮</a>, <a href="/zh-CN/Add-ons/SDK/Tutorials/Add_a_Context_Menu_Item">上下文菜单</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox">菜单项</a>，<a href="/zh-CN/Add-ons/SDK/Tutorials/Display_a_Popup">对话框</a>。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials#modify-web-pages">修改网页</a></dt> - <dd> - <p>通过<a href="/zh-CN/docs//zh-CN/Add-ons/SDK/Tutorials/Modifying_Web_Pages_Based_on_URL">URL匹配</a>修改页面或者动态<a href="/zh-CN/docs//zh-CN/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">修改某个tab选项卡</a>。</p> - </dd> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Annotator">将其组合在一起</a></dt> - <dd>关于注释器的附加组件的例子演示.</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="指南">指南</h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Guides#contributors-guide"><span class="short_text" id="result_box" lang="zh-CN"><span class="op_dict_text2">贡献者</span><span>指南</span></span></a></dt> - <dd>学习<a href="/zh-CN/Add-ons/SDK/Guides/Getting_Started">如何开始构建</a> SDK和关于SDK最重要的术语, 如 <a href="/zh-CN/Add-ons/SDK/Guides/Modules">模块</a>, <a href="/zh-CN/Add-ons/SDK/Guides/Classes_and_Inheritance"> 类和继承</a>, <a href="/zh-CN/Add-ons/SDK/Guides/Private_Properties">私有属性</a>, <a href="/zh-CN/Add-ons/SDK/Guides/Content_Processes">内容处理</a>.</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Guides#sdk-infrastructure">SDK的基础构建</a></dt> - <dd>SDK的底层技术方面: <a href="/zh-CN/Add-ons/SDK/Guides/Module_structure_of_the_SDK">模块</a>,<a href="/zh-CN/Add-ons/SDK/Guides/Program_ID">程序ID</a>, <a href="/zh-CN/Add-ons/SDK/Guides/Firefox_Compatibility">Firefox 兼容</a>的规则定义.</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Guides/Content_Scripts"><span class="short_text" id="result_box" lang="zh-CN"><span>内容</span><span>脚本</span></span></a></dt> - <dd> - <div class="output-bd" dir="ltr"> - <p class="ordinary-output target-output"><span>一个详细的</span><span>指南</span><span>内容脚本</span></p> - </div> - </dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Guides#sdk-idioms">SDK语法</a></dt> - <dd>SDK的事件框架和插件的脚本和内容脚本之间的区别。</dd> - <dd>SDK的 <a href="/zh-CN/Add-ons/SDK/Guides/Working_with_Events">事件框架</a> 和 <a href="/zh-CN/Add-ons/SDK/Guides/Two_Types_of_Scripts">add-on scripts 和 content scripts 的</a>区别.</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Guides/XUL_Migration_Guide">XUL 迁移</a></dt> - <dd>指导 <a href="/zh-CN/Add-ons/SDK/Guides/XUL_Migration_Guide">移植 XUL add-ons 到 SDK</a>. 本指南包括 <a href="/zh-CN/Add-ons/SDK/Guides/XUL_vs_SDK">两工具</a> 和 一个 <a href="/zh-CN/Add-ons/SDK/Guides/Porting_the_Library_Detector">工作实例</a> 比较 XUL 和 add-on.</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="参考"><span class="short_text" id="result_box" lang="zh-CN"><span>参考</span></span></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/High-Level_APIs">高级API</a></dt> - <dd>高级SDK API的参考文档.</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tools">工具参考</a></dt> - <dd>用于 <a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tools/jpm">jpm工具</a> 开发的参考文档, 测试, 打包add-ons, 全局 <a href="/zh-CN/Add-ons/SDK/Tools/console">控制台</a>记录, 和<a href="/zh-CN/Add-ons/SDK/Tools/package_json">package.json</a> 文件.</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Low-Level_APIs">低级API</a></dt> - <dd>低级SDK API的参考文档.</dd> -</dl> -</div> -</div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/index.html b/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/index.html deleted file mode 100644 index 673c369430..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/index.html +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 低层 API -slug: Mozilla/Add-ons/SDK/Low-Level_APIs -translation_of: Archive/Add-ons/Add-on_SDK/Low-Level_APIs ---- -<p>{{AddonSidebar}}</p> - -<p>本节的模块实现了低层的 API，这些模块大至分为三类：</p> - -<ul> - <li> - <p>基础工具，比如 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/util_collection">collection</a>。很多 add-ons 都有可能使用这个类别的模块。</p> - </li> - <li> - <p>为高层模块构建分块，比如 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/event_core">events</a> 和 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker">worker</a>。你更有可能使用它们构建你自己德尔模块，来扩展 SDK 本身。</p> - </li> - <li> - <p>权限模块，露出强大的低层功能，比如<a href="/en-US/Add-ons/SDK/Low-Level_APIs/window_utils">window/utils</a> 和 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/net_xhr">net/xhr</a>。你可以使用这些模块，但是应该意识到获取访问权限的代价是必须采取更加详尽的预防措施。大部分情况下这些模块在"高层API中"有着简单的更加严格的同类模块。（例如，<a href="/en-US/Add-ons/SDK/High-Level_APIs/windows">windows</a> 或 <a href="/en-US/Add-ons/SDK/High-Level_APIs/request">request</a>）。</p> - </li> -</ul> - -<p>这些模块仍在开发中，我们预期在将来发布的版本中会做出不兼容的变更。</p> - -<p>{{ LandingPageListSubpages ("/zh-CN/Add-ons/SDK/Low-Level_APIs", 5) }}</p> - -<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/test_assert/index.html b/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/test_assert/index.html deleted file mode 100644 index 5f7537ec42..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/test_assert/index.html +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: test/assert -slug: Mozilla/Add-ons/SDK/Low-Level_APIs/test_assert -translation_of: Archive/Add-ons/Add-on_SDK/Low-Level_APIs/test_assert ---- -<p>{{LegacyAddonsNotice}}{{AddonSidebar}}</p> - -<div class="note"> -<p>Unstable</p> -</div> - -<p>实现在 <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification version 1.1</a> 其中定义的断言接口。</p> - -<h2 id="Usage">Usage</h2> - -<p>To use the <code>assert</code> module, write a set of unit tests following the instructions in the <a href="/en-US/Add-ons/SDK/Tutorials/Unit_testing">unit testing tutorial</a>. Each test will be passed an <code>Assert</code> object when you run the tests using <a href="/en-US/Add-ons/SDK/Tools/jpm"><code>jpm test</code></a>. You can use this object to make assertions about your program's state.</p> - -<p>For example:</p> - -<pre class="brush: js">var a = 1; - -exports["test value of a"] = function(assert) { - assert.ok(a == 1, "test that a is 1"); -} - -require("sdk/test").run(exports);</pre> - -<h2 id="Globals">Globals</h2> - -<h3 id="Constructors">Constructors</h3> - -<h4 class="addon-sdk-api-name" id="Assert(logger)"><code>Assert(logger)</code></h4> - -<p>Create a new Assert object. This function is only called by the unit test framework, and not by unit tests themselves.</p> - -<h5 id="Parameters">Parameters</h5> - -<p><strong>logger : object</strong><br> - Object used to log the results of assertions.</p> - -<h2 id="Assert">Assert</h2> - -<p>An object used to make assertions about a program's state in order to implement unit tests.</p> - -<p>The <code>Assert</code> object's interface is defined by the <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification, version 1.1</a>.</p> - -<h3 id="Methods">Methods</h3> - -<h4 class="addon-sdk-api-name" id="ok(guard_message)"><code>ok(guard, message)</code></h4> - -<p>Tests whether an expression evaluates to true.</p> - -<pre class="brush: js">assert.ok(a == 1, "test that a is equal to one");</pre> - -<p>This is equivalent to:</p> - -<pre class="brush: js">assert.equal(a == 1, true, "test that a is equal to one");</pre> - -<h5 id="Parameters_2">Parameters</h5> - -<p><strong>guard : expression</strong><br> - The expression to evaluate.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="equal(actual_expected_message)"><code>equal(actual, expected, message)</code></h4> - -<p>Tests shallow, coercive equality with <code>==</code>:</p> - -<pre class="brush: js">assert.equal(1, 1, "test that one is one");</pre> - -<h5 id="Parameters_3">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="notEqual(actual_expected_message)"><code>notEqual(actual, expected, message)</code></h4> - -<p>Tests that two objects are not equal, using <code>!=</code>:</p> - -<pre class="brush: js">assert.notEqual(1, 2, "test that one is not two");</pre> - -<h5 id="Parameters_4">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="deepEqual(actual_expected_message)"><code>deepEqual(actual, expected, message)</code></h4> - -<p>Tests that two objects have a deep equality relation. Deep equality is defined in the <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.0#Assert">CommonJS specification for Assert</a>, item 7, which is quoted here:</p> - -<div class="quote"> -<ol> - <li>All identical values are equivalent, as determined by ===.</li> - <li>If the expected value is a Date object, the actual value is equivalent if it is also a Date object that refers to the same time.</li> - <li>Other pairs that do not both pass typeof value == "object", equivalence is determined by ==.</li> - <li>For all other Object pairs, including Array objects, equivalence is determined by having the same number of owned properties (as verified with Object.prototype.hasOwnProperty.call), the same set of keys (although not necessarily the same order), equivalent values for every corresponding key, and an identical "prototype" property. Note: this accounts for both named and indexed properties on Arrays.</li> -</ol> -</div> - -<pre class="brush: js">assert.deepEqual({ a: "foo" }, { a: "foo" }, "equivalent objects");</pre> - -<h5 id="Parameters_5">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="notDeepEqual(actual_expected_message)"><code>notDeepEqual(actual, expected, message)</code></h4> - -<p>Tests that two objects do not have a deep equality relation, using the negation of the test for deep equality:</p> - -<pre class="brush: js">assert.notDeepEqual({ a: "foo" }, Object.create({ a: "foo" }), - "object's inherit from different prototypes");</pre> - -<h5 id="Parameters_6">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="strictEqual(actual_expected_message)"><code>strictEqual(actual, expected, message)</code></h4> - -<p>Tests that two objects are equal, using the strict equality operator <code>===</code>:</p> - -<pre class="brush: js">// This test will pass, because "==" will perform type conversion -exports["test coercive equality"] = function(assert) { - assert.equal(1, "1", "test coercive equality between 1 and '1'"); -} - -// This test will fail, because the types are different -exports["test strict equality"] = function(assert) { - assert.strictEqual(1, "1", "test strict equality between 1 and '1'"); -}</pre> - -<h5 id="Parameters_7">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="notStrictEqual(actual_expected_message)"><code>notStrictEqual(actual, expected, message)</code></h4> - -<p>Tests that two objects are not equal, using the negation of the strict equality operator <code>===</code>:</p> - -<pre class="brush: js">// This test will fail, because "==" will perform type conversion -exports["test coercive equality"] = function(assert) { - assert.notEqual(1, "1", "test coercive equality between 1 and '1'"); -} - -// This test will pass, because the types are different -exports["test strict equality"] = function(assert) { - assert.notStrictEqual(1, "1", "test strict equality between 1 and '1'"); -}</pre> - -<h5 id="Parameters_8">Parameters</h5> - -<p><strong>actual : object</strong><br> - The actual result.</p> - -<p><strong>expected : object</strong><br> - The expected result.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> - -<h4 class="addon-sdk-api-name" id="throws(block_error_message)"><code>throws(block, error, message)</code></h4> - -<p>Assert that a block of code throws the expected exception.</p> - -<p>This method takes an optional <code>Error</code> argument:</p> - -<ul> - <li> - <p>to check that the exception thrown is of the expected type, pass a constructor function: the exception thrown must be an instance of the object returned by that function.</p> - </li> - <li> - <p>to check that the exception thrown contains a specific message, pass a regular expression here: the <code>message</code> property of the exception thrown must match the regular expression</p> - </li> -</ul> - - -<p>For example, suppose we define two different custom exceptions:</p> - -<pre class="brush: js">function MyError(message) { - this.name = "MyError"; - this.message = message || "Default Message"; -} - -MyError.prototype = new Error(); -MyError.prototype.constructor = MyError; - -function AnotherError(message) { - this.name = "AnotherError"; - this.message = message || "Default Message"; - console.log(this.message); -} - -AnotherError.prototype = new Error(); -AnotherError.prototype.constructor = AnotherError;</pre> - -<p>We can check the type of exception by passing a function as the <code>Error</code> argument:</p> - -<pre class="brush: js">exports["test exception type 1 expected to pass"] = function(assert) { - assert.throws(function() { - throw new MyError("custom message"); - }, - MyError, - "test throwing a specific exception"); -} - -exports["test exception type 2 expected to fail"] = function(assert) { - assert.throws(function() { - throw new MyError("custom message"); - }, - AnotherError, - "test throwing a specific exception"); -}</pre> - -<p>We can check the message by passing a regular expression:</p> - -<pre class="brush: js">exports["test exception message 1 expected to pass"] = function(assert) { - assert.throws(function() { - throw new MyError("custom message"); - }, - /custom message/, - "test throwing a specific message"); -} - -exports["test exception message 2 expected to pass"] = function(assert) { - assert.throws(function() { - throw new AnotherError("custom message"); - }, - /custom message/, - "test throwing a specific exception"); -} - -exports["test exception message 3 expected to fail"] = function(assert) { - assert.throws(function() { - throw new MyError("another message"); - }, - /custom message/, - "test throwing a specific message"); -}</pre> - -<h5 id="Parameters_9">Parameters</h5> - -<p><strong>block : block</strong><br> - The block of code to test.</p> - -<p><strong>error : function|RegExp</strong><br> - Either a constructor function returning the type of exception expected, or a regular expression expected to match the exception's <code>message</code> property.</p> - -<p><strong>message : string</strong><br> - Optional message to log, providing extra information about the test.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/ui_button_action/index.html b/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/ui_button_action/index.html deleted file mode 100644 index d826b15d7f..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/low-level_apis/ui_button_action/index.html +++ /dev/null @@ -1,526 +0,0 @@ ---- -title: ui/button/action -slug: Mozilla/Add-ons/SDK/Low-Level_APIs/ui_button_action -translation_of: Archive/Add-ons/Add-on_SDK/Low-Level_APIs/ui_button_action ---- -<div class="note"> - <p>实验性的（译者备注：暂不翻译，可能会废弃）</p> -</div> -<p><span class="seoSummary">Add a button to the Firefox user interface.</span> With this module you can create buttons that display icons and can respond to click events.</p> -<h2 id="Usage">Usage</h2> -<h3 id="Creating_buttons"><br> - Creating buttons</h3> -<p>To create a button you must give it an ID, an icon, and a label:</p> -<pre class="brush: js">var { ActionButton } = require("sdk/ui/button/action"); - -var button = ActionButton({ - id: "my-button", - label: "my button", - icon: { - "16": "./firefox-16.png", - "32": "./firefox-32.png" - }, - onClick: function(state) { - console.log("button '" + state.label + "' was clicked"); - } - });</pre> -<p>By default, the button appears in the Firefox toolbar:</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/6803/action-button-toolbar.png" style="width: 381px; height: 201px; display: block; margin-left: auto; margin-right: auto;">However, users can move it to the Firefox menu panel using the <a href="https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars">toolbar customization feature</a>:</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/6809/action-button-menu.png" style="width: 381px; height: 573px; display: block; margin-left: auto; margin-right: auto;"></p> -<h3 id="Badged_buttons">Badged buttons</h3> -<div class="geckoVersionNote"> - <p>New in Firefox 36.</p> -</div> -<p>You can add a "badge" to a button using its <code>badge</code> property. This can be a number or a string, and you can update it at any time. By default the badge's color is red, but you can set your own color using the <code>badgeColor</code> property, specified as a CSS <a href="/en-US/docs/Web/CSS/color_value"><code><color></code></a> value:</p> -<pre class="brush: js">var { ToggleButton } = require("sdk/ui/button/toggle"); - -var button = ToggleButton({ - id: "my-button1", - label: "my button1", - icon: "./icon-16.png", - onChange: changed, - badge: 0, - badgeColor: "#00AAAA" - }); - -function changed(state) { - button.badge = state.badge + 1; - if (state.checked) { - button.badgeColor = "#AA00AA"; - } - else { - button.badgeColor = "#00AAAA"; - } -}</pre> -<p><img alt="" src="https://mdn.mozillademos.org/files/9067/badge.png" style="width: 383px; height: 202px; display: block; margin-left: auto; margin-right: auto;"></p> -<h3 id="Specifying_multiple_icons">Specifying multiple icons</h3> -<p>You can specify just one icon, or multiple icons in different sizes.</p> -<p>If you specify multiple icons, Firefox will select the best-fitting icon based on the device screen resolution and the place the icon appears. For example, in the screenshots above, Firefox uses the small icon when the button is in the toolbar and the large icon when the button is in the menu panel. Read more about specifying icons in the reference documentation for the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#ActionButton(options)"><code>ActionButton</code> constructor</a>.</p> -<h3 id="Responding_to_click_events">Responding to click events</h3> -<p>You can respond to click events by assigning a listener to the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click"><code>click</code></a> event. You can do this in the button's constructor, by assigning the listener to the <code>onClick</code> option. You can also add, or change, the listener afterwards:</p> -<pre class="brush: js">var { ActionButton } = require("sdk/ui/button/action"); - -var button = ActionButton({ - id: "my-button", - label: "my button", - icon: { - "16": "./firefox-16.png", - "32": "./firefox-32.png" - }, - onClick: firstClick - }); - -function firstClick(state) { - console.log("You clicked '" + state.label + "'"); - button.removeListener("click", firstClick); - button.on("click", subsequentClicks); -} - -function subsequentClicks(state) { - console.log("You clicked '" + state.label + "' again"); -}</pre> -<p>The listener is passed a <code>state</code> object that contains all the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Properties">properties</a>.</p> -<p>You can generate click events programmatically with the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click()"><code>click()</code></a> method.</p> -<h3 id="Disabling_buttons">Disabling buttons</h3> -<p>You can disable a button by setting its <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#disabled"><code>disabled</code></a> property to <code>true</code>. A disabled button will not generate click events and its icon will appear disabled:</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/6805/action-button-toolbar-disabled.png" style="width: 381px; height: 201px; display: block; margin-left: auto; margin-right: auto;"></p> -<h3 id="Updating_state">Updating state</h3> -<p>You can update all the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Properties">properties</a> except for its <code>id</code>.</p> -<p>By default, the button has global state: that is, its properties are the same across all open windows and tabs, and updating them updates the button's state across all open windows and tabs.</p> -<p>You can set state to be specific to a window or tab using the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#state()"><code>state()</code></a> method. To set state like this, call <code>state()</code> with 2 parameters:</p> -<ul> - <li>the first parameter is a <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows"><code>window</code></a> or <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs#Tab"><code>tab</code></a> object or as a shorthand, the string "window" for the currently active window, or the string "tab" for the currently active tab</li> - <li>the second parameter is an object containing the state properties you wish to update.</li> -</ul> -<p>Here's an add-on with a button that disables itself when you click it, but only for the currently active window:</p> -<pre class="brush: js">var { ActionButton } = require("sdk/ui/button/action"); - -var button = ActionButton({ - id: "my-button", - label: "my button", - icon: { - "16": "./firefox-16.png", - "32": "./firefox-32.png" - }, - onClick: disableForThisWindow - }); - -function disableForThisWindow(state) { - button.state("window", { - disabled: true - }); -}</pre> -<p>To fetch the state for a specific window or tab, call <code>state()</code>, passing in the window or tab you are interested in, and it will return the state:</p> -<pre class="brush: js">var labelForActiveTab = button.state("tab").label;</pre> -<p>To learn more about this, see the API documentation for <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#state()"><code>state()</code></a>.</p> -<h3 id="Destroying_buttons">Destroying buttons</h3> -<p>When you've finished with a button, destroy it by calling its <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#destroy()"><code>destroy()</code></a> method. After that, any attempts to access any of its properties or to call any of its methods will throw exceptions.</p> -<h2 id="Globals">Globals</h2> -<h3 id="Constructors">Constructors</h3> -<h4 class="addon-sdk-api-name" id="ActionButton(options)"><code>ActionButton(options)</code></h4> -<p>Creates an action button.</p> -<h5 id="Parameters">Parameters</h5> -<p><strong>options : object</strong><br> - Required options:</p> -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>id</td> - <td>string</td> - <td> - <p>The button's ID. This is used internally to keep track of this button. The ID must be unique within your add-on.</p> - </td> - </tr> - <tr> - <td>label</td> - <td>string</td> - <td> - <p>The button's human-readable label. When the button is in the toolbar, this appears in a tooltip, and when the button is in the menu, it appears underneath the button as a legend.</p> - </td> - </tr> - <tr> - <td>icon</td> - <td>url, string, object</td> - <td> - <p>One or more icons for the button. You can specify this in one of three ways: </p> - <ul> - <li><strong>as a resource:// URL</strong> pointing at an icon file in your add-on's "data" directory, typically constructed using <em><code>self.data.url(iconfile)</code></em></li> - <li><strong>as a relative path</strong>: a string in the form "./iconfile", where "iconfile" is a relative path to the icon file beginning in your add-on's "data" directory</li> - <li><strong>as an object, or dictionary of key-value pairs</strong>. Here you can specify a range of sizes for your button's icon. Each key-value pair specifies an icon: - <ul> - <li>each value specifies an image file as a resource:// URL or relative path.</li> - <li>each key must be a numeric string such as "16", or "32", which represents the size in pixels of the corresponding image.</li> - </ul> - </li> - </ul> - <pre class="brush: js"> -var { ActionButton } = require('sdk/ui/button/action'); -var self = require("sdk/self"); - -var button1 = ActionButton({ - id: "my-button1", - label: "my button1", - icon: self.data.url("firefox-16.png") - }); - -var button2 = ActionButton({ - id: "my-button2", - label: "my button2", - icon: "./firefox-16.png" - }); - -var button3 = ActionButton({ - id: "my-button3", - label: "my button3", - icon: { - "16" : "./firefox-16.png", - "32" : "./firefox-32.png", - "64" : "./firefox-64.png" - } - });</pre> - <p>If you use the final form, Firefox will automatically choose the best-fit icon for your button, depending on the device screen resolution and where the button is in the UI. On a device with a "normal" screen resolution, the toolbar has space for 18 x 18 pixels and the menu panel has space for 32 x 32 pixels. On a high resolution screen (such as a <a href="https://en.wikipedia.org/wiki/Retina_Display">HiDPI</a> display), these are doubled to 36 x 36 and 64 x 64 pixels, respectively. So you can supply three icon files:</p> - <pre class="brush: js"> -icon: { - "16": "./addon16.png", - "32": "./addon32.png", - "64": "./addon64.png" -}</pre> - <p>This will look fine in both toolbar and menu panel, and for both screen resolutions. However, the icons in the toolbar will not quite fill the space available, so you can instead supply four icons:</p> - <pre class="brush: js"> -icon: { - "18": "./addon18.png", // toolbar icon non HiDPI - "32": "./addon32.png", // menu panel icon non HiDPI - "36": "./addon36.png", // toolbar icon HiDPI - "64": "./addon64.png" // menu panel icon HiDPI -} -</pre> - </td> - </tr> - </tbody> -</table> -<p>Optional options:</p> -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>disabled</td> - <td>boolean</td> - <td> - <p>Determines whether the button is disabled. Disabled buttons appear disabled in the UI, and do not respond to clicks. Defaults to false.</p> - </td> - </tr> - <tr> - <td>onClick</td> - <td>function</td> - <td> - <p>Click handler for the button.</p> - </td> - </tr> - <tr> - <td>badge</td> - <td>Number or String</td> - <td> - <div class="geckoVersionNote"> - <p>New in Firefox 36.</p> - </div> - <p><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Badged_buttons">Badge</a> to attach to the button.</p> - </td> - </tr> - <tr> - <td>badgeColor</td> - <td>CSS <a href="/en-US/docs/Web/CSS/color_value"><color></a> value</td> - <td> - <div class="geckoVersionNote"> - <p>New in Firefox 36.</p> - </div> - <p>Color for the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Badged_buttons">badge</a>. If <code>badgeColor</code> is omitted and <code>badge</code> is specified, then the badge is red.</p> - </td> - </tr> - </tbody> -</table> -<h2 id="ActionButton">ActionButton</h2> -<h3 id="Methods">Methods</h3> -<h4 class="addon-sdk-api-name" id="click()"><code>click()</code></h4> -<p>Click the button. This will cause the button to generate the <code>click</code> event:</p> -<pre class="brush: js">var { ActionButton } = require('sdk/ui/button/action'); - -var button = ActionButton({ - id: "my-button", - label: "my button", - icon: { - "16": "./firefox-16.png", - "32": "./firefox-32.png" - }, - onClick: function(state) { - console.log("You clicked '" + state.label + "'"); - } -}); - -button.click(); -</pre> -<h4 class="addon-sdk-api-name" id="state()"><code>state()</code></h4> -<p>Get or set the button's state for a specific window or tab.</p> -<p>By default, a button's properties are global, meaning that they are the same across all open windows and tabs, and that if you update these properties, then they are updated across all windows and tabs. But sometimes you want a button attached to one window (or tab) to have a different state to a button attached to a different window (or tab). That's what <code>state()</code> is for.</p> -<p>To set a button's properties for a specific window or tab, call <code>state()</code>, passing it the <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows"><code>window</code></a> or <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tab</code></a> you want the property to apply to, and the property value to set. A special shortcut allows you to pass the string "window" or "tab" to select the currently active window or tab.</p> -<p>For example, if you have a button like this:</p> -<pre class="brush: js">var { ActionButton } = require('sdk/ui/button/action'); - -var button = ActionButton({ - id: "my-button", - label: "default", - icon: "./firefox-16.png" -});</pre> -<p>You can change its label for only the currently active window like this:</p> -<pre class="brush: js">button.state("window", { - "label" : "window-specific label" -});</pre> -<p>You can change its label for only the currently active tab like this:</p> -<pre class="brush: js">button.state("tab", { - "label" : "tab-specific label" -}); -</pre> -<p>To fetch the button state for a specific window or tab, call <code>state()</code>, passing it the window or tab you're interested in, and it will return a state object containing all the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Properties">properties</a> for the button associated with that window or tab. Again. you can use the strings "window" or "tab" as shortcuts. For example, this add-on:</p> -<ul> - <li>creates a button with a default label</li> - <li>opens a new tab</li> - <li>sets a new label only for the new tab</li> - <li>logs the result of accessing the global label, the window-specific label, and each of the 2 tab-specific labels</li> -</ul> -<pre class="brush: js">var { ActionButton } = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = ActionButton({ - id: "my-button", - label: "default label", - icon: "./firefox-16.png" -}); - -tabs.open({ - url: "https://mozilla.org/", - onOpen: onNewTab -}); - -function onNewTab(tab) { - // Modify the label only for the new tab - button.state(tab, { - "label" : "tab-specific label" - }); - - // access the global label -> "default label" - console.log(button.label); - - // access the window's label -> "default label" - console.log(button.state("window").label); - - // access the first tab's label -> "default label" - console.log(button.state(tabs[0]).label); - - // access the second tab's label -> "tab-specific label" - console.log(button.state(tabs[1]).label); -}</pre> -<p>Setting a property won't affect a more-specific property setting. For example, if you have a window with two tabs, and you set a tab-specific label, then set the window-specific label, this will not overwrite the tab-specific label:</p> -<pre class="brush: js">var { ActionButton } = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = ActionButton({ - id: "my-button", - label: "default label", - icon: "./firefox-16.png" -}); - -tabs.open({ - url: "https://mozilla.org/", - onOpen: onNewTab -}); - -function onNewTab(tab) { - // Modify the label only for the new tab - button.state(tab, { - "label" : "tab-specific label" - }); - - // Modify the label for the window - button.state("window", { - "label" : "window-specific label" - }); - - // access the global label -> "default label" - console.log(button.label); - - // access the window's label -> "window-specific label" - console.log(button.state("window").label); - - // access the first tab's label -> "window-specific label" - console.log(button.state(tabs[0]).label); - - // access the second tab's label -> "tab-specific label" - console.log(button.state(tabs[1]).label); -}</pre> -<p>The best way to think of this is as a tree: the global state is the root, followed by the state for each window, followed by the state for each tab in a window. If a property value for a node in the tree has not been set explicitly using <code>state()</code>, then it inherits its value from the next level up. So if you have one window containing two tabs, and have set the button's <code>label</code> only for tab A, then tab B will inherit <code>label</code>'s value from the window, and changing the value for the window will implicitly change the value for tab B.</p> -<p>To delete a tab- or window-specific state, assign <code>null</code> to the property. After that, the property will inherit its value from the less-specific state as before:</p> -<pre class="brush: js">var { ActionButton } = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = ActionButton({ - id: "my-button", - label: "default label", - icon: "./firefox-16.png" -}); - -tabs.open({ - url: "https://mozilla.org/", - onOpen: onNewTab -}); - -function onNewTab(tab) { - // Modify the label only for the new tab - button.state(tab, { - "label" : "tab-specific label" - }); - - // Modify the label for the window - button.state("window", { - "label" : "window-specific label" - }); - - // access the global label -> "default label" - console.log(button.label); - - // access the window's label -> "window-specific label" - console.log(button.state("window").label); - - // access the first tab's label -> "window-specific label" - console.log(button.state(tabs[0]).label); - - // access the second tab's label -> "tab-specific label" - console.log(button.state(tabs[1]).label); - - // Reset the tab-specific state - button.state(tab, null); - - // access the second tab's label -> "window-specific label" - console.log(button.state(tabs[1]).label); -}</pre> -<p>Finally, you can pass the button itself into <code>state()</code>. This is an alternative way to set or get the global state. The reason for using this, rather than setting properties individually, is that you can define an object with the properties to set in one place, then apply it to the global state with a single line:</p> -<pre class="brush: js">const defaultState = { - "label": "default label", - "icon": "./default.png", -} - -const differentState = { - "label": "different label", - "icon": "./different.png", -} - -var { ActionButton } = require("sdk/ui/button/action"); - -var button = ActionButton({ - id: "default-label", - label: "default label", - icon: "./default.png", - onClick: function(state) { - if (button.label == "default label") { - button.state(button, differentState); - } - else { - button.state(button, defaultState); - } - console.log(button.state(button).label); - console.log(button.state(button).icon); - } - }); -</pre> -<h5 id="Parameters_2">Parameters</h5> -<p><strong>target : button, tab, window, string</strong></p> -<ul> - <li>To set or get the global state, this needs to be the <code>button</code> instance.</li> - <li>To get or set window-specific state, this needs to be the <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows"><code>window</code></a> object for which you wish to set a specific state, or the string "window" to select the currently active window.</li> - <li>To get or set tab-specific state this needs to be the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tab</code></a> object for which you wish to set a specific state, or the string "tab" to select the currently active tab.</li> -</ul> -<p><strong>state : object, null</strong><br> - Include this parameter only if you are setting state. It is an object containing all the properties you wish to set. For example:</p> -<pre class="brush: js">button.state("tab", { - "label" : "tab-specific label", - "icon": "./tab-specific-icon.ico" -});</pre> -<p>To reset state, pass null:</p> -<pre class="brush: js">button.state("tab", null);</pre> -<h5 id="Returns">Returns</h5> -<p><strong>state</strong> : if you have passed the second <code>state</code> argument to make this function a setter, it returns <code>undefined</code>. Otherwise, it functions as a getter and returns the button's state for the specified object. This logs the state for the button associated with the currently active tab:</p> -<pre class="brush: js">console.log(button.state("tab"));</pre> -<p>This object represents a snapshot of the state at the time <code>state()</code> is called. It is not kept up to date with changes made to the button:</p> -<pre class="brush: js">button.label = "foo"; -var state = button.state(button); -button.label = "bar"; -console.log(state.label) // foo</pre> -<h4 class="addon-sdk-api-name" id="on()"><code>on()</code></h4> -<p>Add a listener to an event emitted by the button. The button only emits one type of event, <code><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click">click</a></code>:</p> -<pre class="brush: js">button.on("click", handleClick) - -function handleClick(state) { - console.log("button '" + state.label + "' was clicked"); -}</pre> -<h5 id="Parameters_3">Parameters</h5> -<p><strong>event : string</strong><br> - The event to listen for. Action buttons only emit one type of event, "<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click"><code>click</code></a>".</p> -<p><strong>listener : function</strong><br> - Function that will be called on click.</p> -<h4 class="addon-sdk-api-name" id="once()"><code>once()</code></h4> -<p>Assign a listener to the first occurrence only of an event emitted by the button. The button only emits one type of event, <code><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click">click</a></code>. The listener is automatically removed after the first time the event is emitted.</p> -<h5 id="Parameters_4">Parameters</h5> -<p><strong>event : string</strong><br> - The event to listen for. Action buttons only emit one type of event, "<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click"><code>click</code></a>".</p> -<p><strong>listener : function</strong><br> - Function that will be called on click.</p> -<h4 class="addon-sdk-api-name" id="removeListener()"><code>removeListener()</code></h4> -<p>Removes an event listener. For example, this code is equivalent to <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#once()"><code>once()</code></a>:</p> -<pre class="brush: js">button.on("click", handleClick) - -function handleClick(state) { - console.log("button '" + state.label + "' was clicked"); - button.removeListener("click", handleClick); -} </pre> -<h5 id="Parameters_5">Parameters</h5> -<p><strong>event : string</strong><br> - The event to listener is listening for. Action buttons only emit one type of event, "<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#click"><code>click</code></a>".</p> -<p><strong>listener : function</strong><br> - The listener to remove.</p> -<h4 class="addon-sdk-api-name" id="destroy()"><code>destroy()</code></h4> -<p>Destroy the button. After calling this function, the button will no longer appear in the UI, and accessing any of its properties or methods will throw an error.</p> -<h3 id="Properties">Properties</h3> -<h4 class="addon-sdk-api-name" id="id"><code>id</code></h4> -<p>The button's unique ID. This is read-only.</p> -<h4 class="addon-sdk-api-name" id="label"><code>label</code></h4> -<p>The button's label.</p> -<h4 class="addon-sdk-api-name" id="icon"><code>icon</code></h4> -<p>The button's icon or icons, as a URL, relative path, or object containing a set of key-value pairs.</p> -<h4 class="addon-sdk-api-name" id="disabled"><code>disabled</code></h4> -<p>Boolean property indicating whether or not the button is disabled.</p> -<h4 class="addon-sdk-api-name" id="badge"><code>badge</code></h4> -<div class="geckoVersionNote"> - <p>New in Firefox 36.</p> -</div> -<p>Value to attach to the button as a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Badged_buttons">badge</a>. May be a number or a string.</p> -<h4 class="addon-sdk-api-name" id="badgeColor"><code>badgeColor</code></h4> -<div class="geckoVersionNote"> - <p>New in Firefox 36.</p> -</div> -<p>Color for the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Badged_buttons">badge</a>, specified as a CSS <a href="/en-US/docs/Web/CSS/color_value"><color></a> value.</p> -<h3 id="Events">Events</h3> -<h4 class="addon-sdk-api-name" id="click"><code>click</code></h4> -<p>This event is emitted when a user clicks the button or your add-on calls the button's <code>click()</code> method.</p> -<h5 id="Arguments">Arguments</h5> -<p><strong>state</strong> : The button's state. This contains all the button's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Properties">properties</a>.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tools/index.html b/files/zh-cn/mozilla/add-ons/sdk/tools/index.html deleted file mode 100644 index 8c67b4644e..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tools/index.html +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Tools -slug: Mozilla/Add-ons/SDK/Tools -tags: - - Add-on SDK - - CFX - - JPM - - NeedsTranslation - - TopicStub -translation_of: Archive/Add-ons/Add-on_SDK/Tools ---- -<p>Articles listed here provide a reference for the SDK's tools:</p> - -<p>{{ LandingPageListSubpages ("/en-US/Add-ons/SDK/Tools", 7) }}</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tools/jpm/index.html b/files/zh-cn/mozilla/add-ons/sdk/tools/jpm/index.html deleted file mode 100644 index db429ef078..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tools/jpm/index.html +++ /dev/null @@ -1,652 +0,0 @@ ---- -title: jpm -slug: Mozilla/Add-ons/SDK/Tools/jpm -tags: - - Add-on SDK - - JPM -translation_of: Archive/Add-ons/Add-on_SDK/Tools/jpm ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>你能在Firefox 38或更高的版本中使用jpm。</p> - -<p>本文为jpm参考。</p> -</div> - -<p><span class="seoSummary"><a href="/en-US/Add-ons/SDK/Tools/cfx">cfx</a> 的Node版本允许你测试、运行以及打包扩展。</span></p> - -<p>你也可以阅读 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29">jpm教程</a> 开始学习。</p> - -<p>jpm 用法:</p> - -<pre class="brush: bash">jpm [command] [options] -</pre> - -<p>jpm支持以下全局参数:</p> - -<pre class="brush: bash">-h, --help - 显示帮助信息并退出 --V, --version - 打印出jpm版本号 ---addon-dir - 源代码目录，默认为当前目录 -</pre> - -<h2 id="安装">安装</h2> - -<p>jpm发布在node包管理器 <a class="external external-icon" href="https://www.npmjs.org/package/jpm">npm</a> 上。</p> - -<h3 id="安装npm">安装npm</h3> - -<p>有两种方法来获取npm。</p> - -<ul> - <li>访问 <a href="http://nodejs.org/">nodejs.org</a> 下载并安装Node.js。Node.js 包含npm。</li> - <li>或者，如果你的系统有像 APT 这种包管理器，就用它来安装。例如，在 Ubuntu 或者 Debian 的终端窗口里，输入<code>sudo apt-get install nodejs nodejs-legacy npm</code></li> -</ul> - -<p>要测试安装是否成功，运行：</p> - -<pre class="brush: bash">/usr/bin/env node -v</pre> - -<p>如果出现错误提示 <em>/usr/bin/env: node: No such file or directory</em> 并且你的 nodejs 是通过包管理的方式安装的，那你的 nodejs 很有可能安装为其它的名字。为了保证jpm的兼容，PATH之中必须是以node为可执行文件名的。在Debian和Ubuntu系统上，你可以通过安装兼容包nodejs-legacy来解决这个问题：</p> - -<pre class="brush: bash"><code>sudo apt-get install nodejs-legacy</code></pre> - -<p><font face="Consolas, Liberation Mono, Courier, monospace">在其它的发行版中，你或许必须手动创建一共本地符号链接：</font></p> - -<pre><code>sudo ln -s "$(which nodejs)" /usr/local/bin/node</code></pre> - -<h3 id="安装jpm"><code>安装jpm</code></h3> - -<p>在你安装好npm并且将其加入你的PATH中后，你可以像安装其他npm包一样来安装jpm。</p> - -<h4 id="全局安装jpm">全局安装jpm</h4> - -<pre><code>npm install jpm --global</code></pre> - -<p>取决于你的安装，你可能需要管理员权限执行:</p> - -<pre class="brush: bash"><code>sudo npm install jpm --global</code></pre> - -<h4 id="局部安装jpm"><code>局部安装jpm</code></h4> - -<p><code>如果你不想，或者不能够全局安装jpm，你或许可以只为你安装它：</code></p> - -<pre><code>npm install jpm</code></pre> - -<p><code>在局部安装的情况下，为了在终端中运行jpm，你必须首先将目录</code>"$HOME/node_modules/.bin/"添加到你的终端PATH中。将下行中的命令添加到$HOME/.profile的末尾来实现永久添加（.profile将在每次运行一个新终端时被执行）：</p> - -<pre><code>export PATH="$HOME/node_modules/.bin/:$PATH"</code></pre> - -<h4 id="通过git来安装jpm">通过git来安装jpm</h4> - -<p>另外，你也可以通过git安装jpm的最新版本</p> - -<pre>git clone https://github.com/mozilla-jetpack/jpm.git -cd jpm -npm install -npm link -</pre> - -<h3 id="jpm安装完毕后">jpm安装完毕后</h3> - -<p><span style="line-height: 1.5;">在全部搞定后，在命令行窗口中输入:</span></p> - -<pre class="brush: bash"><code>jpm</code></pre> - -<p>屏幕上显示了一系列可用的 jpm 命令。不同于 cfx，当在安装时使用了 --global 参数，你能在任何路径下启动的命令提示符中使用 jpm 命令。</p> - -<h3 id="还有问题？">还有问题？</h3> - -<p>如果你看不懂本文，要寻求帮助。SDK 用户和项目团队成员在<a class="external external-icon" href="http://groups.google.com/group/mozilla-labs-jetpack/topics">项目邮件列表</a>中讨论问题和建议。其他人也许会和你有一样的问题，所以试着搜索一下列表。也欢迎你发表一个新问题。你也可以在 <a class="external external-icon" href="http://irc.mozilla.org/">Mozilla 的 IRC 网络</a> 的 <a class="external external-icon" href="http://mibbit.com/?channel=%23jetpack&server=irc.mozilla.org">#jetpack</a> 房间里和其他SDK的用户聊天。</p> - -<h2 id="命令参考">命令参考</h2> - -<p>有六个命令：</p> - -<table> - <tbody> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_init"><code>jpm init</code></a></td> - <td>创建一个基本的 add-on 作为你 add-on 的开端。</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_run"><code>jpm run</code></a></td> - <td>运行一个带有你的 add-on 的 Firefox 实例。</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_test"><code>jpm test</code></a></td> - <td>运行你插件的单元测试</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_xpi"><code>jpm xpi</code></a></td> - <td>将你的插件打包为 <a href="https://developer.mozilla.org/zh-CN/docs/XPI">XPI</a> 文件（火狐的插件扩展文件名）</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_post"><code>jpm post</code></a></td> - <td>把你的 add-on 打包成 <a href="https://developer.mozilla.org/zh-CN/docs/XPI">XPI</a> 文件，然后发送到某一个URL。</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_watchpost"><code>jpm watchpost</code></a></td> - <td>无论是否有文件变更，把你的 add-on 打包成 <a href="https://developer.mozilla.org/zh-CN/docs/XPI">XPI</a> 文件发送到某一个URL。</td> - </tr> - <tr> - <td><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_sign"><code>jpm sign</code></a></td> - <td>将你的插件打包为 <a href="https://developer.mozilla.org/zh-CN/docs/XPI">XPI</a> 文件并且取回一个由Mozilla签名的新XPI文件。</td> - </tr> - </tbody> -</table> - -<h3 id="jpm_init">jpm init</h3> - -<p>这个命令从头开始初始化一个新的 add-on。</p> - -<p>新建一个目录，转到该目录下，然后运行 <code>jpm init</code>。</p> - -<pre><code>mkdir my-addon -cd my-addon -jpm init</code></pre> - -<p>然后你会被要求提供关于你的 add-on 的一些信息：这会用来创建 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json">package.json</a> 文件。</p> - -<ul> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#title">title</a></li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#name">name</a>: 默认是你运行 <code>jpm init 的目录名。除非</code>package.json里有 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#id"><code>id</code></a> 字段， jpm 在name前面加个<code>"@"</code>用作 <a href="https://developer.mozilla.org/en-US/Add-ons/Install_Manifests#id">add-on 安装清单的 <code>id</code> 字段</a>.</li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#version">version</a></li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#description">description</a></li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#main">entry point</a> (映射向package.json中的 "main")</li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#author">author</a></li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#engines">engines</a> (支持哪些应用程序)</li> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#license">license</a></li> -</ul> - -<p>大部分字段都有一个默认值，显示在那些问题的后面的括号里。如果你按了回车，那么你的 add-on 就用那个默认值。</p> - -<p>一旦你提供了一个值或者接受了默认值，你会看到"package.json"的完整内容，并被询问是否接受。</p> - -<p>然后 jpm 创建一个基本的 add-on，作为你开发的起点，文件结构如下：</p> - -<ul> - <li>my-addon - <ul> - <li>index.js</li> - <li>package.json</li> - <li>test - <ul> - <li>test-index.js</li> - </ul> - </li> - </ul> - </li> -</ul> - -<h3 id="jpm_run">jpm run</h3> - -<p>此命令运行一个新的装有你的 add-on 的 Firefox实例：</p> - -<pre><code>jpm run</code></pre> - -<p><code>jpm run</code> 有以下选项：</p> - -<table> - <tbody> - <tr> - <td><code>-b --binary BINARY</code></td> - <td> - <p>指定二进制文件，使用该版本的火狐。可以用全路径，也可以用相对路径。</p> - - <pre> -<code>jpm run -b /path/to/Firefox/Nightly</code></pre> - 参看<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Selecting_a_browser_version">选择浏览器版本</a>。</td> - </tr> - <tr> - <td><code>--binary-args CMDARGS</code></td> - <td> - <p>传递<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options">附件参数</a>到 Firefox。</p> - - <p>例如，为了传递 <code>-jsconsole</code>参数给 Firefox 并打开<a href="https://developer.mozilla.org/en-US/docs/Tools/Browser_Console">浏览器</a>，试试下面命令：</p> - - <pre> -<code>jpm run --binary-args -jsconsole</code></pre> - - <p>要传递多个参数，或者参数中间有空格，就把他们用引号括起来：</p> - - <pre> -<code>jpm run --binary-args '-url mzl.la -jsconsole'</code></pre> - </td> - </tr> - <tr> - <td><code>--debug</code></td> - <td>运行这个 add-on 的<a href="https://developer.mozilla.org/en-US/Add-ons/Add-on_Debugger">Add-on 调试器</a>。</td> - </tr> - <tr> - <td><code>-o --overload PATH</code></td> - <td> - <p>不再使用 Firefox 内建的 SDK 模块，使用指定 PATH 路径下的模块。如果加了 <code>-o</code> 但 PATH 没有指定，jpm 会寻找 JETPACK_ROOT 环境变量用作路径</p> - - <p>参看<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Overloading_the_built-in_modules">重载内建模块</a>以获取更多信息</p> - </td> - </tr> - <tr> - <td><code>-p --profile=<code> PROFILE</code></code></td> - <td> - <p>在你每次调用jpm run时，jpm 默认使用一个干净的临时的 Firefox <a href="http://support.mozilla.com/en-US/kb/profiles">配置文件（profile）</a>。使用<code>--profile</code> 选项以使得 jpm 使用已有的配置文件来打开 Firefox。</p> - - <p>PROFILE的值可以是一个profile的名字或路径。</p> - - <p>参看 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Using_profiles">使用 profile</a> 以获取更多信息。</p> - </td> - </tr> - <tr> - <td><code>-v --verbose</code></td> - <td>（查看）详细操作</td> - </tr> - <tr> - <td><code>--no-copy</code></td> - <td> - <div class="warning">小心使用，因为 <code>jpm run|test</code> 会改变很多配置，不要和你的主配置文件一起使用。</div> - - <div class="note">只有使用 <code>--profile</code> 的时候回生效</div> - 禁止配置文件的拷贝，允许重用配置。</td> - <td> </td> - </tr> - </tbody> -</table> - -<h3 id="jpm_test">jpm test</h3> - -<p>这个命令用来运行 add-on 的单元测试。命令：</p> - -<ul> - <li>查找在当前目录（或者 <code>--addon-dir</code> 目录）下的test文件夹。</li> - <li>打开所有名字以 "test-" 开头的文件。注意文件名中"test"后面的连字符号。<code>jpm test</code> 包含一个 "test-myCode.js" 文件，但会排除"test_myCode.js"或"test_myCode.js"。</li> - <li>调用文件中所有export的、以"test"开头的函数。</li> -</ul> - -<pre><code>jpm test</code></pre> - -<p>查看 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Unit_testing">单元测试教程</a> 和 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/test_assert"> <code>assert</code> 模块参考文档</a>获取更多具体内容。</p> - -<p><code>jpm test</code> 接受一下选项：</p> - -<table> - <tbody> - <tr> - <td><code>-b --binary BINARY</code></td> - <td> - <p>指定所用 Firefox 的版本。BINARY 可被指定为绝对路径或者基于当前路径的相对路径。</p> - - <pre> -<code>jpm test -b /path/to/Firefox/Nightly</code></pre> - - <p>请查看<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Selecting_a_browser_version">选择一个浏览器版本</a>。</p> - </td> - </tr> - <tr> - <td><code>--binary-args CMDARGS</code></td> - <td> - <p>传递<a href="http://kb.mozillazine.org/Command_line_arguments">附件参数</a>给 Firefox。</p> - - <p>例如，传递 <code>-jsconsole</code> 参数，它会打开<a href="https://developer.mozilla.org/en-US/docs/Tools/Browser_Console">浏览器控制台</a>，试试下面的命令：</p> - - <pre> -<code>jpm test --binary-args -jsconsole</code></pre> - - <p>传递多个参数，或者参数间有空格，请将它们用引号括起来：</p> - - <pre> -<code>jpm test --binary-args '-url mzl.la -jsconsole'</code></pre> - </td> - </tr> - <tr> - <td><code>--debug</code></td> - <td>运行 <a href="https://developer.mozilla.org/en-US/Add-ons/Add-on_Debugger">add-on debugger</a> 附件到当前 add-on 上。</td> - </tr> - <tr> - <td><code>-f --filter FILE[:TEST]</code></td> - <td> - <p>只运行名字和 FILE 匹配的测试文件，且名字匹配 TEST（可选）的测试函数。</p> - - <pre> -<code>jpm test --filter base64:btoa</code></pre> - - <p>上面的命令值会运行名字中含有"base64"的文件，在这些文件中只会运行名字中含有"btoa"的测试函数。</p> - </td> - </tr> - <tr> - <td><code>-o --overload PATH</code></td> - <td> - <p>不使用 Firefox 内建的模块，而使用 PATH 路径下的模块。如果 <code>-o</code> 指定而 PATH 被忽略，jpm会查找 JETPACK_ROOT 环境变量并将其用作路径。</p> - - <p>查看<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Overloading_the_built-in_modules">重载内建模块</a>以获取更多信息。</p> - </td> - </tr> - <tr> - <td><code>-p --profile<code> PROFILE</code></code></td> - <td> - <p>你每次运行jpm call时，默认地，jpm使用一个干净的临时 Firefox <a href="http://support.mozilla.com/en-US/kb/profiles">配置文件</a>。使用<code>--profile</code> 选项来让 jpm 使用一个现有配置文件来打开火狐。</p> - - <p>PROFILE 的值可以是配置文件的名称或者指向配置文件的路径。</p> - - <p>查看<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Using_profiles">使用配置文件</a>来获取更多信息。</p> - </td> - </tr> - <tr> - <td><code>--stop-on-error</code></td> - <td> - <p>即使测试失败，jpm test 默认还会继续运行测试。指定 <code>--stop-on-error</code> 的话，会在第一次失败后停止运行测试</p> - - <pre> -<code>jpm test --stop-on-error</code></pre> - </td> - </tr> - <tr> - <td><code>--tbpl</code></td> - <td>用<a href="https://treeherder.mozilla.org/">Treeherder</a> 格式打印 test 的输出</td> - </tr> - <tr> - <td><code>--times NUMBER</code></td> - <td> - <p>运行几遍 test：</p> - - <pre> -<code>jpm test --times 2</code></pre> - </td> - </tr> - <tr> - <td><code>-v --verbose</code></td> - <td>详细操作。</td> - </tr> - <tr> - <td><code>--no-copy</code></td> - <td> - <p>小心使用，因为 <code>jpm run|test</code> 会修改许多首选项，这些首选项在你的主配置文件中从未用过。</p> - - <p>这仅仅在使用 <code>--profile</code> 时生效。</p> - 禁用配置未经的拷贝，允许用户重用配置文件。</td> - </tr> - </tbody> -</table> - -<h3 id="jpm_xpi">jpm xpi</h3> - -<p>这个命令将 add-on 打包为一个 <a href="https://developer.mozilla.org/en/XPI">XPI</a> 文件，这是 Mozilla 附加组件的安装文件的格式。</p> - -<pre><code>jpm xpi</code></pre> - -<p>它会在当前目录(或者 <code>--addon-dir</code> 指定的目录）查找 <code>package.json</code> 文件，并创建相关的 XPI 文件。它忽略任何 ZIP 或 XPI文件（译者注：OSX 上测试下来不会默认忽略这些文件，若要忽略请编辑.jpmignore文件），以及任何测试文件。它会包含其他所有文件。如果你想排除其他文件，查看 <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/SDK/Tools/en-US/Add-ons/SDK/Tools/jpmignore">.jpmignore 文件</a>。</p> - -<p>一旦你构建了一个 XPI 文件，你可以通过提交到 <a href="http://addons.mozilla.org/">addons.mozilla.org</a> 来分发你的附加组件。</p> - -<p><code>jpm xpi</code> 接受下列选项：</p> - -<table> - <tbody> - <tr> - <td><code>-v --verbose</code></td> - <td> - <p>打印详细操作：</p> - - <pre> -<code>jpm xpi -v</code></pre> - </td> - </tr> - </tbody> -</table> - -<h3 id="jpm_post">jpm post</h3> - -<p>这个命令把附加组件打包为 <a href="https://developer.mozilla.org/en/XPI">XPI</a> 后 post 到某个URL。</p> - -<pre><code>jpm post</code></pre> - -<p>查找当前目录（或 <code>--addon-dir</code>）下的<code>package.json</code> 文件，创建 XPI 文件，post 到 <code>--post-url</code>。</p> - -<p><code>jpm post</code> 接受以下选项：</p> - -<table> - <tbody> - <tr> - <td><code>--post-url URL</code></td> - <td> - <p>创建 XPI 文件后，将扩展 post 到这个URL。</p> - - <pre> -<code>jpm post --post-url http://localhost:8888/</code></pre> - - <p>查看<a href="https://www.npmjs.com/package/jpm#using-post-and-watchpost">使用 Post 和 Watchpost</a> 获取更多信息。</p> - </td> - </tr> - <tr> - <td><code>-v --verbose</code></td> - <td> - <p>打印详细操作：</p> - - <pre> -<code>jpm post --post-url http://localhost:8888/ -v</code></pre> - </td> - </tr> - </tbody> -</table> - -<h3 id="jpm_watchpost">jpm watchpost</h3> - -<p>这个命令在打包附件组件为 <a href="https://developer.mozilla.org/en/XPI">XPI</a> 文件后，无论文件是否改变都将其 post 到某个URL。</p> - -<pre><code>jpm watchpost</code></pre> - -<p>无论文件是否改变，在当前目录（或 <code>--addon-dir</code>）下创建一个 XPI并将其post到 <code>--post-url</code>。</p> - -<p><code>jpm watchpost</code> 接受以下选项：</p> - -<table> - <tbody> - <tr> - <td><code>--post-url URL</code></td> - <td> - <p>创建 XPI 文件后，将扩展 post 到这个URL。</p> - - <pre> -<code>jpm watchpost --post-url http://localhost:8888/</code></pre> - - <p>查看 <a href="https://www.npmjs.com/package/jpm#using-post-and-watchpost">Using Post 和 Watchpost</a> 获取更多信息。</p> - </td> - </tr> - <tr> - <td><code>-v --verbose</code></td> - <td> - <p>打印详细信息：</p> - - <pre> -<code>jpm watchpost --post-url http://localhost:8888/ -v</code></pre> - </td> - </tr> - </tbody> -</table> - -<h3 id="jpm_sign">jpm sign</h3> - -<p>此特性仅从 jpm 1.0.4 起被支持。</p> - -<p>此命令为你的附加组件重新生成一个新的被Mozilla签名的 <a href="https://developer.mozilla.org/en-US/docs/XPI">XPI</a> 文件。这就允许你<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#Supporting_updates_for_self-hosted_add-ons">自己托管你的 add-on</a>，这样用户可以在安装时避免 <a href="https://wiki.mozilla.org/Add-ons/Extension_Signing">signed add-ons are required</a> 错误。在用这个命令之前，你需要<a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">在 addons.mozilla.org 创建 API 证书</a>。</p> - -<p>你可以为你已经生成的 XPI 文件签名，就像如下，通过传递 XPI 文件给 <code>--xpi</code>参数：</p> - -<pre id="comment_text_2"><code>jpm sign --api-key ${AMO_API_KEY} --api-secret ${AMO_API_SECRET} --xpi <xpi file></code></pre> - -<p>或者，你可以省略 <code>--xpi</code> 参数，这样 <code>jpm sign</code> 会从当前目录（或者 <code>--addon-dir</code>）生成一个XPI文件。</p> - -<pre><code>jpm sign --api-key ${AMO_API_KEY} --api-secret ${AMO_API_SECRET}</code></pre> - -<p>上面提交了一个 <a href="https://developer.mozilla.org/en-US/docs/XPI/">XPI</a> 到 <a href="https://addons.mozilla.org/">addons.mozilla.org</a> <a href="http://olympia.readthedocs.org/en/latest/topics/api/signing.html">签名g API</a>，如果通过验证，然后下载一个签名后的 XPI 文件到工作目录。</p> - -<p>下面是一些运行 <code>sign</code> 命令的结果：</p> - -<ul> - <li>你的 add-on 通过验证，被 Mozilla 签名，并且一个新的签名后的 <a href="https://developer.mozilla.org/en-US/docs/XPI">XPI</a> 文件被下载到你的工作目录。</li> - <li>你的 add-on 没有通过验证，没有签名，你获取到一个详细报告的链接。修复验证错误以后，你可以再次运行这个命令。</li> - <li>你的 add-on 公公验证，但是它不能自动签名，因为你的 add-on 是<a href="https://developer.mozilla.org/en-US/Add-ons/Distribution">列表上的</a>。列表上的 add-ons 需要人工复核才能被签名。</li> - <li>你的 add-on 已经存在某个版本号了，所以它没有被签名。增加 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json">package.json</a> 文件中的版本号并且再次运行命令。</li> -</ul> - -<p>在底层，<code>jpm sign</code> 在<a href="https://addons.mozilla.org/">addons.mozilla.org</a>里创建了一个不会被列出的附加组件，这就意味着你必须自己把XPI文件分发给你的用户来安装。如果你需要创建一个在列表中的附加组件，只要<a href="https://addons.mozilla.org/en-US/developers/addon/submit/2">直接将它提交到 addons.mozilla.org</a>，在那里它自动会被签名。如果你在安装一个已签名的附加组件时遇到困难，参看<a href="https://developer.mozilla.org/en-US/docs/Extension_Versioning%2C_Update_and_Compatibility#Debugging_and_solving_problems">调试</a>一节。</p> - -<p><code>jpm sign</code> 接收以下参数：</p> - -<table> - <tbody> - <tr> - <td><code>--api-key=API_KEY</code></td> - <td> - <p><a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org key管理页面</a>生成的API访问key（字符串）。</p> - </td> - </tr> - <tr> - <td><code>--api-secret=API_SECRET</code></td> - <td> - <p><a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org key 管理页面</a>生成的API访问密钥（字符串）。这个值应该被小心保密并且永远不要记录到版本控制中。如果你的密钥被破解，另一个开发者就能上传附加组件到你的账号上。你应该立即撤销泄露的API证书并且重新生成一份。</p> - </td> - </tr> - <tr> - <td><code>--api-url-prefix=http://.../api</code></td> - <td> - <p>可选的API URL前缀，如果你想使用一个试用签名的API。</p> - - <p>例如，你可以通过<code>https://addons-dev.allizom.org/api/v3</code>的认证来使用<a href="https://addons.mozilla.org/">addons.mozilla.org</a>的开发者版本。</p> - </td> - </tr> - <tr> - <td><code>--xpi=/path/to/file.xpi</code></td> - <td> - <p>需要签名的<a href="https://developer.mozilla.org/en-US/docs/XPI">XPI</a>文件。如果没指定文件，一个新的XPI会在当前目录（或者<code>--addon-dir</code>）中生成。</p> - </td> - </tr> - </tbody> -</table> - -<h2 id="一些技巧">一些技巧</h2> - -<h3 id="选择浏览器版本">选择浏览器版本</h3> - -<p>默认地，<code>jpm run</code> 和 <code>jpm test</code> 运行 release 版本的 FireFox。你可以有一两种办法来告诉 jpm 使用一个不同的版本：</p> - -<ul> - <li> - <p>你可以使用 <code>-b</code> 或者 <code>--binary</code> 选项来告诉 jpm 去使用一个不同版本的 Firefox。你可以提供一个指定二进制文件的路径：</p> - - <pre><code>jpm run -b /path/to/Firefox/Nightly</code></pre> - - <p>有个简化的方法，你可以传递"nightly"、"aurora"、"beta"或者"firefox"然后jpm会在默认位置寻找这些 Firefox 的版本：</p> - - <pre><code>jpm run -b nightly</code></pre> - </li> - <li> - <p>你可以设置 <code>JPM_FIREFOX_BINARY</code> 环境变量为你想运行的 Firefox 版本的路径。在你调用 <code>jpm run</code> 或 <code>jpm test</code> 而不带 <code>-b</code> 选项时，jpm 首先检查 <code>JPM_FIREFOX_BINARY</code>，并且将其当做已设置的路径来用。</p> - </li> -</ul> - -<h3 id="使用_.jpmignore_来忽略文件">使用 <code>.jpmignore</code> 来忽略文件</h3> - -<p>使用 <code>.jpmignore</code> 就像使用 <code>git</code> 的<code>.gitignore</code>，Mercurial 的 <code>.hgignore</code>，或者 npm 的 <code>.npmignore</code>。通过使用这个文件，你可以在使用 <code>jpm xpi</code> 编译 <code>.xpi</code> 文件时，让 <code>jpm</code> 知道你想要忽略哪些文件。</p> - -<p>这是个例子：</p> - -<pre><code># Ignore .DS_Store files created by mac -.DS_Store - -# Ignore any zip or xpi files -*.zip -*.xpi</code></pre> - -<p>有着以上内容的 <code>.jpmignore</code> 文件会忽略所有的 zip 文件和 <code>.DS_Store</code> 文件，这些文件不会包括在 <code>jpm xpi</code> 所生成的 xpi 文件中。</p> - -<h3 id="使用配置"><a name="Using_profiles">使用配置</a></h3> - -<p>默认地，<code>jpm run</code> 每次都会使用一个新的配置。这就意味着前一次运行 <code>jpm</code> 时的任何配置，默认都不会在下一次中使用。</p> - -<p>这其中包括，比如你安装的任何附加组件，或者你的历史记录，或者任何使用 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/simple-storage">simple-storage</a> API 存储的数据。</p> - -<p>为了让 <code>jpm</code> 使用一个特定的配置，传递 <code>--profile</code> 选项，设定你想使用的配置文件的名字，或者是配置文件的路径。</p> - -<pre><code>jpm run --profile boogaloo</code></pre> - -<pre><code>jpm run --profile path/to/boogaloo</code></pre> - -<p>如果你提供了 <code>--profile</code> 但是它的参数不是一个已有配置文件的名字或路径，jpm 会打开 <a href="https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles">配置文件管理器</a> 让你选择一个已有的配置文件或者创建一个新的配置文件：</p> - -<pre><code>jpm run --profile i-dont-exist</code></pre> - -<h3 id="开发时不用重启浏览器">开发时不用重启浏览器</h3> - -<p>因为每次调用 <code>jpm run</code> 时都会重启浏览，如果你十分频繁地修改附加组件，这就可能有点笨重了。一个替代的开发模型是使用 <a href="https://addons.mozilla.org/en-US/firefox/addon/autoinstaller/" rel="noreferrer">扩展自动安装器</a>附加组件：它会在特定端口监听新 XPI 文件并且自动安装它们。这样，你就能测试新的改动，而不用重启浏览器：</p> - -<ul> - <li>修改附件组件</li> - <li>运行 <code>jpm post --post-url http://localhost:8888/</code>，来创建 XPI 文件并提交。</li> -</ul> - -<p>你甚至可以用一个简单的脚本来自动化这一工作流程。例如：</p> - -<pre><code>jpm watchpost --post-url http://localhost:8888/</code></pre> - -<p>注意，比起使用 <code>jpm run</code> 运行附加组件时的日志级别，你在使用这个方法时控制台定义的日志级别是不一样的。这意味着，如果你想看到 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Logging" rel="noreferrer"><code>console.log()</code></a> 消息的输出，你必须微调一下配置。查看 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/console#Logging_Levels" rel="noreferrer">logging levels</a> 文档以获取这方面的详细信息。</p> - -<h3 id="重载内建模块">重载内建模块</h3> - -<p>你用来实现你的附加组件的SDK模快是 Firefox 内建的。当你使用 <code>jpm run</code> 或 <code>jpm xpi</code> 来运行或者打包附加组件时，附加组件使用其所在的 Firefox 版本中的模块版本。</p> - -<p>作为附件组件开发者，这一般就是你想要的。但是如果你在开发 SDK 模块本身，这就不合适了。这时你需要：</p> - -<ul> - <li>获取你想要的 SDK 模块的本地拷贝：一般来说就是从 <a href="https://github.com/mozilla/addon-sdk" rel="noreferrer">GitHub 仓库</a>中检出SDK。</li> - <li>设置 <code>JETPACK_ROOT</code> 环境变量，指向你的本地拷贝</li> - <li>传递 <code>-o</code> 选项到 <code>jpm run</code> 或 <code>jpm xpi</code>：</li> -</ul> - -<pre><code>jpm run -o</code></pre> - -<p>这会通知 jpm 去使用 SDK 模块的本地拷贝，而不是 Firefox 内部的模块。如果你不想设置 <code>JETPACK_ROOT</code> 环境变量，你可以使用 <code>-o</code> 传递SDK模块本地拷贝的位置：</p> - -<pre><code>jpm run -o "/path/to/addon-sdk/"</code></pre> - -<p>路径必须是一个绝对路径并且指向 SDK 的根目录（不是 addon-sdk/sdk 或 addon-sdk/sdk/lib）。</p> - -<h3 id="支持自托管附加组件的更新">支持自托管附加组件的更新</h3> - -<p>此特性仅被 jpm 1.0.3 及之后版本支持，</p> - -<p>当你给你的附加组件来添加特性或者修复 bug 时，你想让之前安装好的附加组件将自己从老版本更新到新版本。</p> - -<p>如果你在 <a href="https://addons.mozilla.org/">addons.mozilla.org</a> 上列出你的附加组件，那么你要做的只是提交一个新的版本；附加组件默认会检查它们在 <a href="https://addons.mozilla.org/">addons.mozilla.org</a> 上的新版本。好了，你不用继续往下看这一节了。</p> - -<p>如果你没有在 <a href="https://addons.mozilla.org/">addons.mozilla.org</a> 上列出你的附加组件，你需要生成一个 Mozilla 签名的 XPI 文件并告诉 Firefox 哪里可以找到这个附加组件的新版本。方法就是：</p> - -<ul> - <li>每次你想要创建一个新版本时，你运行 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_sign">jpm sign</a></li> - <li>当你需要更新时，更新由你托管的签名好的附加组件</li> - <li>你维护一个“更新清单”，包含了指向那个 XPI 的URL</li> - <li>你的附加组件告诉 Firefox 哪里可以找到更新清单</li> -</ul> - -<p>为了达到这个目的，package.json中需要包含两个额外的key ：</p> - -<ul> - <li><code><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#updateURL">updateURL</a></code>：这个 URL 包含在 <code>jpm xpi</code> 所编译的 XPI 文件的<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Install_Manifests">安装清单</a>中。他指向了你的更新清单。<code>updateURL</code> 值<em>可以</em>是HTTPS的。如果不是，那么你也可以签名的更新清单，并且使用 package.json 文件中的 <code><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#updateKey">updateKey</a></code> 字段来包含其公钥。参看 <a href="https://developer.mozilla.org/en-US/docs/Extension_Versioning%2C_Update_and_Compatibility#Securing_Updates">安全地更新</a> 以获取这方面更多信息</li> - <li><code><a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/package_json#updateLink">updateLink</a></code>：这个 URL 包含在那个更新清单文件中。它指向了 XPI，并且<em>必须</em>是一个 HTTPS URL。</li> -</ul> - -<p><img alt="" src="https://mdn.mozillademos.org/files/11847/addons-update.svg" title="[https://mdn.mozillademos.org]"></p> - -<p>如果你设置了 <code>updateURL</code> 和 <code>updateLink</code>（如果 <code>updateKey</code> 不是 HTTPS 的，那也要包括 <code>updateKey</code>），那么 <code>jpm xpi</code> 会：</p> - -<ul> - <li>生成 XPI 文件时将 <code>updateURL</code> 设置为你提供的值。</li> - <li>和 XPI 文件一起，生成更新清单，并将清单中的 <code>updateURL</code> 设置为你提供的值。</li> -</ul> - -<p>然后你将更新清单托管到 <code>updateURL</code>，并且将新版 XPI 托管到 <code>updateLink</code>。</p> - -<p>获取更多这方面的详细信息，参看<a href="https://developer.mozilla.org/en-US/docs/Extension_Versioning,_Update_and_Compatibility#Automatic_Add-on_Update_Checking">自动检查附件组件更新</a>。</p> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tools/package_json/index.html b/files/zh-cn/mozilla/add-ons/sdk/tools/package_json/index.html deleted file mode 100644 index cd08ff2b64..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tools/package_json/index.html +++ /dev/null @@ -1,312 +0,0 @@ ---- -title: package.json -slug: Mozilla/Add-ons/SDK/Tools/package_json -translation_of: Archive/Add-ons/Add-on_SDK/Tools/package_json ---- -<p>{{AddonSidebar}}</p> - -<p><span class="seoSummary">The <code>package.json</code> file contains manifest data for your add-on, providing not only descriptive information about the add-on for presentation in the Add-ons Manager, but other metadata required of add-ons.</span></p> - -<p>一些条目, 比如<a href="/en-US/Add-ons/SDK/Tools/package_json#icon"><code>icon</code></a>, <a href="/en-US/Add-ons/SDK/Tools/package_json#name"><code>name</code></a>和<a href="/en-US/Add-ons/SDK/Tools/package_json#description"><code>description</code></a>, 有类似<a href="https://developer.mozilla.org/en-US/docs/Install_Manifests">install manifest</a>的格式, 并且<code>package.json会写入</code>install manifest, 当使用<a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_xpi"><code>jpm xpi</code></a><code>的时候.</code></p> - -<p>Others, such as <a href="/en-US/Add-ons/SDK/Tools/package_json#lib"><code>lib</code></a>, <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions"><code>permissions</code></a>, and <a href="/en-US/Add-ons/SDK/Tools/package_json#preferences"><code>preferences</code></a>, represent instructions to the <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a> tool itself to generate and include particular code and data structures in your add-on.</p> - -<p>其他如<a href="/en-US/Add-ons/SDK/Tools/package_json#lib"><code>lib</code></a>, <a href="/en-US/Add-ons/SDK/Tools/package_json#permissions"><code>permissions</code></a>和<a href="/en-US/Add-ons/SDK/Tools/package_json#preferences"><code>preferences</code></a>表示使用<a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>工具的步骤, 生成你扩展包含的特殊代码和数据结构.</p> - -<h2 id="创建manifest">创建manifest</h2> - -<p><code>package.json起初是通过运行</code><a href="/en-US/Add-ons/SDK/Tools/jpm#jpm_init"><code>jpm init</code></a>生成的<code>,通常在扩展的根目录.比如下面(假设扩展目录是</code>"my-addon"<code>)</code></p> - -<pre class="brush: json">{ - "name": "my-addon", - "title": "my-addon", - "id": "jid1-1FERGV45e4f4f", - "description": "a basic add-on", - "author": "", - "license": "MPL-2.0", - "version": "0.1" -}</pre> - -<p>如果你使用新的<a href="/en-US/Add-ons/SDK/Tools/jpm">jpm tool</a>话,可以方便的从package.json获取manifest数据, 通过require其他模块的方式:</p> - -<pre class="brush: js" id="comment_text_1">var title = require("./package.json").title;</pre> - -<h2 id="Key_reference">Key reference</h2> - -<p><code>package.json</code> may contain the following keys:</p> - -<table class="standard-table"> - <tbody> - <tr> - <td id="author"><code>author</code></td> - <td> - <p>The name of the package's original author; this could be the name of a person or a company. Defaults to an empty string. It may include a optional URL in parentheses and an email address in angle brackets.</p> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#creator"><code>em:creator</code></a> element in the <code>install.rdf</code> file generated by <code>cfx</code>.</p> - - <div class="note"><strong>Note:</strong> <a href="https://developer.mozilla.org/Add-ons/SDK/Tools/jpm">jpm</a> supports <a href="https://docs.npmjs.com/files/package.json#people-fields-author-contributors">NodeJS people fields</a>.</div> - </td> - </tr> - <tr> - <td id="contributors"><code>contributors</code></td> - <td> - <p>An array of additional <a href="/en-US/Add-ons/SDK/Tools/package_json#author"><code>author</code></a> strings, identifying other contributors to the add-on.</p> - - <p>These values will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#contributor"><code>em:contributor</code></a> elements in its <code>install.rdf</code>.</p> - - <div class="note"><strong>Note:</strong> This is deprecated along with <code>cfx</code>; it's not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</div> - </td> - </tr> - <tr> - <td id="dependencies"><code>dependencies</code></td> - <td> - <p>A string or an array of strings specifying the names of packages that this add-on requires in order to function properly.</p> - </td> - </tr> - <tr> - <td id="description"><code>description</code></td> - <td> - <p>The add-on's description; this is a human-readable message describing what the add-on does. This defaults to the text "a basic add-on".</p> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#description"><code>em:description</code></a> element in its <code>install.rdf</code>.</p> - </td> - </tr> - <tr> - <td id="engines"><code>engines</code></td> - <td> - <p>Object with supported applications (key) and required version numbers (value).</p> - - <ul> - <li><code>firefox</code>: Firefox Desktop</li> - <li><code>fennec</code>: Firefox for Android</li> - </ul> - - <p>Example:</p> - - <pre> -<code> "engines": { - "firefox": ">=38.0a1", - "fennec": ">=38.0a1" - }</code></pre> - </td> - </tr> - <tr> - <td id="fullName"><code>fullName</code> {{deprecated_inline}}</td> - <td> - <div class="note"><strong>Note:</strong> This is deprecated along with <code>cfx</code>; it's not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</div> - - <p>The full name of the package. It can contain spaces.</p> - - <p>If this key is present its value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#name"><code>em:name</code></a> element in its <code>install.rdf</code>.</p> - </td> - </tr> - <tr> - <td id="harnessClassID"><code>harnessClassID</code> {{deprecated_inline}}</td> - <td> - <div class="note"><strong>Note:</strong> This is deprecated along with <code>cfx</code>; it's not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</div> - - <p>String in the <a href="https://developer.mozilla.org/en-US/docs/Generating_GUIDs">GUID format</a>.</p> - - <p>This is used as a <a href="https://developer.mozilla.org/en-US/docs/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID"><code>classID</code></a> of the "harness service" XPCOM component. Defaults to a random GUID generated by <code>cfx</code>.</p> - </td> - </tr> - <tr> - <td id="homepage"><code>homepage</code></td> - <td> - <p>The URL of the add-on's website.</p> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#homepageURL"><code>em:homepageURL</code></a> element in its <code>install.rdf</code>.</p> - </td> - </tr> - <tr> - <td id="icon"><code>icon</code></td> - <td> - <p>The path to an image file containing the icon for the add-on. Defaults to <code>icon.png</code>. If no icon is specified, the standard add-on icon will be used by default.</p> - - <div class="warning"> - <p>When using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>, relative path to the data directory (to make it re-usable for add-on HTML content) does not currently work. Instead you have to use following syntax:</p> - - <p>resource://ID/data/icon-name.png</p> - - <p>ID is the value from the <code>id </code>field. If it does <strong>not</strong> begin with the <code>@</code>-character, then <code>@</code> has to be escaped as <code>-at-</code> and <code>.</code> as <code>-dot-</code>. If the ID is a GUID, the curly braces used in the <code>id</code> field are <strong>not</strong> included.</p> - </div> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#iconURL"><code>em:iconURL</code></a> element in its <code>install.rdf</code>.</p> - - <p>The icon may be up to 48x48 pixels in size (although a bigger icon is tolerated here too)</p> - </td> - </tr> - <tr> - <td id="icon64"><code>icon64</code> {{deprecated_inline}}</td> - <td> - <div class="note"> - <p><strong>Note:</strong> This is deprecated along with <code>cfx</code>; it's not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - - <p><span style="background-color: rgba(212, 221, 228, 0.14902);">The path to an image</span> containing the large icon for the add-on. Defaults to <code>icon64.png</code>. If you don't provide an icon here, the same icon as specified by <code>icon</code> will be used.</p> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#icon64URL"><code>em:icon64URL</code></a> element in its <code>install.rdf</code>.</p> - - <p>The icon may be up to 64x64 pixels in size.</p> - </td> - </tr> - <tr> - <td id="id"><code>id</code></td> - <td> - <p>A globally unique identifier for the add-on.</p> - - <p>This value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#id"><code>em:id</code></a> element in its <code>install.rdf</code>.</p> - - <p>See the <a href="/en-US/Add-ons/SDK/Guides/Program_ID">Program ID documentation</a>.</p> - </td> - </tr> - <tr> - <td><code>lib</code></td> - <td> - <p>String representing the top-level module directory provided in this add-on. Defaults to "lib".</p> - - <div class="note"> - <p><strong>Note:</strong> This is deprecated along with <code>cfx</code> and is not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="license"><code>license</code></td> - <td> - <p>The name of the license under which the add-on is distributed, with an optional URL in parentheses. Defaults to <code>"MPL-2.0"</code>.</p> - - <div class="note"> - <p><strong>Note</strong>: It is recommend that you use an <a href="https://spdx.org/licenses/">SPDX license ID</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="main"><code>main</code></td> - <td> - <p>A string representing the name of a program module that is located in one of the top-level module directories specified by <a href="/en-US/Add-ons/SDK/Tools/package_json#lib"><code>lib</code></a>. Defaults to <code>"main"</code>.</p> - </td> - </tr> - <tr> - <td id="name"><code>name</code></td> - <td> - <p>The add-on's name. This name cannot contain spaces or periods, and defaults to the name of the parent directory.</p> - - <p>When the add-on is built as an XPI, if the <a href="/en-US/Add-ons/SDK/Tools/package_json#fullName"><code>fullName</code></a> and <a href="/en-US/Add-ons/SDK/Tools/package_json#title"><code>title</code></a> keys are not present, <code>name</code> is used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#name"><code>em:name</code></a> element in its <code>install.rdf</code>.</p> - </td> - </tr> - <tr> - <td id="packages"><code>packages</code></td> - <td> - <div class="note"> - <p><strong>Note:</strong> This is deprecated along with <code>cfx</code> and is not available when using <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - - <p>A string pointing to a directory containing additional packages. Defaults to <code>"packages"</code>.</p> - </td> - </tr> - <tr> - <td id="permissions"><code>permissions</code></td> - <td> - <p>A set of permissions that the add-on needs.</p> - - <p><strong><code>private-browsing</code></strong>: a boolean indicating whether or not the add-on supports private browsing. If this value is not <code>true</code> or is omitted, then the add-on will not see any private windows or objects, such as tabs, that are associated with private windows. See the documentation for the <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing"><code>private-browsing</code> module</a>.</p> - - <p><strong><code>cross-domain-content</code></strong>: a list of domains for which content scripts are given cross-domain privileges to access content in iframes or to make XMLHTTPRequests. See the documentation for <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts/Cross_Domain_Content_Scripts">enabling cross-domain content scripts</a>.</p> - - <p><strong><code>multiprocess</code></strong>: a Boolean value declaring whether this add-on is, or is not, compatible with <a href="/en-US/Add-ons/Working_with_multiprocess_Firefox">multiprocess Firefox</a>.</p> - - <div class="note"> - <p><strong>Note</strong> the <code>multiprocess</code> permission is not supported by <a href="/en-US/Add-ons/SDK/Tools/cfx">cfx</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="preferences"><code>preferences</code></td> - <td> - <p>An array of <a href="/en-US/docs/Glossary/JSON">JSON</a> objects that use the following keys: <code>name</code>,<code>type</code>, <code>value</code>, <code>title</code>, and <code>description</code>. These JSON objects will be used to create a preferences interface for the add-on in the Add-ons Manager.</p> - - <p>See the documentation for the <a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-prefs"><code>simple-prefs</code> module</a>.</p> - </td> - </tr> - <tr> - <td id="preferences-branch"><code>preferences-branch</code></td> - <td>Use this to specify an alternative branch for your add-on's simple-prefs. See <a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-prefs#Simple-prefs_in_the_preferences_system">"Simple-prefs in the preferences system"</a> for more details.</td> - </tr> - <tr> - <td id="title"><code>title</code></td> - <td> - <p>The human-readable title of the package; this can contain spaces.</p> - - <p>If this key is present its value will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#name"><code>em:name</code></a> element in its <code>install.rdf</code>.</p> - </td> - </tr> - <tr> - <td id="translators"><code>translators</code></td> - <td> - <p>An array of strings listing the people who contributed to the localization of this add-on.</p> - - <p>These values will be used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#translator"><code>em:translator</code></a> elements in its <code>install.rdf</code>.</p> - - <div class="note"><strong>Note:</strong> <a href="https://developer.mozilla.org/Add-ons/SDK/Tools/jpm">jpm</a> supports <a href="https://docs.npmjs.com/files/package.json#people-fields-author-contributors">NodeJS people fields</a>.</div> - </td> - </tr> - <tr> - <td id="unpack"><code>unpack</code></td> - <td> - <p>Same as the <code><a href="/en-US/Add-ons/Install_Manifests#unpack">unpack</a></code> in an <code>install.rdf</code> file.</p> - - <p>Useful when the extension contains binaries.</p> - </td> - </tr> - <tr> - <td id="updateKey"><code>updateKey</code></td> - <td> - <p>Same as the <code><a href="/en-US/Add-ons/Install_Manifests#updateKey">updateKey</a></code> in an <code>install.rdf</code> file.</p> - - <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Supporting_updates_for_self-hosted_add-ons">Supporting updates for self-hosted add-ons</a>.</p> - - <div class="note"> - <p><strong>Note:</strong> This key is only available with <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="updateLink"><code>updateLink</code></td> - <td> - <p>Same as the <code><a href="/en-US/docs/Extension_Versioning%2C_Update_and_Compatibility#Securing_Updates">updateLink</a></code> for an <code>update.rdf</code> file. Previously was <code><a href="/en-US/Add-ons/SDK/Tools/cfx#updateURL_and_updateLink">--update-link in cfx</a></code>.</p> - - <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Supporting_updates_for_self-hosted_add-ons">Supporting updates for self-hosted add-ons</a>.</p> - - <div class="note"> - <p><strong>Note:</strong> This key is only available with <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="updateURL"><code>updateURL</code></td> - <td> - <p>Same as the <code><a href="/en-US/Add-ons/Install_Manifests#updateURL">updateURL</a></code> for an <code>install.rdf</code> file.</p> - - <p>See <a href="/en-US/Add-ons/SDK/Tools/jpm#Supporting_updates_for_self-hosted_add-ons">Supporting updates for self-hosted add-ons</a>.</p> - - <div class="note"> - <p><strong>Note:</strong> This key is only available with <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a>.</p> - </div> - </td> - </tr> - <tr> - <td id="version"><code>version</code></td> - <td> - <p>String representing the version of the add-on. Defaults to "0.0.1".</p> - - <p>This value is used as the add-on's <a href="https://developer.mozilla.org/en-US/docs/Install_Manifests#version"><code>em:version</code></a> element in its <code>install.rdf</code>.</p> - - <div class="note"> - <p><strong>Note:</strong> For <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a> the version must be a valid <a href="http://semver.org/">semver</a>.</p> - </div> - </td> - </tr> - </tbody> -</table> - -<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/add_a_menu_item_to_firefox/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/add_a_menu_item_to_firefox/index.html deleted file mode 100644 index 29348bbabb..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/add_a_menu_item_to_firefox/index.html +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Add a Menu Item to Firefox -slug: Mozilla/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Add_a_Menu_Item_to_Firefox ---- -<div class="note"> - <p>学习本模块你需要 <a href="/en-US/Add-ons/SDK/Installation">安装SDK</a> 学习基础工具<a href="/en-US/Add-ons/SDK/Getting_Started_With_cfx"><code>cfx</code></a>.</p> -</div> -<div class="note"> - <p>如果你使用 <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a> 替代cfx, 使用第三方模块的方式是不同的, 你应该阅读 <a href="/en-US/Add-ons/SDK/Tutorials/Using_third-party_modules_%28jpm%29">jpm</a>的相应版本替代本教程.</p> - <p>给予Python可能未来废弃，使用JPM基于nodejs(译者备注).</p> -</div> -<p class="ordinary-output target-output"><span>SDK还不能为<span>火狐浏览器</span>提供一个API添加新的菜单项。</span><span>但它是可扩展的设计，所以任何人都可以建立和发布模块，使用插件开发者。</span><span>幸运的是</span><span>，</span><span>埃里克</span><span>沃尔德</span><span>写的</span><a href="https://github.com/mykmelez/menuitems-jplib"><span>MenuItems</span></a><span>模块，</span><span>能够使我们</span><span>添加菜单项</span><span>。</span></p> -<p class="ordinary-output target-output"><span>本教程有双重的责任。</span><span>它描述的一般</span><span>方法，</span><span>使用一个外部的</span><span>，</span><span>在你的</span><span>插件</span><span>的第三方</span><span>模块</span><span>，</span><span>并</span><span>描述了如何</span><span>使用</span><span>特别的</span><span>MenuItems</span><span>模块</span><span>添加一个菜单项</span><span>。</span></p> -<p class="ordinary-output target-output"><span>首先，创建一个新的扩展程序。</span><span>创建一个</span><span>目录名称为</span><span>“</span><span>clickme</span><span>”</span><span>（名称随意）</span><span>，</span><span>找到它并运行</span><code>cfx init</code><span>初始化</span><span>。</span></p> -<pre>mkdir clickme -cd clickme -cfx init -</pre> -<p>通常将创建目录结构：</p> -<ul> - <li>clickme - <ul> - <li>data</li> - <li>docs - <ul> - <li>main.md</li> - </ul> - </li> - <li>lib - <ul> - <li>main.js</li> - </ul> - </li> - <li>package.json</li> - <li>README.md</li> - <li>tests - <ul> - <li>test-main.js</li> - </ul> - </li> - </ul> - </li> -</ul> -<div> - </div> -<h2 id="安装_menuitems"><code>安装 menuitems</code></h2> -<p>在 "clickme"下创建一个名称为"packages"的目录. 从 <a href="https://github.com/mykmelez/menuitems-jplib/zipball/4d6ae5b410d79cc16c9c76920fbaa8a367e44ca7">https://github.com/mykmelez/menuitems-jplib</a> 下载 <code>menuitems 并展开到刚才创建的</code>"packages" 目录下:</p> -<pre>mkdir packages -cd packages -tar -xf ../erikvold-menuitems-jplib-d80630c.zip -</pre> -<h2 id="模块依赖">模块依赖</h2> -<p class="ordinary-output target-output"><span>如果</span><span>第三方模块</span><span>只</span><span>取决于</span><span>SDK</span><span>模块</span><span>，</span><span>你</span><span>可以马上</span><span>使用它们</span><span>，</span><span>但如果</span><span>他们依赖于其他</span><span>第三方模块</span><span>，</span><span>你需要安装</span><span>的</span><span>依赖</span><span>以及</span><span>。</span></p> -<p><span class="high-light-bg">在软件包的主目录，你会发现一个叫做</span> "package.json"的文件. <span>打开它，看看一个</span>名称"dependencies"的入口. <code>menuitems</code> 包的入口:</p> -<pre>"dependencies": ["vold-utils"] -</pre> -<p>这告诉我们需要安装 <code>vold-utils</code> 包, 我们可以从<a href="https://github.com/mykmelez/vold-utils-jplib/zipball/a321447dc5d613df33023165854957c181dc3174">https://github.com/mykmelez/vold-utils-jplib</a> 下载，并添加到 <code>packages</code> 目录<code>下的旁边的menuitems</code>.</p> -<h2 id="使用menuitems"><code>使用menuitems</code></h2> -<p> <a href="https://github.com/mykmelez/menuitems-jplib/blob/master/docs/menuitems.md"><code>Menuitems</code>模块文档</a> <code>告诉使用MenuItem()创建一个新的菜单项</code>. <code>MenuItem()可接受的附加选项</code>, 我们将使用最迷你的配置:</p> -<ul> - <li><code>id</code>: 菜单项标示符</li> - <li><code>label</code>:菜单项线上的文本</li> - <li><code>command</code>: 用户选择菜单项的响应函数</li> - <li><code>menuid</code>: 菜单项的父类标示符</li> - <li><code>insertbefore</code>: 我们希望出现的标示符之前的位置</li> -</ul> -<div> - <div> - <pre class="brush: js">var menuitem = require("menuitems").Menuitem({ - id: "clickme", - menuid: "menu_ToolsPopup", - label: "Click Me!", - onCommand: function() { - console.log("clicked"); - }, - insertbefore: "menu_pageInfo" -});</pre> - <div> - </div> - </div> -</div> -<p>接下来, 我们将<code>声明menuitems</code>的依赖包. 在你的add-on's <code>package.json文件添加一行</code>:</p> -<pre>"dependencies": "menuitems" -</pre> -<p>Note that due to <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=663480">bug 663480</a>, if you add a <code>dependencies</code> line to <code>package.json</code>, and you use any modules from the SDK, then you must also declare your dependency on that built-in package, like this:</p> -<pre>"dependencies": ["menuitems", "addon-sdk"] -</pre> -<p class="ordinary-output target-output"><span>现在我们要做的。</span><span>运行</span><span>插件</span><span>，</span><span>你会</span><span>看到新的项目</span><span>出现在工具</span><span>菜单：</span><span>选择它，</span><span>你会看到</span><code>info: clicked </code><span>出现在</span><span>控制台</span><span>。</span></p> -<h2 id="Caveats">Caveats</h2> -<p class="ordinary-output target-output"><span>第三方</span><span>模块</span><span>使用</span><span>不直接支持的</span><span>SDK功能</span><span>的好方法，</span><span>但由于</span><span>第三方模块</span><span>通常使用</span><span>低级别的</span><span>API</span><span>，</span><span>它们可以通过</span><span>Firefox的</span><span>新版本</span><span>了</span><span>。</span></p> -<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/adding_a_button_to_the_toolbar/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/adding_a_button_to_the_toolbar/index.html deleted file mode 100644 index 8e4438f818..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/adding_a_button_to_the_toolbar/index.html +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: 在工具栏上添加按钮 -slug: Mozilla/Add-ons/SDK/Tutorials/Adding_a_Button_to_the_Toolbar -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Adding_a_Button_to_the_Toolbar ---- -<div class="note"> -<p>动手之前，必须先<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/安装">安装SDK</a>并学习<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_With_cfx"><code>cfx</code>基础</a>.</p> - -<p>这篇教程使用<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>API，需要Firefox 29或更新版本。</p> -</div> - -<p>如果要给工具栏添加一个按钮，需要使用<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>或<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">切换按钮</a>模块。</p> - -<p>新建一个目录，打开它，执行<code>cfx init</code>。</p> - -<p>然后，把这三个图标保存到data文件夹：</p> - -<table class="standard-table"> - <tbody> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7635/icon-16.png" style="height: 16px; width: 16px;"></td> - <td>icon-16.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7637/icon-32.png" style="height: 32px; width: 32px;"></td> - <td>icon-32.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7639/icon-64.png" style="height: 64px; width: 64px;"></td> - <td>icon-64.png</td> - </tr> - </tbody> -</table> - -<p>随后打开lib目录下的main.js文件，添加如下代码：</p> - -<pre class="brush: js">var buttons = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = buttons.ActionButton({ - id: "mozilla-link", - label: "Visit Mozilla", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -function handleClick(state) { - tabs.open("https://www.mozilla.org/"); -}</pre> - -<p>现在输入<code>cfx run</code>来执行附加组件。按钮添加到了浏览器顶部的工具栏上：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7641/mozilla-button.png" style="display: block; height: 221px; margin-left: auto; margin-right: auto; width: 382px;">你无法设置按钮的初始位置，但是用回可以使用浏览器的自定义功能移动它。其中的<code>id</code>属性是必需的，用来记录按钮的位置，因此，你最好不要在后续版本中修改它。</p> - -<p>单击按钮，<a href="https://www.mozilla.org/en-US/">https://www.mozilla.org/</a>将会在新的标签页中加载。</p> - -<h2 id="设定图标">设定图标</h2> - -<p>icon属性可以设定单个或是一组不同大小图标。如果你用的是一组不同大小的图标，浏览器将会自动选择最适合当前屏幕分辨率的，然后显示在浏览器界面的按钮上。<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#ActionButton(options)">更多内容，参考设定多个图标</a>。</p> - -<p>图标文件必须打包在附加组件内：它不可以指向一个远程文件。</p> - -<p>你只要正确地设置了按钮的<code>icon</code>属性，它就会立刻生效。你可以改变全局的，在特定窗口的或者是特定标签页中显示的图标或者是其他状态属性。<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action#Updating_state">更多内容，参考更新状态</a>。</p> - -<h2 id="附加一个面板">附加一个面板</h2> - -<p>如果你想把一个面板附加到按钮上，使用<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">切换按钮</a>API。这就和动作按钮API类似，只不过多了一个boolean值属性，表示按钮是否被<code>checked</code>。附加面板，要把按钮传递给面板的<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/panel#show(options)"><code>show()</code></a>方法。<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle#Attaching_panels_to_buttons">更多细节，参考切换按钮文档</a>。</p> - -<h2 id="显示更多样的内容">显示更多样的内容</h2> - -<p>添加按钮做不到的复杂界面功能，需要使用<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_toolbar">工具栏</a>API。 使用工具栏API你可以得到一个用户界面内容的水平条。可以添加按钮或者是可以包含HTML，CSS，javaScript的<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_frame">frame</a>到工具栏上。</p> - -<h2 id="进一步学习">进一步学习</h2> - -<ul> - <li><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮参考</a></li> - <li><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">切换按钮参考</a></li> - <li><a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_toolbar">工具栏参考</a></li> -</ul> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/implementing_the_widget/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/implementing_the_widget/index.html deleted file mode 100644 index 04e4a75d23..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/implementing_the_widget/index.html +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: 实现控件 -slug: Mozilla/Add-ons/SDK/Tutorials/Annotator/Implementing_the_widget -tags: - - 附加组件 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Annotator/Implementing_the_widget ---- -<p>我们想要控件做两件事：</p> - -<ul> - <li>点击鼠标左键，控件应当启用或禁用注释器。</li> - <li>点击鼠标右键，控件应当显示用户创建注释的清单。</li> -</ul> - -<p>因为控件无法区分鼠标左右键的点击，我们应当使用内容脚本来捕获单击事件并发送相应的消息到附加组件。</p> - -<p>控件将有两个图标：一个在注释器启用时显示，一个在禁用时显示。</p> - -<p>因此，我们需要创建三个文件：控件的内容脚本和两个图标。</p> - -<p>在data子目录创建一个widget子目录，我们将把控件的文件保存在这里（注意，这个不是强制性的：你可以仅仅把它们放在data里，但分类放置会更加整洁）。</p> - -<h2 id="控件的内容脚本">控件的内容脚本</h2> - -<p>控件的内容脚本仅仅监听鼠标的左右单击并发送相应的消息到附加组件代码：</p> - -<pre class="brush: js">this.addEventListener('click', function(event) { - if(event.button == 0 && event.shiftKey == false) - self.port.emit('left-click'); - - if(event.button == 2 || (event.button == 0 && event.shiftKey == true)) - self.port.emit('right-click'); - event.preventDefault(); -}, true);</pre> - -<p>把它保存在data/widget并命名为widget.js。</p> - -<h2 id="控件图标">控件图标</h2> - -<p>你可以从这里复制图标：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6673/pencil-off.png"><img alt="" src="https://mdn.mozillademos.org/files/6675/pencil-on.png" style="width: 32px; height: 32px;"></p> - -<p>或者自己动手做你觉得有创造性的图标。把它们保存在data/widget目录。</p> - -<h2 id="main.js">main.js</h2> - -<p>现在在lib目录创建main.js并添加下列内容：</p> - -<pre class="brush: js">var widgets = require('sdk/widget'); -var data = require('sdk/self').data; - -var annotatorIsOn = false; - -function toggleActivation() { - annotatorIsOn = !annotatorIsOn; - return annotatorIsOn; -} - -exports.main = function() { - - var widget = widgets.Widget({ - id: 'toggle-switch', - label: 'Annotator', - contentURL: data.url('widget/pencil-off.png'), - contentScriptWhen: 'ready', - contentScriptFile: data.url('widget/widget.js') - }); - - widget.port.on('left-click', function() { - console.log('activate/deactivate'); - widget.contentURL = toggleActivation() ? - data.url('widget/pencil-on.png') : - data.url('widget/pencil-off.png'); - }); - - widget.port.on('right-click', function() { - console.log('show annotation list'); - }); -}</pre> - -<p>注释器默认禁用。它创建控件并通过切换注释器的活动状态来回应来自控件内容脚本的消息。注意，由于<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=626326">bug 626326</a>，附加组件状态栏的环境菜单会显示，尽管在控件的内容脚本中调用了event.preventDefault()。由于我们没有任何代码来显示注释，所以我们们仅仅记录右击事件到控制台。</p> - -<p>现在在注释器目录输入cfx run，你应该看见在附加组件状态栏的控件：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6679/widget-icon.png" style="width: 405px; height: 166px; display: block; margin-left: auto; margin-right: auto;"></p> - -<p>左击和右击应当产生合适的调试输出，同时左击应当改变控件的图标为启用状态。</p> - -<p> </p> - -<p>下一步，我们将添加代码来<a href="/en-US/Add-ons/SDK/Tutorials/Annotator/Creating_annotations">创建注释器</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/index.html deleted file mode 100644 index 4f76d67802..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/index.html +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: 注释器(Annotator) -slug: Mozilla/Add-ons/SDK/Tutorials/Annotator -tags: - - 附加组件 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Annotator ---- -<div class="warning"> -<p>请注意教程中Widget API适合的浏览器版本。（译者注）</p> -</div> - -<p>在这个教程中，我们将构建一个使用许多SDK高级API的附加组件.</p> - -<p>这个附加组件是一个注释器:它可以让用户选择网页的元素并输入有关的笔记(注释).注释器储存笔记.无论用户何时载入包含被注释元素的页面,这些元素都将会高亮显示,并且用户若把鼠标移动到被注释元素的上面,将会显示它的注释.</p> - -<p>接着我们将给出这个注释器设计的快速简介,然后一步步的讨论如何实现.</p> - -<p>如果你想参阅完整的附加组件,你可以在<a href="https://github.com/mozilla/addon-sdk/tree/master/examples/annotator">SDK例子目录</a>找到它.</p> - -<ul> - <li> - <p><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Annotator/Overview">设计概述</a></p> - </li> - <li> - <p><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Annotator/Implementing_the_widget">实现控件</a></p> - </li> - <li> - <p><a href="/en-US/Add-ons/SDK/Tutorials/Annotator/Creating_annotations">创建注释</a></p> - </li> - <li> - <p><a href="/en-US/Add-ons/SDK/Tutorials/Annotator/Storing_annotations">保存注释</a></p> - </li> - <li> - <p><a href="/en-US/Add-ons/SDK/Tutorials/Annotator/Displaying_annotations">显示注释</a></p> - </li> -</ul> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/overview/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/overview/index.html deleted file mode 100644 index da94f8142a..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/annotator/overview/index.html +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 概述 -slug: Mozilla/Add-ons/SDK/Tutorials/Annotator/Overview -tags: - - addon sdk example - - annotator example - - 附加组件 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Annotator/Overview ---- -<p>注释器使用内容脚本（content scripts）来构建用户界面，得到用户输入，并检查用户载入页面的DOM。</p> - -<p>同时，主要模块包括程序逻辑和调节不同SDK对象的交互。</p> - -<p>我们可以描述在主要模块和不同内容脚本的交互，像这样：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6671/annotator-design.png" style="display: block; margin-left: auto; margin-right: auto;"></p> - -<h2 id="用户界面">用户界面</h2> - -<p>注释器的主要用户界面由一个控件和三个面板组成。</p> - -<ul> - <li><a href="/en-US/Add-ons/SDK/High-Level_APIs/widget">控件（widget）</a>用来选择打开或关闭注释器，显示所有已经储存的注释列表。</li> - <li><strong>注释编辑器（annotation-editor）</strong><a href="/en-US/Add-ons/SDK/High-Level_APIs/panel">面板</a>用来让用户输入注释。</li> - <li><strong>注释列表（annotation-list）</strong>面板用来显示保存的注释清单。</li> - <li><strong>注释（annotation）</strong>面板显示单条注释。</li> -</ul> - -<p>除此之外，我们使用 <a href="/en-US/Add-ons/SDK/High-Level_APIs/notifications">notifications</a> 模块来告知用户附加组件的储存限额已满。</p> - -<h2 id="用DOM工作">用DOM工作</h2> - -<p>我们将使用 <a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod">page-mods</a> 来和用户打开的网页的DOM进行交互。</p> - -<ul> - <li> - <p><strong>选择器（selector）</strong>让用户选择一个元素来注释。它识别符合注释条件的页面元素，当鼠标在他们上方时高亮显示，并在用户点击高亮元素时通知主要的附加组件代码。</p> - </li> - <li> - <p><strong>匹配器（matcher）</strong>用来寻找被注释的元素：它初始化注释列表并网页中和注释相关连的元素。高亮网页上找到的关联元素，并高亮显示。当鼠标移动到已注释元素的上面，匹配器将通知显示注释面板的主要附加组件代码。</p> - </li> -</ul> - -<h2 id="处理数据">处理数据</h2> - -<p>我们将使用<a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-storage">simple-storage</a>模块来储存数据。</p> - -<p>由于我们将记录潜在的敏感信息，我们想阻止用户在隐私浏览模式下创建注释，最简单的方式是删除附加组件中“package.json“文件的<a href="/en-US/Add-ons/SDK/Tools/package_json#permissions">”private-browsing"键</a>。这样，附加组件就不能看见任何隐私浏览窗口，同时注释器的控件也将不再出现。</p> - -<h2 id="开始行动">开始行动</h2> - -<p>现在让我们来创建叫“注释器”的目录。Navigate to it and type <code>cfx init</code>.</p> - -<p>下一步，我们将<a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Annotator/Implementing_the_widget">实现控件</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/display_a_popup/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/display_a_popup/index.html deleted file mode 100644 index 9bec4966d4..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/display_a_popup/index.html +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: 显示弹出对话框 -slug: Mozilla/Add-ons/SDK/Tutorials/Display_a_Popup -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Display_a_Popup ---- -<div class="note"> - <p>动手之前，必须先<a href="/en-US/Add-ons/SDK/Installation">安装SDK</a>并学习<a href="/en-US/Add-ons/SDK/Getting_Started_With_cfx"><code>cfx</code>基础知识</a>.</p> - <p>T这篇教程使用<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>API需要Firefox 29或更新版本。</p> -</div> -<p>可以使用<a href="/en-US/Add-ons/SDK/High-Level_APIs/panel"><code>面板(panel)</code></a>模块来显示弹出对话框。面板的内容通过HTML编写。你可以在面板上运行content script：尽管在面板里的脚本无法直接访问插件代码，但是你可以在面板脚本和插件代码间交换信息。</p> -<p>这里，我们做了一个会在单击时显示面板的<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>。面板上有一个<code><textarea></code>元素：用户按下<code>return</code>键时，<code><textarea></code>的内容会被发送给插件代码主程序。插件代码主程序会<a href="/en-US/Add-ons/SDK/Tutorials/Logging">在控制台输出日志</a>。.</p> -<p><img alt="" src="https://mdn.mozillademos.org/files/7647/panel.png" style="display: block; margin-left: auto; margin-right: auto;">The add-o插件由六个文件组成n consists of six files:</p> -<ul> - <li><code>main.js</code>：插件主程序，在这里创建按钮和面板</li> - <li><code>get-text.js</code>：与面板内容交互的content脚本</li> - <li><code>text-entry.html</code>：面板的内容，由HTML编写</li> - <li><code>icon-16.png</code>，<code>icon-32.png</code>和<code>icon-64.png</code>：三种不同大小的图标</li> -</ul> -<p>"main.js"像这样：</p> -<pre class="brush: js">var data = require("sdk/self").data; -// 构造面板，从"data"目录的"text-entry.html"加载 -// 内容，然后加载"get-text.js"脚本。 -var text_entry = require("sdk/panel").Panel({ - contentURL: data.url("text-entry.html"), - contentScriptFile: data.url("get-text.js") -}); - -// 创建按钮 -require("sdk/ui/button/action").ActionButton({ - id: "show-panel", - label: "Show Panel", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -// 在用户点击按钮时显示面板。 -function handleClick(state) { - text_entry.show(); -} - -<code class="language-js"><span class="token comment">// When the panel is displayed it generated an event called -</span><span class="token comment">// "show": we will listen for that event and when it happens, -</span><span class="token comment">// send our own "show" event to the panel's script, so the -</span><span class="token comment">// script can prepare the panel for display.</span></code> -text_entry.on("show", function() { - text_entry.port.emit("show"); -}); - -// 监听来自content脚本的text-entered消息。消息主体L是用户输入的文本。 -// 此实现，我们只在控制台显示日志。 -text_entry.port.on("text-entered", function (text) { - console.log(text); - text_entry.hide(); -});</pre> -<p>content脚本"get-text.js"像这样：</p> -<div> - <pre class="brush: js">// 用户按下回车，发送text-entered消息给main.js。 -// 消息主体是编辑框的内容。 -var textArea = document.getElementById("edit-box"); -textArea.addEventListener('keyup', function onkeyup(event) { - if (event.keyCode == 13) { - // Remove the newline. - text = textArea.value.replace(/(\r\n|\n|\r)/gm,""); - self.port.emit("text-entered", text); - textArea.value = ''; - } -}, false); -// 监听由插件主程序发送的show事件。表示面板将要显示。 -// -// 焦点放在textarea上，这样用户可以直接开始输入。 -self.port.on("show", function onShow() { - textArea.focus(); -});</pre> - <div> - </div> -</div> -<p>最后，"text-entry.html"文件定义了<code><textarea></code>元素：</p> -<div> - <div> - <pre class="brush: html"><html> -<head> - <style type="text/css" media="all"> - textarea { - margin: 10px; - } - body { - background-color: gray; - } - </style> - </head> -<body> - <textarea rows="13" cols="33" id="edit-box"></textarea> - </body> -</html></pre> - <div> - </div> - </div> -</div> -<p>最后，把这三个图标文件保存在"data"目录：</p> -<table class="standard-table"> - <tbody> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7635/icon-16.png" style="width: 16px; height: 16px;"></td> - <td>icon-16.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7637/icon-32.png" style="width: 32px; height: 32px;"></td> - <td>icon-32.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7639/icon-64.png" style="width: 64px; height: 64px;"></td> - <td>icon-64.png</td> - </tr> - </tbody> -</table> -<p>试用以下：保存在<code>lib</code>目录，其他五个文件存放在插件的<code>data</code>目录：</p> -<pre>my-addon/ - data/ - get-text.js - icon-16.png - icon-32.png - icon-64.png - text-entry.html - lib/ - main.js -</pre> -<p>运行插件，点击按钮，你就会看见一个面板。输入几行文本，然后按下回车，你就会看见控制台里的输出。</p> -<p>自Firefox 30起，如果你使用<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">切换按钮</a>，就可以<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle#Attaching_panels_to_buttons">给它附加一个面板</a>。</p> -<h2 id="进一步学习">进一步学习</h2> -<p>学习<code>panel</code>模块的更多内容，见<a href="/en-US/Add-ons/SDK/High-Level_APIs/panel"><code>panel</code> API参考</a>。</p> -<p>学习关于按钮的更多内容，见<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>和<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_toggle">切换按钮</a>API参考。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started/index.html deleted file mode 100644 index 225739de76..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started/index.html +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: 快速入门 -slug: Mozilla/Add-ons/SDK/Tutorials/Getting_started -tags: - - add-on sdk开发 - - cfx工具基础使用教程 - - 火狐扩展程序 -translation_of: Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29 ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p>Add-on SDK 里包含了一个命令行工具，你可以用此工具来初始化、运行、测试以及打包 add on。 这个工具称为 jpm，基于 <a href="http://nodejs.org/">Node.js</a> 。它替代了以前的cfx工具。</p> - -<p>你可以在 Firefox 38或之后的版本中使用。</p> - -<p>本文阐述如何使用 jpm 开发。</p> -</div> - -<p>本教程会过一遍使用 SDK 创建一个简单 add-on 的过程。</p> - -<h2 id="准备">准备</h2> - -<p>要使用 SDK 创建 add-on，你需要：</p> - -<ul> - <li>Firefox 38或以后版本。如果你需要在早期版本的 Firefox 上开发，你就要使用老的 cfx 工具。参看 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_started_(cfx)">cfx 快速入门</a>的说明。</li> - <li>命令行 jpm 工具。参看 <a href="/en-US/Add-ons/SDK/Tools/jpm#Installation">jpm 安装</a>的说明。一旦你已经完成这些工作，你就会在一个命令行提示符下。</li> -</ul> - -<h2 id="初始化空的_add-on">初始化空的 add-on</h2> - -<p>在命令行提示符下，创建一个新目录。进入新文件夹，键入 <code>jpm init</code>，然后敲回车</p> - -<pre>mkdir my-addon -cd my-addon -jpm init -</pre> - -<p>接着你会被要求提供一些关于你的 add-on 的信息：这会用来创建 <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> 文件。如果光按回车的话，就表示接受属性的默认值。关于 <code>jpm init</code> 的更多信息，参看 <a href="/en-US/Add-ons/SDK/Tools/jpm#Command_reference">jpm command reference</a>.</p> - -<p>一旦你设置了这些属性的值或者接受默认值，你会看到 "package.json" 的完整内容并被询问是否接受这些设置。</p> - -<h2 id="实现_add-on">实现 add-on</h2> - -<p>现在你可以写 add-on 的代码了。除非你修改了"entry point"的值（package.json 中的 "<a href="/en-US/Add-ons/SDK/Tools/package_json#main">main</a>"），一般情况将从你的 add-on 的根目录下的"index.js"文件开始。这个文件就是在之前步骤中创建的。打开这个文件并且添加以下代码：</p> - -<pre class="brush: js">var buttons = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = buttons.ActionButton({ - id: "mozilla-link", - label: "Visit Mozilla", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -function handleClick(state) { - tabs.open("http://www.mozilla.org/"); -} -</pre> - -<div class="note"> -<p>注意在jpm中"entry point"的默认值为"index.js"，意思是你的主文件是"index.js"，且在你的 add-on的根目录下。</p> - -<p>cfx中，入口默认是"main.js"，并且在"lib"目录下</p> -</div> - -<p>保存文件</p> - -<p>接下来，在根目录下创建目录<strong>"data"</strong>。</p> - -<pre>mkdir data -</pre> - -<p>并保存这三个图标文件到<strong>"data"</strong>目录：</p> - -<table class="standard-table"> - <tbody> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7635/icon-16.png" style="height: 16px; width: 16px;"></td> - <td>icon-16.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7637/icon-32.png" style="height: 32px; width: 32px;"></td> - <td>icon-32.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7639/icon-64.png" style="height: 64px; width: 64px;"></td> - <td>icon-64.png</td> - </tr> - </tbody> -</table> - -<p>返回命令行，键入：</p> - -<pre>jpm run</pre> - -<p>这个 jpm 命令会运行一个带有你的 add-on 的 Firefox 的新实例。</p> - -<p>如果找不到 Firefox，你可能要为它提供一个路径（如在Ubuntu中）：</p> - - -<pre>jpm run -b /usr/bin/firefox</pre> - -<p>Firefox 启动以后，在浏览器右上角你能看到一个 Firefox logo 的图标。点击该图标，就会打开一个新标签页 <a href="http://www.mozilla.org/" rel="noreferrer">http://www.mozilla.org/</a>。</p> - -<p>这就是这个 add-on 的全部功能了。它用到了 SDK 的两个模块：<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> 模块，使你能加个按钮到浏览器上，以及 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs" rel="noreferrer">tabs</a> 模块，使你能完成对标签页的基本操作。本例中，我们以及创建了一个图标是Firefox图标的按钮，并添加一个点击处理程序，可以在新标签页中打开 Mozilla 页面。</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7643/mozilla-button.png" style="display: block; height: 221px; margin-left: auto; margin-right: auto; width: 382px;">试着编辑这个文件。例如，我们可以改变加载的页面：</p> - -<pre class="brush: js">var buttons = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = buttons.ActionButton({ - id: "mozilla-link", - label: "Visit Mozilla", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -function handleClick(state) { - tabs.open("https://developer.mozilla.org/"); -}</pre> - -<p>在命令行提示符下，再次执行 <code>jpm run</code>。这次点击按钮，它会带你到 <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a> 页面。</p> - -<h2 id="打包_add-on">打包 add-on</h2> - -<p>当你完成了 add-on 并准备发布它，你会需要把它打包为 XPI 文件。你能自己分发 XPI 文件，也可以把它们发布到 <a href="https://addons.mozilla.org" rel="noreferrer">https://addons.mozilla.org</a>，这样其他用户就能下载并按照它们。</p> - -<p>要构建 XPI，只要在 add-on 的根目录下运行命令 <code>jpm xpi</code>：</p> - -<pre>jpm xpi -</pre> - -<p>你应该看到像这样的信息：</p> - -<pre>JPM info Successfully created xpi at /path/to/my-addon/@my-addon-0.0.1.xpi -</pre> - -<p>要测试附加组件是否能正常运行，可以尝试在你自己的火狐中安装 XPI 文件。你可以在 Firefox 中按 Ctrl+O 组合键（Mac 中是 Cmd+O），或者选择"文件"菜单里的“打开”。这样会弹出一个文件选择对话框：转到"@my-addon.xpi"文件，打开并按照提示安装 add-on。</p> - -<p>注意 Firefox 默认需要 add-on 有签名，即使是本地开发的 add-on。安装完后他们会在已安装的 add-on 列表中出现，只因没有签名而被禁用。开发的时候，又或者你不准备发布，你可以打开 <a>about:config</a> 设置 <em>xpinstall.signatures.required</em> 为 <em>false</em> 来运行未经签名的组件。这个设置会应用到所有的 add-on，所以要十分小心，不要一不当心从别的地方安装了恶意组件。</p> - -<p>要发布你的 add-on，请<a href="https://addons.mozilla.org/en-US/developers/addon/submit/2">提交 XPI 文件到 addons.mozilla.org</a> 或者如果你想在你自己的服务器上发布，运行 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm#jpm_sign">jpm sign</a>。</p> - -<h2 id="总结">总结</h2> - -<p>本教程中我们使用了下面三个命令来构建和打包 add-on ：</p> - -<ul> - <li><code>jpm init</code> 初始化一个空的 add-on 模板</li> - <li><code>jpm run</code> 运行一个装有 add-on 的新 Firefox 实例，所以我们可以试用它</li> - <li><code>jpm xpi</code> 打包 add-on 为 XPI 文件，用来发布</li> -</ul> - -<p>这是你在开发SDK add-on会用到的三个主要命令。完全的<a href="/en-US/Add-ons/SDK/Tools/jpm" rel="noreferrer">参考文档</a>包含了所以你能使用的命令，以及这些命令的可选项。</p> - -<p>这次开发的add-on 的代码用到了两个 SDK 模块，<a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> 和 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs" rel="noreferrer">tabs</a>。这儿有参考文档，描述 SDK 中所有<a href="/en-US/Add-ons/SDK/High-Level_APIs" rel="noreferrer">高层次</a>和<a href="/en-US/Add-ons/SDK/Low-Level_APIs" rel="noreferrer">低层次</a>的 API。</p> - -<h2 id="下一步">下一步?</h2> - -<p>要了解你能用 SDK API 做些什么，试着继续阅读<a href="/en-US/Add-ons/SDK/Tutorials" rel="noreferrer">教程</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started_(jpm)/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started_(jpm)/index.html deleted file mode 100644 index e09d6d4e55..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/getting_started_(jpm)/index.html +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: JPM 入门！ -slug: Mozilla/Add-ons/SDK/Tutorials/Getting_Started_(jpm) -tags: - - JPM - - add-on -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Getting_Started_(jpm) ---- -<div class="note"> -<p>该附加SDK包含一个用于初始化，运行，测试和打包加载项的命令行工具。当前工具称为jpm，并且基于 <a href="http://nodejs.org/">Node.js</a> .它替代了旧的cfx工具。</p> - -<p>Firefox 38 以上的版本才可以使用jpm。</p> - -<p>本文介绍如何使用jpm开发。</p> -</div> - -<p>本教程将介绍使用SDK创建一个简单的附加组件。</p> - -<h2 id="先决条件">先决条件</h2> - -<p>要使用SDK为Firefox创建附加组件，您需要：</p> - -<ul> - <li>备好 Firefox 38 或更高版本浏览器，否则抱着你亲爱的cfx古董去死吧，出门左转 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_started">getting started with cfx</a> 不谢。</li> - <li>命令行 JPM 工具，至 <a href="/en-US/Add-ons/SDK/Tools/jpm#Installation">installing jpm</a> 此处领取。// 后面这句是废话不翻译</li> -</ul> - -<h2 id="初始化一个空的附加组件">初始化一个空的附加组件</h2> - -<p>在命令提示符下，创建一个新目录。导航到它，键入 <code>jpm init, </code>然后按Enter键<code>：</code></p> - -<pre>mkdir my-addon -cd my-addon -jpm init -</pre> - -<p>You'll then be asked to supply some information about your add-on: this will be used to create your add-on's <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> file. For now, just press Enter to accept the default for each property. For more information on <code>jpm init</code>, see the <a href="/en-US/Add-ons/SDK/Tools/jpm#Command_reference">jpm command reference</a>.</p> - -<p>Once you've supplied a value or accepted the default for these properties, you'll be shown the complete contents of "package.json" and asked to accept it.</p> - -<h2 id="实现附加组件">实现附加组件</h2> - -<p>Now you can write the add-on's code. Unless you've changed the value of "entry point" ("<a href="/en-US/Add-ons/SDK/Tools/package_json#main">main</a>" in package.json), this goes in "index.js" file in the root of your add-on. This file was created for you in the previous step. Open it and add the following code:</p> - -<pre class="brush: js">var buttons = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = buttons.ActionButton({ - id: "mozilla-link", - label: "Visit Mozilla", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -function handleClick(state) { - tabs.open("http://www.mozilla.org/"); -} -</pre> - -<div class="note"> -<p>Note that "entry point" defaults to "index.js" in jpm, meaning that your main file is "index.js", and it is found directly in your add-on's root.</p> - -<p>In cfx, the entry point defaults to "main.js", and is located in the "lib" directory under the add-on's root.</p> -</div> - -<p>Save the file.</p> - -<p>Next, create a directory called "data" in your add-on's root, and save these three icon files to the "data" directory:</p> - -<table class="standard-table"> - <tbody> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7635/icon-16.png" style="height: 16px; width: 16px;"></td> - <td>icon-16.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7637/icon-32.png" style="height: 32px; width: 32px;"></td> - <td>icon-32.png</td> - </tr> - <tr> - <td><img alt="" src="https://mdn.mozillademos.org/files/7639/icon-64.png" style="height: 64px; width: 64px;"></td> - <td>icon-64.png</td> - </tr> - </tbody> -</table> - -<p>Back at the command prompt, type:</p> - -<pre>jpm run</pre> - -<p>This is the jpm command to run a new instance of Firefox with your add-on installed.</p> - -<p>If Firefox can not be located, you may need to provide the path to it (example in Ubuntu):</p> - - -<pre>jpm run -b /usr/bin/firefox</pre> - -<p>When Firefox launches, in the top-right corner of the browser you'll see an icon with the Firefox logo. Click the icon, and a new tab will open with <a href="http://www.mozilla.org/" rel="noreferrer">http://www.mozilla.org/</a> loaded into it.</p> - -<p>That's all this add-on does. It uses two SDK modules: the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> module, which enables you to add buttons to the browser, and the <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs" rel="noreferrer">tabs</a> module, which enables you to perform basic operations with tabs. In this case, we've created a button whose icon is the Firefox icon, and added a click handler that loads the Mozilla home page in a new tab.</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7643/mozilla-button.png" style="display: block; height: 221px; margin-left: auto; margin-right: auto; width: 382px;">Try editing this file. For example, we could change the page that gets loaded:</p> - -<pre class="brush: js">var buttons = require('sdk/ui/button/action'); -var tabs = require("sdk/tabs"); - -var button = buttons.ActionButton({ - id: "mozilla-link", - label: "Visit Mozilla", - icon: { - "16": "./icon-16.png", - "32": "./icon-32.png", - "64": "./icon-64.png" - }, - onClick: handleClick -}); - -function handleClick(state) { - tabs.open("https://developer.mozilla.org/"); -}</pre> - -<p>At the command prompt, execute <code>jpm run</code> again. This time clicking it takes you to <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>.</p> - -<h2 id="Packaging_the_add-on">Packaging the add-on</h2> - -<p>When you've finished the add-on and are ready to distribute it, you'll need to package it as an XPI file. This is the installable file format for Firefox add-ons. You can distribute XPI files yourself or publish them to <a href="https://addons.mozilla.org" rel="noreferrer">https://addons.mozilla.org</a> so other users can download and install them.</p> - -<p>To build an XPI, just execute the command <code>jpm xpi</code> from the add-on's directory:</p> - -<pre>jpm xpi -</pre> - -<p>You should see a message like:</p> - -<pre>JPM info Successfully created xpi at /path/to/getting-started/@getting-started.xpi -</pre> - -<p>To test that this worked, try installing the XPI file in your own Firefox installation. You can do this by pressing the Ctrl+O key combination (Cmd+O on Mac) from within Firefox, or selecting the "Open" item from Firefox's "File" menu. This will bring up a file selection dialog: navigate to the "@getting-started.xpi" file, open it and follow the prompts to install the add-on.</p> - -<h2 id="Summary">Summary</h2> - -<p>In this tutorial we've built and packaged an add-on using three commands:</p> - -<ul> - <li><code>jpm init</code> to initialize an empty add-on template</li> - <li><code>jpm run</code> to run a new instance of Firefox with the add-on installed, so we can try it out</li> - <li><code>jpm xpi</code> to package the add-on into an XPI file for distribution</li> -</ul> - -<p>These are the three main commands you'll use when developing SDK add-ons. There's comprehensive <a href="/en-US/Add-ons/SDK/Tools/jpm" rel="noreferrer">reference documentation</a> covering all the commands you can use and all the options they take.</p> - -<p>The add-on code itself uses two SDK modules, <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> and <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs" rel="noreferrer">tabs</a>. There's reference documentation for all the <a href="/en-US/Add-ons/SDK/High-Level_APIs" rel="noreferrer">high-level</a> and <a href="/en-US/Add-ons/SDK/Low-Level_APIs" rel="noreferrer">low-level</a> APIs in the SDK.</p> - -<h2 id="What's_next">What's next?</h2> - -<p>To get a feel for some of the things you can do with the SDK APIs, try working through some of the <a href="/en-US/Add-ons/SDK/Tutorials" rel="noreferrer">tutorials</a>.</p> - -<p> </p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/index.html deleted file mode 100644 index 03173c3219..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/index.html +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: 教程 -slug: Mozilla/Add-ons/SDK/Tutorials -tags: - - 插件SDK -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials ---- -<p>{{LegacyAddonsNotice}}{{AddonSidebar}}</p> - -<p>本文列出了许多关于如何通过SDK完成特定任务要求的实际动手的文章。</p> - -<hr> -<h3 id="开发之旅"><a name="getting-started">开发之旅</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Installation">安装</a></dt> - <dd>在Windows, OS X和Linux上下载，安装，初始化SDK工具。</dd> -</dl> - -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Troubleshooting">常见问题</a></dt> - <dd>解决常见问题的建议和获取更多帮助。</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_started">快速开始</a></dt> - <dd>走马观花地使用SDK开发一个简单的扩展</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="创建用户交互界面"><a name="create-user-interfaces">创建用户交互界面</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Adding_a_Button_to_the_Toolbar">添加一个工具按钮</a></dt> - <dd>添加一个按钮到火狐Add-on工具栏。</dd> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox">添加一个菜单选项到火狐</a></dt> - <dd>添加多个菜单选项到火狐主菜单。</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Display_a_Popup">显示一个弹出对话框</a></dt> - <dd>通过HTML和JavaScript实现并显示一个弹窗对话框。</dd> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/添加一个菜单项">添加一个上下文菜单</a></dt> - <dd>添加一个上下文菜单(一般都是右键菜单)到火狐浏览器</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="与浏览器交互"><a name="interact-with-the-browser">与浏览器交互</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Open_a_Web_Page">打开Web页面</a></dt> - <dd>在一个新的浏览器选项卡里打开一个Web页面或窗口使用tabs模块并获取内容。</dd> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Listen_for_Page_Load">监听页面加载</a></dt> - <dd>当新页面载入时使用tabs模块得到通知并获取页面内容。</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/List_Open_Tabs">获取打开的选项卡(Tab)列表</a></dt> - <dd>使用tabs模块遍历当前打开的tab，并获取其内容。</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="更改网页"><a name="modify-web-pages">更改网页</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Modifying_Web_Pages_Based_on_URL">更改网页通过URL</a></dt> - <dd>基于URL过滤网页：当载入的页面的URL与过滤器匹配时执行特定的脚本。</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">修改页面内容</a></dt> - <dd>动态加载脚本到当前页面。</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="开发技术"><a name="development-techniques">开发技术</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/日志">日志</a></dt> - <dd>在终端中记录日志以便调试。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Creating_reusable_modules">创建可复用的模块</a></dt> - <dd>拆分扩展程序为多个分离的模块，可以使开发调试和维护更加简单。封装你的模块使其成为可复用的包，以便其他开发者可以再次使用。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Unit_testing">单元测试</a></dt> - <dd>使用SDK的测试框架书写和进行单元测试。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Chrome_authority">Chrome授权 </a></dt> - <dd>获得Components对象，使你的扩展程序能够加载和使用任何XPCOM对象。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Creating_event_targets">创建事件目标</a></dt> - <dd>使你定义的对象能够响应相关事件。</dd> -</dl> -</div> - -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Listening_for_load_and_unload">监听载入和卸载</a></dt> - <dd>当你的扩展程序被加载和卸载时获得通知，并从终端传递参数给扩展程序。</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox">使用第三方模块</a></dt> - <dd>安装和使用与SDK无关额外的模块</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/l10n">本地化</a></dt> - <dd>书写本地化代码.</dd> - <dt><a href="/zh-CN/Add-ons/SDK/Tutorials/Mobile_development">移动开发</a></dt> - <dd>为Andriod上的火狐浏览器开发扩展程序。</dd> - <dt><a href="/zh-CN/Add-ons/Add-on_Debugger">扩展调试</a></dt> - <dd>调试扩展应用的JavaScript。</dd> -</dl> -</div> -</div> - -<hr> -<h3 id="打包"><a name="putting-it-together">打包</a></h3> - -<div class="column-container"> -<div class="column-half"> -<dl> - <dt><a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Annotator">扩展应用：Annotator</a></dt> - <dd>一起开发一个相对复杂的扩展应用。</dd> -</dl> -</div> -</div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/installation/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/installation/index.html deleted file mode 100644 index 4313836979..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/installation/index.html +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: 安装 -slug: Mozilla/Add-ons/SDK/Tutorials/Installation -tags: - - cfx安装 - - 配置cfx环境 -translation_of: Mozilla/Add-ons/SDK/Tools/jpm#Installation ---- -<h2 id="先决条件">先决条件</h2> - -<p><span style="color: #ff0000;">请不要把任何相关的开发工具和扩展程序（命名推荐小写英文和数字，不推荐特殊符号等），放到有空格的目录(如Progaram Files\Python)，会导致意想不到的错误，无法进行后续操作。(最新开发SDK可能修复了该错误，参见https://github.com/mozilla/addon-sdk/pull/1738)</span></p> - -<p>开发 Add-on SDK，你需要：</p> - -<ul> - <li> - <p><a href="http://www.python.org/">Python</a> 2.5，2.6 或 2.7。 <span class="short_text" id="result_box" lang="zh-CN"><span>需要注意的是在任何平台<span class="short_text" id="result_box" lang="zh-CN"><span>都是不支持</span></span></span></span> <span class="short_text" id="result_box" lang="zh-CN"><span>Python</span><span>3.x版本的</span></span> 。确保你已经安装过Python。</p> - </li> - <li> - <p>Firefox火狐浏览器(本教程针对最新的浏览器)。</p> - </li> - <li> - <p><span class="short_text" id="result_box" lang="zh-CN"><span>SDK本身</span><span>：</span><span>可以获取</span><span>SDK的最新</span><span>稳定版本</span><span>为</span></span> <a href="https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz">tarball压缩包</a> 或 <a href="https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.zip">zip 文件</a>。</p> - </li> -</ul> - -<p>另外，<span class="short_text" id="result_box" lang="zh-CN"><span>你</span><span>可以从它</span><span>的<a href="https://github.com/mozilla/addon-sdk">GitHub repository</a></span><span>库中</span><span>得到最新的</span><span>开发版本</span></span>。</p> - -<h2 id="为AMO开发扩展">为AMO开发扩展</h2> - -<p>如果提交到AMO只有最新发布或许使用。</p> - -<p class="ordinary-output target-output"><span>git</span><span> archive </span><span>需要扩展</span><span>一些Git</span><span>属性</span><span>占位符</span><span>。</span></p> - -<pre class="language-html">git checkout 1.16 - -git archive 1.16 python-lib/cuddlefish/_version.py | tar -xvf -</pre> - -<h2 id="通过Homebrew自动安装到Mac_OS_X">通过Homebrew自动安装到Mac OS X</h2> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>使用以下命令</span><span>通过</span></span> <a href="http://brew.sh/">homebrew</a><span class="short_text" id="result_box" lang="zh-CN"><span>来安装</span><span>SDK<span class="short_text" id="result_box" lang="zh-CN"><span><span class="short_text" id="result_box" lang="zh-CN"><span>插件</span></span></span></span>工具：</span></span></p> - -<pre>brew install mozilla-addon-sdk</pre> - -<h2 id="安装到Mac_OS_XLinux">安装到Mac OS X/Linux</h2> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span><span class="short_text" id="result_box" lang="zh-CN"><span>无论你</span><span>选择哪个方式都要</span></span>解压缩</span><span>文件的内容</span><span>作为根路径，</span><span>并通过</span><span>shell</span><span>/</span><span>命令提示符切换到</span><span>SDK的</span><span>根目录下</span><span>。</span><span>例如：</span></span></p> - -<pre>tar -xf addon-sdk.tar.gz -cd addon-sdk -</pre> - -<p>如果你是<span class="short_text" id="result_box" lang="zh-CN"><span>Bash的</span><span>用户，则继续运行</span></span>(大多数人都是的)：</p> - -<pre>source bin/activate -</pre> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>如果你是</span><span>一个非</span><span>Bash的</span><span>用户</span><span>，</span><span>你应该运行</span><span>：</span></span></p> - -<pre>bash bin/activate -</pre> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>命令提示符</span><span>现在应该</span><span>有一个包含</span><span>SDK的</span><span>根</span><span>目录名称</span><span>的新的前缀</span><span>：</span></span></p> - -<pre>(addon-sdk)~/mozilla/addon-sdk > -</pre> - -<h2 id="安装到Windows">安装到Windows</h2> - -<p>同样解压缩文件，并通过命令符进入到SDK根目录下，例如：</p> - -<pre>7z.exe x addon-sdk.zip -cd addon-sdk -</pre> - -<p>接着运行激活命令：</p> - -<pre>bin\activate -</pre> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>同样可以看到命令提示符</span><span>现在应该</span><span>有一个包含</span><span>SDK的</span><span>根</span><span>目录名称</span><span>的<span class="short_text" id="result_box" lang="zh-CN"><span>新的</span></span>前缀</span><span>：</span></span></p> - -<pre>(C:\Users\mozilla\sdk\addon-sdk) C:\Users\Work\sdk\addon-sdk> -</pre> - -<h2 id="SDK_的虚拟环境">SDK 的虚拟环境</h2> - -<p><span id="result_box" lang="zh-CN"><span><span id="result_box" lang="zh-CN"><span>当命令</span><span>提示符</span></span>出现新的</span><span>前缀</span><span>表明</span><span>你的</span><span>已经搭建好了SDK的</span><span>运行环境</span><span>，那么你就可以使用</span><span>Add</span><span class="atn">-</span><span>on SDK来开发</span><span>的</span><span>命令行工具</span><span>。</span></span></p> - -<p>任何时候，你都可以通过运行 <code>deactivate 命令停用虚拟环境</code>.</p> - -<p class="ordinary-output target-output"><span>配置好的虚拟环境是特定于这个特定的命令提示符。</span><span>如果您关闭命令提示符， 它会关闭运行环境，你需要<code>source bin/activate</code>或<code> bin\activate 在</code>一个新的命令提示符重新激活它。</span><span>如果你</span><span>打开一个新命令提示符</span><span>，</span><span id="result_box" lang="zh-CN"><span>SDK将</span><span>不会被激活</span><span>在新的提示</span></span><span>。</span></p> - -<p><span id="result_box" lang="zh-CN"><span>可以</span><span>将SDK</span><span>的多个副本</span><span>拷贝在</span><span>磁盘上的</span><span>不同位置</span><span>，并</span><span>在它们之间切换</span><span>，甚至可以</span><span>让他们<span id="result_box" lang="zh-CN"><span>同时</span><span>激活</span></span>运行在</span><span>不同的命令</span><span>提示</span><span>符</span><span>。</span></span></p> - -<h3 id="制作启动项">制作启动项</h3> - -<p><span id="result_box" lang="zh-CN"><span>所有 </span><code>activate </code><span>的作用是通过设置环境变量，<span id="result_box" lang="zh-CN"><span>使位于</span><span>顶层</span><code> bin </code><span>目录下</span><span>的脚本</span></span></span><span> </span><span>位于当前命令符下</span><span>，制作的启动项 ，</span><span>通过永久</span><span>环境中的这些</span><span>变量</span><span>设置，以便</span><span>每一个新的</span><span>命令提示符下</span><span>都能读取它们</span><span>。</span><span>那么</span><span>就不需要每次都去打开新的命令提示符来激活</span><span><code> activate </code>。</span></span></p> - -<p class="ordinary-output target-output"><span>因为变量精确设置可能随SDK发布新版本的变化，所以最好是指激活脚本来确定哪些变量需要设置。</span><span>激活</span><span>使用不同的</span><span>脚本</span><span>设置</span><span>bash</span><span>环境</span><span>不同的变量</span><span>（</span><span>Linux</span><span>和</span><span>MAC</span><span> OS X</span><span>和Windows</span><span>环境</span><span>）</span><span>。</span></p> - -<h4 id="Windows">Windows</h4> - -<p><span id="result_box" lang="zh-CN"><span>在Windows上，</span><span>使用</span><span> <code>bin\activate\</code><code>activate.bat</code></span><span>批处理脚本，也可以</span><span>使用命令行</span><code>setx</code><span>工具或</span><span>控制面板</span><span>激活</span><span>永久</span><span>使用</span><span>。</span></span></p> - -<h4 id="LinuxMac_OS_X">Linux/Mac OS X</h4> - -<p>在 Linux 和 Mac OS X,<span id="result_box" lang="zh-CN"><span>使用</span></span><code>source bin/activate</code>/<code>activate</code> bash 脚本, 你可以 <code>~/.bashrc</code> ( Linux) <code>或~/.bashprofile</code> (Mac OS X) 来激活。</p> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>作为替代</span><span>，你</span><span>可以在</span><code> ~/bin </code><span class="hps">目录中</span><span>创建到</span><span>cfx </span><span>程序</span><span>的符号链接</span><span>：</span></span></p> - -<pre>ln -s PATH_TO_SDK/bin/cfx ~/bin/cfx -</pre> - -<h2 id="完整性检查"><span class="short_text" id="result_box" lang="zh-CN"><span>完整性检查</span></span></h2> - -<p><span class="short_text" id="result_box" lang="zh-CN"><span>在shell提示符</span></span>运行:</p> - -<pre>cfx -</pre> - -<p>它会产生下面信息，这里是第一行内容，后面<span>是</span><span>大量的</span><span>使用信息</span><span>：</span></p> - -<pre>Usage: cfx [options] [command] -</pre> - -<p><span id="result_box" lang="zh-CN"><span>这是</span></span> <a href="/en-US/Add-ons/SDK/Tools/cfx"><span id="result_box" lang="zh-CN"><span>CFX</span><span>命令行程序</span></span></a>， <span id="result_box" lang="zh-CN"><span>是</span><span>主</span><span>界面</span><span>加载项</span><span>的SDK</span></span>，<span id="result_box" lang="zh-CN"><span>可以使用</span><span>它来</span><span>启动Firefox</span><span>和测试</span><span>插件，</span><span>打包</span><span>附加</span><span>分发</span><span>，查看</span><span>文档和</span><span>运行单元测试</span><span>。</span></span></p> - -<h2 id="出现问题">出现问题?</h2> - -<p>尝试通过<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Troubleshooting">故障排除页面</a>来解决遇到的问题。</p> - -<h2 id="下一步">下一步</h2> - -<p>接下来， 开始学习 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_With_cfx">cfx</a> 教程， <span class="short_text" id="result_box" lang="zh-CN"><span>其中</span><span>介绍了如何</span><span>使用</span><span>CFX的</span><span>工具来创建</span><span>附加组件</span><span>。</span></span></p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/l10n/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/l10n/index.html deleted file mode 100644 index 5083be5b5c..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/l10n/index.html +++ /dev/null @@ -1,381 +0,0 @@ ---- -title: Localization -slug: Mozilla/Add-ons/SDK/Tutorials/l10n -tags: - - Add-on SDK - - 本地化 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/l10n ---- -<p>该SDK支持本地化字符串出现在:</p> - -<ul> - <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_JavaScript">你的主附加组件Add-on的 JavaScript代码</a></li> - <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_HTML">你的附加组件一起打包的HTML文件</a></li> - <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_Preferences">你的附加组件首选项中的 title 标题和 description 描述域</a></li> -</ul> - -<p>目前为止还不支持本地化CSS和content scripts。</p> - -<h2 id="本地化字符串">本地化字符串</h2> - -<p>翻译后的字符串都保存在你的add-on扩展目录下一个名为 "locale"的目录 ，每个本地化地域对应一个文件。这些文件：</p> - -<ul> - <li>使用文件<a href="http://en.wikipedia.org/wiki/.properties"><code>.properties</code> 格式</a></li> - <li>被命名为 "xx-YY.properties", 这里的 "xx-YY" 是 <a href="https://wiki.mozilla.org/L10n:Locale_Codes"> </a> <a href="https://wiki.mozilla.org/L10n:Locale_Codes">name of the locale（本地化区域的名称）</a></li> - <li>包含所有你想要本地化的字符串，其中由一个本地化字符串标识ID和对应的本地化翻译字符串以 <code>"标识ID=本地化翻译的字符串</code>" 的格式组成。(contain one entry for each string you want to localize, consisting of an identifier for the string and its translation in that locale, in the format <code>identifier=translation</code>.)</li> - <li>需要使用没有BOM的UTF-8格式来编码(need to use UTF-8 without BOM encoding)</li> -</ul> - -<p>假设你的附加组件包含一个单一的本地化字符串，用英语表示为“Hello！”，你想提供英语和法语的本地化支持。</p> - -<p>你需要添加两个文件到"locale"目录：</p> - -<pre>my-addon/ - data - lib - locale/ - en-US.properties - fr-FR.properties -</pre> - -<p>"en-US.properties" 文件中内容:</p> - -<pre>hello_id= Hello! -</pre> - -<p>"fr-FR.properties" 文件中内容:</p> - -<pre>hello_id= Bonjour ! -</pre> - -<p>现在，每当你的JavaScript或HTML向本地化系统请求hello_id标识的翻译，它将获得与当前区域语言一致的翻译。</p> - -<h2 id="在HTML中使用本地化字符串">在HTML中使用本地化字符串</h2> - -<div class="note"> -<p>本例使用的 <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> API需要 Firefox 29 或者更高版本。</p> -</div> - -<p>要从HTML中引用本地化字符串，需要添加一个 <code>data-l10n-id</code> 的属性，到你想本地化的字符串所属的HTML标签中，然后为该属性指定一个ID值(To reference localized strings from HTML, add a <code>data-l10n-id</code> attribute to the HTML tag where you want the localized string to appear, and assign the identifier to it)：</p> - -<pre class="brush: html"><html> - <body> - <h1 data-l10n-id="hello_id"></h1> - </body> -</html> -</pre> - -<p>然后你就可以使用这个HTML文件来建立你的界面, 比如插入一个 panel 面板：</p> - -<pre class="brush: js">var button = require("sdk/ui/button/action").ActionButton({ - id: "localized-hello", - label: "Localized hello", - icon: "./icon-16.png", - onClick: function() { - hello.show(); - } -}); - -var hello = require("sdk/panel").Panel({ - height: 75, - width: 150, - contentURL: require("sdk/self").data.url("my-panel.html") -});</pre> - -<p>“en-US”和“fr-FR”提供了翻译标识为hello_id字符串的本地化文件，面板将根据当前区域语言设置，显示“Hello！”或者“Bonjour！”：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/7663/bonjour.png" style="width: 255px; height: 160px;"><img alt="" src="https://mdn.mozillademos.org/files/7665/hello.png" style="width: 255px; height: 160px;"></p> - -<p>翻译文本会插入到具有data-l10n-id属性集的节点中。任何之前存在的内容只是被替换掉了。(The translation is inserted into the node which has the <code>data-l10n-id</code> attribute set. Any previously existing content is just replaced.)</p> - -<p>本地化字符串只能作为text文本插入, 所以你不能使用下面的语句插入HTML：</p> - -<pre>hello_id= <blink>Hello!</blink> -</pre> - -<h3 id="Localizing_Element_Attributes">Localizing Element Attributes</h3> - -<div class="geckoVersionNote">这是 Firefox 39 上的新功能</div> - -<p><br> - 你可以在properties文件中，通过设置 l10n-id.attributeName 的值，本地化某些具有 l10n-id属性的元素的属性值。像这样(You can localize certain attributes of elements with an l10n-id by setting its value with l10n-id.attributeName in the properties file like)：<br> - </p> - -<pre>hello_id.accesskey= H</pre> - -<p>可以支持以下几个属性：</p> - -<ul> - <li><strong>accesskey</strong></li> - <li><strong>alt</strong></li> - <li><strong>label</strong></li> - <li><strong>title</strong></li> - <li><strong>placeholder</strong></li> -</ul> - -<p>更多的<a href="/en-US/docs/Web/Accessibility/ARIA"> ARIA</a> 属性<strong>aria-label</strong>, <strong>aria-valuetext</strong> 和 <strong>aria-moz-hint</strong> 的本地化将通过在Firefox OS上同样的别名被支持(Further the localization of the <a href="/en-US/docs/Web/Accessibility/ARIA">ARIA</a> attributes <strong>aria-label</strong>, <strong>aria-valuetext</strong> and <strong>aria-moz-hint</strong> are supported with the same aliases as on Firefox OS)：</p> - -<ul> - <li><strong>ariaLabel</strong></li> - <li><strong>ariaValueText</strong></li> - <li><strong>ariaMozHint</strong></li> -</ul> - -<h2 id="在JavaScript代码中使用本地化字符串">在JavaScript代码中使用本地化字符串</h2> - -<p>为了在主附加组件代码中引用本地化字符串，你需要这样做：</p> - -<pre class="brush: js">var _ = require("sdk/l10n").get; -console.log(_("hello_id!"));</pre> - -<p><span>指定的 "_" 并不是必需的，但是作为<a href="https://www.gnu.org/software/gettext/gettext.html"> gettext </a>工具的默认约定，这能更好的配合其他默认使用 "_" 来表示本地化字符串的现有工具。</span></p> - -<ol> - <li>导入 <code>l10n</code> 模块，然后指定 "_" (下划线）为模块的 <code>get</code> 函数。</li> - <li>把所有涉及本地化的字符串放到 <code>_()</code> 函数中包括起来。</li> -</ol> - -<p>如果你运行它，你会看到输出为预期的当前设置的区域语言:</p> - -<pre>info: Hello! -</pre> - -<pre>info: Bonjour ! -</pre> - -<p>注意你不能在content scripts中 <code>require()</code> 一个模块，所以目前还不能在content script 中引用本地化字符串。</p> - -<h3 id="复数">复数</h3> - -<p> <code>l10n</code> 模快支持复数形式，不同的语言有不同的复数形态。例如，英语有两种形式：相对于"one"的单数形式，和对于"everything else, including zero"的复数形式：</p> - -<pre>one tomato -no tomatoes -two tomatoes -</pre> - -<p>但是俄罗斯语对于以 1 结尾(除了11)的数字、以 2-4 结尾(除了12-14)的数字和其他数字，有着不同的复数形态：</p> - -<pre>один помидор // one tomato -два помидора // two tomatoes -пять помидоров // five tomatoes -</pre> - -<p>SDK使用 <a href="http://cldr.unicode.org/index">Unicode CLDR</a> 数据描述由不同的语言使用的不同复数形式。</p> - -<h4 id="Unicode_CLDR_复数形式">Unicode CLDR 复数形式</h4> - -<p>Unicode CLDR项目定义了用于描述一个特定语言的多个规则的一种方案。在这个方案中一种语言对应最多有六种不同的范围的数字，有以下类别区分：<em>zero(零个)，one(一个)，two(两个)，few(几个)，many(很多)，</em>和<em>other(其他)</em>。(The Unicode CLDR project defines a scheme for describing a particular language's plural rules. In this scheme a language maps each distinct range of numbers on to one of up to six forms, identified by the following categories: <em>zero</em>, <em>one</em>, <em>two</em>, <em>few</em>, <em>many</em>, and <em>other</em>.)</p> - -<p>英语有两种复数形式，可以表示为 "1" 映射到 "one" 和 "everything else" 映射到 "other"的形式(English has two forms, which can be described by mapping "1" to "one" and "everything else" to "other")：</p> - -<pre>one → n is 1; -other → everything else -</pre> - -<p>俄罗斯语有四种形式，可以使用以下方式表示:</p> - -<pre>one → n mod 10 is 1 and n mod 100 is not 11; -few → n mod 10 in 2..4 and n mod 100 not in 12..14; -many → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14; -other → everything else -</pre> - -<p>所有语言的多个规则可以在CLDR的 <a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html">语言复数规则</a> 页面查到 (即使这个规则表相对于 <a href="http://unicode.org/repos/cldr/trunk/common/supplemental/plurals.xml">CLDR XML source</a> 已经过时了).</p> - -<h4 id="SDK中的复数形式">SDK中的复数形式</h4> - -<p>代码中，在 <code>_()</code>函数中的本地化ID参数之后提供一个额外的参数，用来表示代表多少个项的本地化字符串(In the code, you supply an extra parameter alongside the identifier, describing how many items there are)：</p> - -<pre class="brush: js">var _ = require("sdk/l10n").get; -console.log(_("tomato_id")); -console.log(_("tomato_id", 1)); -console.log(_("tomato_id", 2)); -console.log(_("tomato_id", 5)); -console.log(_("tomato_id", .5));</pre> - -<p>在 <code>.properties</code> 文件中通过使用 CLDR 关键字，对于每种语言可能的复数形式你可以自定义不同的本地化字符串。所以对于英语可以有两种本地化（注意"other" 分类不是 CDLR 关键字）。（In the <code>.properties</code> file for each language you can define a different localization for each plural form possible in that language, using the CLDR keywords. So in English we could have two plural localizations (note that the "other" category does <strong>not</strong> take the CLDR keyword)）</p> - -<pre># en-US translations -tomato_id[one]= %d tomato -tomato_id= %d tomatoes -</pre> - -<p>俄罗斯语中可以定义四种本地化的复数形式：</p> - -<pre># ru-RU translations -tomato_id[one]= %d помидор -tomato_id[few]= %d помидора -tomato_id[many]= %d помидоров -tomato_id= %d помидоры -</pre> - -<p>The localization module itself understands the CLDR definitions for each language, enabling it to map between, for example, "2" in the code and "few" in the <code>ru-RU.properties</code> file. Then it retrieves and returns the localization appropriate for the count you supplied.</p> - -<h3 id="Placeholders">Placeholders</h3> - -<p>The <code>l10n</code> module supports placeholders, allowing you to insert a string which should not be localized into one which is. The following "en-US" and "fr-FR" ".properties" files include placeholders:</p> - -<pre># en-US translations -hello_id= Hello %s! -</pre> - -<pre># fr-FR translations -hello_id= Bonjour %s ! -</pre> - -<p>To use placeholders, supply the placeholder string after the identifier:</p> - -<pre class="brush: js">var _ = require("sdk/l10n").get; -console.log(_("hello_id", "Bob")); -console.log(_("hello_id", "Alice"));</pre> - -<p>In the "en-US" locale, this gives us:</p> - -<pre>info: Hello Bob! -info: Hello Alice! -</pre> - -<p>In "fr-FR" we get:</p> - -<pre>info: Bonjour Bob ! -info: Bonjour Alice ! -</pre> - -<h3 id="Ordering_Placeholders">Ordering Placeholders</h3> - -<p>When a localizable string can take two or more placeholders, translators can define the order in which placeholders are inserted, without affecting the code.</p> - -<p>Primarily, this is important because different languages have different rules for word order. Even within the same language, though, translators should have the freedom to define word order.</p> - -<p>For example, suppose we want to include a localized string naming a person's home town. There are two placeholders: the name of the person and the name of the home town:</p> - -<pre class="brush: js">var _ = require("sdk/l10n").get; -console.log(_("home_town_id", "Bob", "London"));</pre> - -<p>An English translator might want to choose between the following:</p> - -<pre>"<town_name> is <person_name>'s home town." -</pre> - -<pre>"<person_name>'s home town is <town_name>" -</pre> - -<p>To choose the first option, the <code>.properties</code> file can order the placeholders as follows:</p> - -<pre>home_town_id= %2s is %1s's home town. -</pre> - -<p>This gives us the following output:</p> - -<pre>info: London is Bob's home town. -</pre> - -<h2 id="在首选项设置中的本地化字符串">在首选项设置中的本地化字符串</h2> - -<p>通过加入一个 <a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-prefs">"preferences" 字段的结构到你的附加组件的 "package.json" 文件</a>中，你可以为你的附加组件定义首选项选项，用户可以在Firefox的 <a href="https://support.mozilla.org/en-US/kb/Using%20extensions%20with%20Firefox#w_how-to-change-extension-settings">Add-ons Manager</a> 看到和编辑它。</p> - -<p>Preferences (首选项)有一个必需的title标题项和一个可选的description描述项 这些字符串将出现在 Add-ons Manager中，来帮助向用户解释各个首选项设置的意义。</p> - -<ul> - <li> - <p>要对preferences中的title标题部分进行本地化，所有在"properties"文件中，形式为preferences中的name后面接着 <code>_title</code> 的本地化标识ID，其对应的值就是标题的本地化字符串。(To provide the localized form of the preference title, include an entry in your "properties" file whose identifier is the preference name followed by <code>_title</code>, and whose value is the localized title.)</p> - </li> - <li> - <p>要对preferences中的description描述部分进行本地化，所有在"properties"文件中，形式为preferences中的name后面接着 <code>_description</code> 的本地化标识ID，其对应的值就是描述的本地化字符串。(To provide the localized form of the preference description, include an entry in your "properties" file whose identifier is the preference name followed by <code>_description</code>, and whose value is the localized description.）</p> - </li> -</ul> - -<p>例如, 假设你的 "package.json" 中只定义了一个设置选项：</p> - -<pre>{ - "preferences": [ - { - "type": "string", - "name": "monster_name", - "value": "Gerald", - "title": "Name" - } - ], - "name": "monster-builder", - "license": "MPL 2.0", - "author": "me", - "version": "0.1", - "fullName": "Monster Builder", - "id": "monster-builder@me.org", - "description": "Build your own monster" -} -</pre> - -<p>在你的"en-US.properties"文件中, 应该包括下面两个项：</p> - -<pre>monster_name_title= Name -monster_name_description= What is the monster's name? -</pre> - -<p>在你的"fr-FR.properties"文件中, 应该包括下面两个法语的翻译项：</p> - -<pre>monster_name_title= Nom -monster_name_description= Quel est le nom du monstre ? -</pre> - -<p>现在，当浏览器的区域设置为 "en-US", 用户会在 Add-ons Manager看到这样：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6525/preference-us.png" style="width: 571px; height: 77px;"></p> - -<p>当浏览器区域设置为 "fr-FR", 用户会看到:</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6523/preference-french.png"></p> - -<p>下拉菜单<code>menulist</code>和单选按钮<code>radio</code>的类型有多个选项，每一个选项的标签属性都会展示给用户。如果本地化文件中有一项是以前缀是"{name} _options" 为键的键值对，其中"{name}"是选项的标签名字，该键值对的值就是一个选项标签的本地化字符串。（The <code>menulist</code> and the <code>radio</code> preference types have options. The <code>label</code> attribute of each option is displayed to the user. If the locale file has a entry with the value of the <code>label</code> attribute prefixed with "{name}_options." as its key, where {name} is the name of the preference, its value is used as a localized label.）</p> - -<h2 id="Using_Identifiers">Using Identifiers</h2> - -<p>If the localization system can't find an entry for a particular identifier using the current locale, then it just returns the identifier itself.</p> - -<p>This has the nice property that you can write localizable, fully functional add-ons without having to write any locale files. You can just use the default language strings as your identifier, and subsequently supply <code>.properties</code> files for all the additional locales you want to support.</p> - -<p>For example, in the case above you could use "Hello!" as the identifier, and just have one <code>.properties</code> file for the "fr-FR" locale:</p> - -<pre>Hello!= Bonjour ! -</pre> - -<p>Then when the locale is "en-US", the system would fail to find a <code>.properties</code> file, and return "Hello!".</p> - -<p>However, this approach makes it difficult to maintain an add-on which has many localizations, because you're using the default language strings both as user interface strings and as keys to look up your translations. This means that if you want to change the wording of a string in the default language, or fix a typo, then you break all your locale files.</p> - -<h2 id="Locale_Updater">Locale Updater</h2> - -<p>The <a href="https://github.com/downloads/ochameau/locale-updater/locale-updater.xpi">locale updater</a> add-on makes it easier to update locale files. Once you've installed it, open the Add-on Manager, and you'll see a see a new button labeled "Update l10n" next to each add-on you've installed:</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6515/locale-updater.png"></p> - -<p>Click the button and you'll be prompted for a new <code>.properties</code> file for that add-on. If you provide a new file, the add-on's locale data will be updated with the new file.</p> - -<h2 id="Limitations">Limitations</h2> - -<p>The current localization support is a first step towards full support, and contains a number of limitations.</p> - -<ul> - <li> - <p>There's no support for content scripts or CSS files: at the moment, you can only localize strings appearing in JavaScript files that can <code>require()</code> SDK modules and in HTML.</p> - </li> - <li> - <p>The set of locale files is global across an add-on. This means that a module isn't able to override a more general translation: so a module <code>informal.js</code> can't specify that "hello_id" occurring in its code should be localized to "Hi!".</p> - </li> - <li> - <p>The SDK tools compile the locale files into a JSON format when producing an XPI. This means that translators can't localize an add-on given the XPI alone, but must be given access to the add-on source.</p> - </li> - <li> - <p>The add-on developer must manually assemble the set of localizable strings that make up the locale files. In a future release we'll add a command to <code>cfx</code> that scans the add-on for localizable strings and builds a template <code>.properties</code> file listing all the strings that need to be translated.</p> - </li> -</ul> - -<h2 id="See_Also_-_for_developers_looking_to_localize_non-SDK_add-ons">See Also - for developers looking to localize non-SDK add-ons</h2> - -<ul> - <li>How to localize html pages, xul files, and js/jsm files from bootstrapped add-ons: <a href="/en-US/Add-ons/Bootstrapped_extensions#Localization_%28L10n%29">Bootstrapped Extensions :: Localization (L10n)</a></li> - <li>XUL School Localization Tutorial: <a href="/en-US/docs/Mozilla/Tech/XUL/Tutorial/Localization">DTD/Entities method</a> and <a href="/en-US/docs/Mozilla/Tech/XUL/Tutorial/Property_Files">Properties method</a></li> - <li><a href="/en-US/docs/Mozilla/Localization/Localizing_an_extension">Localizing an extension</a></li> -</ul> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/list_open_tabs/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/list_open_tabs/index.html deleted file mode 100644 index 8a4985806e..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/list_open_tabs/index.html +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: 列出打开的标签页 -slug: Mozilla/Add-ons/SDK/Tutorials/List_Open_Tabs -tags: - - Add-on SDK -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/List_Open_Tabs ---- -<p>{{AddonSidebar}}</p> - -<div class="note"> -<p><span>学习本教程之前你需要学习 <a href="/en-US/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29"><code>jpm</code> 基础</a>。</span></p> -</div> - -<p>列出打开的标签页，你可以遍历 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> 对象本身。</p> - -<p>下面的 add-on 添加一个 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a> 当用户单击该按钮时，该日志将在打开的标签页中记录：</p> - -<pre class="brush: js">require("sdk/ui/button/action").ActionButton({ - id: "list-tabs", - label: "List Tabs", - icon: "./icon-16.png", - onClick: listTabs -}); - -function listTabs() { - var tabs = require("sdk/tabs"); - for (let tab of tabs) - console.log(tab.url); -} -</pre> - -<div class="note"> -<p>注意：为此你需要一个按钮图标，以"icon-16.png"的文件名保存到你的 add-on 的"data"目录下。你可以从这里下载图标：<img alt="" src="https://mdn.mozillademos.org/files/7649/icon-16.png" style="height: 16px; width: 16px;">。</p> -</div> - -<p>运行该 add-on，加载一对标签页，并点击按钮，你会看到在<a href="/en-US/Add-ons/SDK/Tutorials/Logging">控制台</a>输出如下的内容：</p> - -<pre>info: http://www.mozilla.org/en-US/about/ -info: http://www.bbc.co.uk/ -</pre> - -<div class="warning"> -<p>你不能直接访问到标签页中的任何宿主内容（具体概念请查阅相关内容：<span class="tcnt">JavaScript 本地对象、内置对象、宿主对象</span> ）。</p> - -<p>为了访问标签页的内容，你需要使用 tab.attach() 添加一个脚本，此 add-on 加载加载一个页面，然后将一个脚本附加到所有打开的标签页，该脚本将向标签页的文档添加红色边框：</p> -</div> - -<pre class="brush: js">require("sdk/ui/button/action").ActionButton({ - id: "list-tabs", - label: "List Tabs", - icon: "./icon-16.png", - onClick: listTabs -}); - -function listTabs() { - var tabs = require("sdk/tabs"); - for (let tab of tabs) - runScript(tab); -} - -function runScript(tab) { - tab.attach({ - contentScript: "document.body.style.border = '5px solid red';" - }); -} -</pre> - -<h2 id="学习更多">学习更多</h2> - -<p>要了解更多关于SDK中标签如何工作, 查看 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code> API reference</a>。</p> - -<p>要了解更多关于在标签中运行脚本, 查看 <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">tutorial on using <code>tab.attach()</code></a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/listen_for_page_load/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/listen_for_page_load/index.html deleted file mode 100644 index 815cfd42c5..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/listen_for_page_load/index.html +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 监听页面加载 -slug: Mozilla/Add-ons/SDK/Tutorials/Listen_for_Page_Load -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Listen_for_Page_Load ---- -<p>{{AddonSidebar}}</p> - -<div class="note"><span>学习本教程之前你需要了解 <a href="/en-US/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29"><code>jpm</code> 基础</a>。</span></div> - -<p>你可以使用 <a href="/zh-CN/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> 模块来获取关于新页面加载的通知。下面的附加组件监听标签页内建的 <code>ready</code> 事件，并且记录下每一个标签加载时的URL：</p> - -<pre class="brush: js">require("sdk/tabs").on("ready", logURL); - -function logURL(tab) { - console.log(tab.url); -} -</pre> - -<div class="note"> -<p>你会在<a href="/zh-CN/docs/Tools/Browser_Console">浏览器控制台</a>，而非 <a href="/zh-CN/docs/Tools/Web_Console">Web 控制台</a>中，找到这些输出的内容。</p> -</div> - -<p>你不能直接访问标签页里面的内容。</p> - -<p>为了访问标签页内容，你需要使用 <code>tab.attach()</code> 把一个脚本附到标签页上。这个示例给每一个打开后的标签页附上了一个脚本。这个脚本给标签页的 document 加上了一个红色边框：</p> - -<pre class="brush: js">require("sdk/tabs").on("ready", runScript); - -function runScript(tab) { - tab.attach({ - contentScript: "if (document.body) document.body.style.border = '5px solid red';" - }); -} -</pre> - -<p>（本示例仅仅表示：可以像这样实现一些功能，而你应当使用 <a href="/zh-CN/Add-ons/SDK/High-Level_APIs/page-mod"><code>page-mod</code></a>，并且指定匹配模式为 "*"。）</p> - -<h2 id="了解更多">了解更多</h2> - -<p>想要了解更多关于如何在SDK中处理标签页的内容，请看 <a href="/zh-CN/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code> API 参考</a>。你能够监听其他一些标签页事件，包括 <code>open</code>、<code>close</code>、和 <code>activate</code>。</p> - -<p>想要了解更多关于在标签页中运行脚本的事情，请看 <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab"><code>tab.attach() 使用教程</code></a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_the_page_hosted_by_a_tab/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_the_page_hosted_by_a_tab/index.html deleted file mode 100644 index 5fd51fd8f7..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_the_page_hosted_by_a_tab/index.html +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: 修改标签页中页面 -slug: Mozilla/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab -tags: - - Add-on SDK -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab ---- -<div class="note"> -<p>为了进一步学习本教程，你需要安装 <a href="/en-US/Add-ons/SDK/Tutorials/Installation">Add-on SDK</a> 和学习 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_With_cfx">cfx的基本使用</a></p> - -<p>这篇教程使用<a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">动作按钮</a>API，需要Firefox 29或更新版本。</p> -</div> - -<p>为了修改特定标签页中的页面, 可以使用<code> <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/tabs">tab</a></code>对象的<code>attach()</code> 方法加载一个script脚本到页面中。因为他们的工作是和Web内容进行交互，所以这些脚本被称为content scripts(内容脚本)。</p> - -<p>这是个简单的示例:</p> - -<pre class="brush: js">var button = require("sdk/ui/button/action").ActionButton({ - id: "style-tab", - label: "Style Tab", - icon: "./icon-16.png", - onClick: function() { - require("sdk/tabs").activeTab.attach({ - contentScript: 'document.body.style.border = "5px solid red";' - }); - } -});</pre> - -<p>要运行这个示例你必须保存一个名为”icon-16.png“的图标文件在你的Add-on目录下的”data”目录下。你可以下载这个图标： <img alt="" src="https://mdn.mozillademos.org/files/7661/icon-16.png" style="width: 16px; height: 16px;">。</p> - -<p>这个插件创建一个按钮，其中包含Mozilla的图标作为一个图标。这个按钮产生一个点击事件处理程序，处理事件中将获取当前活动标签页和加载一个脚本到该标签页中的页面。使用<code>contentscript</code>选项指定加载的脚本，该脚本只绘制一个红色边框页。</p> - -<p>然后在浏览器窗口中打开任何网页，点击按钮 。你会看到一个红色的边界出现在页面中, 就像这样:</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6531/tabattach-bbc.png" style="display: block; margin-left: auto; margin-right: auto;"></p> - -<h2 id="保持Content_Script在一个单独的文件中">保持Content Script在一个单独的文件中</h2> - -<p>在上面的例子中我们的<code>content script</code>作为一个字符串来直接使用.除非脚本非常简单，你应该保持脚本作为一个单独的文件。这使得代码更容易维护、调试和审查。</p> - -<p>比如，我们把上面的脚本代码保存在Add-on目录下的data目录中并取名为<code>my-script.js</code>，在代码中可以这样加载脚本：</p> - -<pre class="brush: js">var self = require("sdk/self"); - -var button = require("sdk/ui/button/action").ActionButton({ - id: "style-tab", - label: "Style Tab", - icon: "./icon-16.png", - onClick: function() { - require("sdk/tabs").activeTab.attach({ - contentScriptFile: self.data.url("my-script.js") - }); - } -}); -</pre> - -<p>你可以加载多个脚本，同时这些脚本可以直接相互作用。所以你可以加载 <a href="http://jquery.com/">jQuery</a>, 然后在你的其他 content script使用它。</p> - -<h2 id="与Content_Script传递信息">与Content Script传递信息</h2> - -<p>你的扩展插件脚本Add-on script和内容脚本content script 不能直接访问对方的变量和函数，但他们之间可以互相发送消息。</p> - -<p>从一方发送消息到另外一方, 发送方需要调用 <code>port.emit()发送消息，</code> 同时接收方使用<code>port.on()</code>接收消息。</p> - -<ul> - <li>在 content script 中, <code>port</code> 是全局对象 <code>self</code> 的属性之一.</li> - <li>在 content script 中, <code>tab.attach()</code> 返回一个其中包含 <code>port</code> 属性的 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker">worker</a> 对象，你可以使用它来向 content script 发送消息</li> -</ul> - -<p>让我们重写上面的例子来从附加内容脚本 content script 传递一个消息。现在content script 需要像下面这样:</p> - -<pre class="brush: js">// "self" is a global object in content scripts -// Listen for a "drawBorder" -self.port.on("drawBorder", function(color) { - document.body.style.border = "5px solid " + color; -}); -</pre> - -<p>在 add-on script 扩展脚本中，我们使用 <code>attach()方法返回的对象向 content script</code> 中发送一个“drawBorder”消息：</p> - -<pre class="brush: js">var self = require("sdk/self"); -var tabs = require("sdk/tabs"); - -var button = require("sdk/ui/button/action").ActionButton({ - id: "style-tab", - label: "Style Tab", - icon: "./icon-16.png", - onClick: function() { - var worker = tabs.activeTab.attach({ - contentScriptFile: self.data.url("my-script.js") - }); - worker.port.emit("drawBorder", "red"); - } -}); -</pre> - -<p>名为 <code>drawBorder</code> 的消息并不是一个内置的消息, 而是通过 <code>port.emit()方法自定义的。</code></p> - -<h2 id="注入_CSS">注入 CSS</h2> - -<p>不像 <a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod"><code>page-mod</code></a> API, <code>tab.attach()</code> 不允许你直接注入CSS到页面中。</p> - -<p>你需要使用 JavaScript 来修改页面的样式，就像前面的示例那样。</p> - -<h2 id="学习更多">学习更多</h2> - -<p>要了解更多关于在SDK中标签页的使用, 可以查看<a href="/en-US/Add-ons/SDK/Tutorials/Open_a_Web_Page">打开一个网页</a>教程, <a href="/en-US/Add-ons/SDK/Tutorials/List_Open_Tabs">列出打开的标签页</a>教程, 和<a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code> API 参考手册</a>.</p> - -<p>要学习更多关于content scripts, 查看 <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">content scripts guide</a>.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_web_pages_based_on_url/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_web_pages_based_on_url/index.html deleted file mode 100644 index 6e5e46c532..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/modifying_web_pages_based_on_url/index.html +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Modifying Web Pages Based on URL -slug: Mozilla/Add-ons/SDK/Tutorials/Modifying_Web_Pages_Based_on_URL -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Modifying_Web_Pages_Based_on_URL ---- -<div class="note">开始本教程之前，您必须安装好 <em><strong>SDK</strong></em>，并且学习 <strong><em>cfx </em></strong>的基本的使用方法。</div> - -<p>要修改任何页面匹配特定的模式（比如，“http://example.org/”）当它们加载后，使用<a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod">page-mod</a>模块。</p> - -<p>要创建 <strong><em>page-mod</em></strong>，您必须指定两件事：</p> - -<ul> - <li>一个或多个 <em><strong>content scripts</strong></em> 运行，它们的工作将和网站内容进行交互</li> - <li>一个或多个 <strong><em>patterns</em> </strong>去匹配您要修改的页面的 URLs</li> -</ul> - -<div class="note"> -<p>content scripts为内容脚本，只能使用普通浏览器支持的 JS，不能使用 add-on 的API</p> -</div> - -<p>这里有一个范例。内容脚本提供contentScript选项，地址样本提供include选项：</p> - -<pre class="brush: js">// Import the page-mod API -var pageMod = require("sdk/page-mod"); - -// Create a page mod -// It will run a script whenever a ".org" URL is loaded -// The script replaces the page contents with a message -pageMod.PageMod({ - include: "*.org", - contentScript: 'document.body.innerHTML = ' + - ' "<h1>Page matches ruleset</h1>";' -}); -</pre> - -<p>试试吧：</p> - -<ul> - <li>创建新的目录并转到该目录下</li> - <li>运行 <code>cfx init</code></li> - <li>打开 <code>lib/main.js</code> 文件，添加以上的代码</li> - <li>运行 <code>cfx run</code></li> - <li>在打开的浏览器窗口中打开 <a href="http://www.ietf.org">ietf.org</a></li> -</ul> - -<p>您将看到：</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/6537/pagemod-ietf.png" style="display: block; margin-left: auto; margin-right: auto;"></p> - -<h2 id="指定匹配模式">指定匹配模式</h2> - -<p>匹配模式使用 <a href="/en-US/Add-ons/SDK/Low-Level_APIs/util_match-pattern"><code>match-pattern</code></a> 语法。您可以通过单一的匹配字符串，或者数组。</p> - -<h2 id="把内容脚本放在独立的文件中">把内容脚本放在独立的文件中</h2> - -<p>在上面的范例中我们通过字符串来实现内容脚本。除非是用作简单的例子，通常情况下您应该将内容脚本放在独立文件中，这将使您的代码更易维护、调式和查看。</p> - -<p>要这样做，您需要：</p> - -<ul> - <li>将脚本文件保存在 data 目录下</li> - <li>使用 <code>contentScriptFile</code> 选项代替 <code>contentScript 选项，并且指定脚本的路径</code>。路径用 <code>self.data.url()</code> 取得</li> -</ul> - -<p>例如，如果我们将内容脚本保存在 data 目录下，命名为 my-script.js，在main.js中，我们应该这么写：</p> - -<pre class="brush: js">// Import the page-mod API -var pageMod = require("sdk/page-mod"); -// Import the self API -var self = require("sdk/self"); - -// Create a page mod -// It will run a script whenever a ".org" URL is loaded -// The script replaces the page contents with a message -pageMod.PageMod({ - include: "*.org", - contentScriptFile: self.data.url("my-script.js") -});</pre> - -<h2 id="加载多个Content_Scripts">加载多个Content Scripts</h2> - -<p>您可以加载更多脚本，且脚本可以相互交互。所以，您可以使用jQuery重写 my-script.js：</p> - -<pre class="brush: js">$("body").html("<h1>Page matches ruleset</h1>"); -</pre> - -<p>然后下载 jQuery 库到您的扩展开发目录的 data 目录下，并且将 jQuery 和 my-script 一起加载（确保先加载 jQuery 库）：</p> - -<pre class="brush: js">// Import the page-mod API，加载 add-on 的 page-mod API -var pageMod = require("sdk/page-mod"); -// Import the self API, 加载 add-on 的 self API -var self = require("sdk/self"); - -// Create a page mod -// It will run a script whenever a ".org" URL is loaded -// The script replaces the page contents with a message -// 创建 page mod，匹配 “.org” URL -pageMod.PageMod({ - include: "*.org", - contentScriptFile: [self.data.url("jquery-1.7.min.js"), self.data.url("my-script.js")] -}); -</pre> - -<p>您也可以在同一 page-mod 中同时使用 <code>contentScript</code> 和 <code>contentScriptFile</code> 。如果您这么做的话，contentScript的脚本将会先加载。（应该是contentScriptFile的先加载吧？）</p> - -<pre class="brush: js">// Import the page-mod API -var pageMod = require("sdk/page-mod"); -// Import the self API -var self = require("sdk/self"); - -// Create a page mod -// It will run a script whenever a ".org" URL is loaded -// The script replaces the page contents with a message -pageMod.PageMod({ - include: "*.org", - contentScriptFile: self.data.url("jquery-1.7.min.js"), - contentScript: '$("body").html("<h1>Page matches ruleset</h1>");' -}); -</pre> - -<p>注意，您不能直接加载网站上的脚本。脚本必须从 data 目录中加载。</p> - -<h2 id="与_Content_Script_通信">与 Content Script 通信</h2> - -<p>Your add-on script and the content script can't directly access each other's variables or call each other's functions, but they can send each other messages.</p> - -<p>从 Content Script 与 main.js 通信，发送方使用 <code>port.emit()</code> ，接收方使用 <code>port.on()</code> 监听.</p> - -<ul> - <li>In the content script, <code>port</code> is a property of the global <code>self</code> object.</li> - <li>In the add-on script, you need to listen for the <code>onAttach</code> event to get passed a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker">worker</a> object that contains <code>port</code>.</li> -</ul> - -<p>Let's rewrite the example above to pass a message from the add-on to the content script. The message will contain the new content to insert into the document. The content script now needs to look like this:</p> - -<pre class="brush: js">// "self" is a global object in content scripts -// Listen for a message, and replace the document's -// contents with the message payload. -self.port.on("replacePage", function(message) { - document.body.innerHTML = "<h1>" + message + "</h1>"; -}); -</pre> - -<p>In the add-on script, we'll send the content script a message inside <code>onAttach</code>:</p> - -<pre class="brush: js">// Import the page-mod API -var pageMod = require("sdk/page-mod"); -// Import the self API -var self = require("sdk/self"); - -// Create a page mod -// It will run a script whenever a ".org" URL is loaded -// The script replaces the page contents with a message -pageMod.PageMod({ - include: "*.org", - contentScriptFile: self.data.url("my-script.js"), - // Send the content script a message inside onAttach - onAttach: function(worker) { - worker.port.emit("replacePage", "Page matches ruleset"); - } -}); -</pre> - -<p>The <code>replacePage</code> message isn't a built-in message: it's a message defined by the add-on in the <code>port.emit()</code> call.</p> - -<h2 id="注入_CSS">注入 CSS</h2> - -<div class="warning"> -<p><strong>请注意，本节中描述的功能是实验性的：我们很可能继续支持的功能，但可能需要改变的细节。</strong></p> -</div> - -<p>Rather than injecting JavaScript into a page, you can inject CSS by setting the page-mod's <code>contentStyle</code> option:</p> - -<pre class="brush: js">var pageMod = require("sdk/page-mod").PageMod({ - include: "*", - contentStyle: "body {" + - " border: 5px solid green;" + - "}" -}); -</pre> - -<p>As with <code>contentScript</code>, there's a corresponding <code>contentStyleFile</code> option that's given the URL of a CSS file in your "data" directory, and it is good practice to use this option in preference to <code>contentStyle</code> if the CSS is at all complex:</p> - -<pre class="brush: js">var pageMod = require("sdk/page-mod").PageMod({ - include: "*", - contentStyleFile: require("sdk/self").data.url("my-style.css") -}); -</pre> - -<p>You can't currently use relative URLs in style sheets loaded with <code>contentStyle</code> or <code>contentStyleFile</code>. If you do, the files referenced by the relative URLs will not be found.</p> - -<p>To learn more about this, and read about a workaround, see the <a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod#PageMod(options)">relevant section in the page-mod API documentation</a>.</p> - -<h2 id="Learning_More">Learning More</h2> - -<p>To learn more about <code>page-mod</code>, see its <a href="/en-US/Add-ons/SDK/High-Level_APIs/page-mod">API reference page</a>. In particular, the <code>PageMod</code> constructor takes several additional options to control its behavior:</p> - -<ul> - <li> - <p>By default, content scripts are not attached to any tabs that are already open when the page-mod is created, and are attached to iframes as well as top-level documents. To control this behavior use the <code>attachTo</code> option.</p> - </li> - <li> - <p>Define read-only values accessible to content scripts using the <code>contentScriptOptions</code> option.</p> - </li> - <li> - <p>By default, content scripts are attached after all the content (DOM, JS, CSS, images) for the page has been loaded, at the time the <a href="/en-US/docs/Web/API/GlobalEventHandlers.onload">window.onload event</a> fires. To control this behavior use the <code>contentScriptWhen</code> option.</p> - </li> -</ul> - -<p>To learn more about content scripts in general, see the <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">content scripts guide</a>.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/open_a_web_page/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/open_a_web_page/index.html deleted file mode 100644 index 7ff9ba7883..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/open_a_web_page/index.html +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 打开Web页面 -slug: Mozilla/Add-ons/SDK/Tutorials/Open_a_Web_Page -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Open_a_Web_Page ---- -{{AddonSidebar}} - -<div class="note"><span>学习本教程之前你需要学习 <a href="/zh-CN/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29"><code>jpm</code> 基础</a>。</span></div> - -<p>打开一个新的网页，你可以使用 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code></a> 模块：</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.open({ -"http://www.example.com"); -</pre> - -<p>这个函数是异步的，所以你不能立即获取一个可以检查的标签对象。要做到这一点，通过一个回调函数为open()。将回调函数赋值给 onready 属性，并将通过标签作为参数：</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.open({ - url: "http://www.example.com", - onReady: function onReady(tab) { - console.log(tab.title); - } -}); -</pre> - -<div class="warning"> -<p>尽管这样，你还是不能直接访问到标签页中的任何宿主内容（具体概念请查阅相关内容：<span class="tcnt">JavaScript 本地对象、内置对象、宿主对象</span> ）。</p> -</div> - -<p> -要访问标签页的内容，你需要使用 tab.attach()把一个脚本添加到该标签页。此add-on加载加载一个页面，然后将一个脚本附加到该页，该将向页面添加红色边框：</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.open({ - url: "http://www.example.com", - onReady: runScript -}); - -function runScript(tab) { - tab.attach({ - contentScript: "document.body.style.border = '5px solid red';" - }); -} -</pre> - -<h2 id="学习更多">学习更多</h2> - -<p>要了解更多关于SDK中标签如何工作, 查看 <a href="/en-US/Add-ons/SDK/High-Level_APIs/tabs"><code>tabs</code> API reference</a>.</p> - -<p>要了解更多关于在标签中运行脚本, 查看 <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">tutorial on using <code>tab.attach()</code></a>.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/troubleshooting/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/troubleshooting/index.html deleted file mode 100644 index afa3cc0cd3..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/troubleshooting/index.html +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Troubleshooting -slug: Mozilla/Add-ons/SDK/Tutorials/Troubleshooting -tags: - - add-on sdk 安装指南 - - add-on sdk安装解惑 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Troubleshooting ---- -<p>{{AddonSidebar}}</p> - -<p>如果你的SDK安装和运行遇到了问题，不要慌！本页面列出了一些基本点，来帮助你追踪你的问题。</p> - -<h2 id="检查你的_Firefox">检查你的 Firefox</h2> - -<p><code>jpm</code> 会搜索你系统中 Firefox 常见的地址，<code>jpm</code> 也许不能找到火狐安装在哪，或者你有多个地方安装了火狐，<code>jpm</code> 也许找错了地方。这种情况下，你需要使用 <code>jpm</code> 的 <code>--binary</code> 选项。参看 <code><a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a></code> 指南以获取更多信息</p> - -<p>当你运行 <code>jpm</code> 来测试你的 add-on 或者运行单元测试时，它会打印出 Firefox 或 XULRunner 二进制文件的地址，所有你可以检查一下它的输出内容来做确认。</p> - -<h2 id="检查你的文本控制台">检查你的文本控制台</h2> - -<p>当你的代码代码和SKD的API产生错误时，他们会被记录到文本控制台。这应该和你运行 <code>jpm</code> 命令的是同一控制台或shell</p> - -<h2 id="搜索已知的问题">搜索已知的问题</h2> - -<p>也许有人已经遇到过和你一样的问题了。其他用户经常发布问题到 <a href="http://groups.google.com/group/mozilla-labs-jetpack/topics">项目邮件列表</a>。你也可以浏览<a href="https://bugzilla.mozilla.org/buglist.cgi?order=Bug%20Number&resolution=---&resolution=DUPLICATE&query_format=advanced&product=Add-on%20SDK">已知问题</a>列表或者<a href="https://bugzilla.mozilla.org/query.cgi?format=advanced&product=Add-on%20SDK">搜索</a>特定的关键词。</p> - -<h2 id="与项目团队和用户组交流">与项目团队和用户组交流</h2> - -<p>SDK的用户和项目团队成员对问题和建议在 <a href="http://groups.google.com/group/mozilla-labs-jetpack/topics">项目的邮件列表</a>. 别人可能有与你相同的问题，所以试着搜索列表。也欢迎你发表问题.</p> - -<p>你也可以与其他SDK用户在 <a href="http://irc.mozilla.org/">Mozilla的 IRC 网络</a> 的 <a href="http://mibbit.com/?channel=%23jetpack&server=irc.mozilla.org">#jetpack</a> 聊天室聊天.</p> - -<p>如果你想<a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Add-on%20SDK&component=General">报告SDK的bug</a><span>，我们非常欢迎！您将需要创建一个 Bugzilla 的帐号，Bugzilla 是 Mozilla 的 bug 追踪系统。</span></p> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> - -<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/unit_testing/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/unit_testing/index.html deleted file mode 100644 index 63cd86da13..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/unit_testing/index.html +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Unit Testing -slug: Mozilla/Add-ons/SDK/Tutorials/Unit_testing -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Unit_testing ---- -<div class="note"> - <p><span>学习本教程你将需要<a href="/en-US/Add-ons/SDK/Tutorials/Installation">安装SDK</a>, 学习 <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_With_cfx">基本操作<code>cfx</code></a>,和学习过<a href="/en-US/Add-ons/SDK/Tutorials/Creating_reusable_modules">编写可重复模块(writing reusable modules)</a>.</span></p> -</div> -<div class="note"> - <p>如果你在使用 <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm</a> 而不是 cfx, 请看关于cfx, 而且重点看<a href="/en-US/Add-ons/SDK/Tools/cfx_to_jpm#Requiring_modules_from_test_code">加载测试模块(loading modules from test code)</a>.</p> -</div> -<p>SDK提供了一个框架,为你的代码创建和运行单元测试.接下来我们将演示如何写一个关于<a href="http://en.wikipedia.org/wiki/Base64">Base64</a> 模块的单元测试.</p> -<h2 id="一个Base64模块例子">一个Base64模块例子</h2> -<p>在一个网页中, 你可以进行Base64的加密和解密,通过使用函数<code>btoa()</code> and <code>atob()</code> .不幸的是这些函数依附在<code>window</code>对象: 由于这个对象在你的add-on(插件) main 的代码里不是有效对象,所以 <code>atob()</code> and <code>btoa()</code> 也不是有效的. 因此我们将展示如何在这个平台上创建一个<code>base64</code>模块 .</p> -<p>To begin with, create a new directory, navigate to it, and run <code>cfx init</code>. Now create a new file in "lib" called "base64.js", and give it the following contents:</p> -<pre class="brush: js">const { atob, btoa } = require("chrome").Cu.import("resource://gre/modules/Services.jsm", {}); - -exports.atob = a => atob(a); -exports.btoa = b => btoa(b); -</pre> -<p>This code exports two functions, which just call the platform's <code>btoa()</code> and <code>atob()</code> functions. To show the module in use, edit the "main.js" file as follows:</p> -<pre class="brush: js">var base64 = require("./base64"); - -var button = require("sdk/ui/button/action").ActionButton({ - id: "base64", - label: "base64", - icon: "./icon-16.png", - onClick: function() { - encoded = base64.btoa("hello"); - console.log(encoded); - decoded = base64.atob(encoded); - console.log(decoded); - } -});</pre> -<p>To run this example you'll also have to have an icon file named "icon-16.png" saved in your add-ons "data" directory. You could download this icon: <img alt="" src="https://mdn.mozillademos.org/files/7661/icon-16.png" style="width: 16px; height: 16px;">.</p> -<p>Now "main.js" imports the base64 module and calls its two exported functions. If we run the add-on and click the button, we should see the following logging output:</p> -<pre>info: aGVsbG8= -info: hello -</pre> -<h2 id="Testing_the_Base64_Module">Testing the Base64 Module</h2> -<p>Navigate to the add-on's <code>test</code> directory and delete the <code>test-main.js</code> file. In its place create a file called <code>test-base64.js</code> with the following contents:</p> -<pre class="brush: js">var base64 = require("./base64"); - -exports["test atob"] = function(assert) { - assert.ok(base64.atob("aGVsbG8=") == "hello", "atob works"); -} - -exports["test btoa"] = function(assert) { - assert.ok(base64.btoa("hello") == "aGVsbG8=", "btoa works"); -} - -exports["test empty string"] = function(assert) { - assert.throws(function() { - base64.atob(); - }, - "empty string check works"); -} - -require("sdk/test").run(exports); -</pre> -<p>This file: exports three functions, each of which expects to receive a single argument which is an <code>assert</code> object. <code>assert</code> is supplied by the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/test_assert"><code>test/assert</code></a> module and implements the <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification</a>.</p> -<ul> - <li> - <p>The first two functions call <code>atob()</code> and <code>btoa()</code> and use <a href="/en-US/Add-ons/SDK/Low-Level_APIs/test_assert#ok(guard.2C_message)"><code>assert.ok()</code></a> to check that the output is as expected.</p> - </li> - <li> - <p>The second function tests the module's error-handling code by passing an empty string into <code>atob()</code> and using <a href="/en-US/Add-ons/SDK/Low-Level_APIs/test_assert#throws(block.2C_error.2C_message)"><code>assert.throws()</code></a> to check that the expected exception is raised.</p> - </li> -</ul> -<p>At this point your add-on ought to look like this:</p> -<pre> /base64 - package.json - README.md - /doc - main.md - /lib - main.js - base64.js - /test - test-base64.js -</pre> -<p>Now execute <code>cfx --verbose test</code> from the add-on's root directory. You should see something like this:</p> -<pre>Running tests on Firefox 13.0/Gecko 13.0 ({ec8030f7-c20a-464f-9b0e-13a3a9e97384}) under darwin/x86. -info: executing 'test-base64.test atob' -info: pass: atob works -info: executing 'test-base64.test btoa' -info: pass: btoa works -info: executing 'test-base64.test empty string' -info: pass: empty string check works - -3 of 3 tests passed. -Total time: 5.172589 seconds -Program terminated successfully. -</pre> -<p>What happens here is that <code>cfx test</code>:</p> -<p><span>Note the hyphen after "test" in the module name. <code>cfx test</code> will include a module called "test-myCode.js", but will exclude modules called "test_myCode.js" or "testMyCode.js".</span></p> -<ul> - <li>looks in the <code>test</code> directory of your package</li> - <li>loads any modules whose names start with the word <code>test-</code></li> - <li>calls each exported function whose name starts with "test", passing it an <a href="/en-US/Add-ons/SDK/Low-Level_APIs/test_assert#Assert"><code>assert</code></a> object as its only argument.</li> -</ul> -<p>Obviously, you don't have to pass the <code>--verbose</code> option to <code>cfx</code> if you don't want to; doing so just makes the output easier to read.</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/日志/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/日志/index.html deleted file mode 100644 index e581a0811c..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/日志/index.html +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: 日志 -slug: Mozilla/Add-ons/SDK/Tutorials/日志 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Logging ---- -<p>{{AddonSidebar}}</p> - -<div class="note"><span>学习本教程之前你需要学习 </span><span><a href="/en-US/docs/Mozilla/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29">jpm 基础</a>. </span></div> - -<p><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); display: inline !important; float: none; font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><a href="https://developer.mozilla.org/en/DOM/console">DOM console</a> 对象对调试 Javascript 非常有帮助。但是由于扩展程序无法访问 DOM 对象，sdk 提供了一个拥有大部分 DOM console 对象方法的全局 console 对象，包括打印错误日车、警告和数据信息的方法。你无需 require() 任何模块，就可以直接使用 console 对象。</span></p> - -<p><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); display: inline !important; float: none; font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;">使用 console.log() 方法来打印信息：</span></p> - -<pre class="brush: js">console.log("Hello World"); -</pre> - -<p style="margin-bottom: 1.5em; width: inherit; position: relative; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><span class="md-line" style="display: block; width: 516px;"><span class="md-expand" style="">尝试：</span></span></p> - -<ul style="margin: -1em 0px 1.5em 1.5em; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"> - <li style="margin: 0px; position: relative; list-style-type: disc;"> - <p style="margin: 0.5rem 0px; width: inherit; position: relative;"><span class="md-line" style="display: block; width: 452px;"><span style="">新建一个目录，打开它</span></span></p> - </li> - <li style="margin: 0px; position: relative; list-style-type: disc;"> - <p style="margin: 0.5rem 0px; width: inherit; position: relative;"><span class="md-line" style="display: block; width: 452px;"><span style="">执行 </span><span style=""><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">jpm init</code></span><span style="">，接受所有默认设置</span></span></p> - </li> - <li style="margin: 0px; position: relative; list-style-type: disc;"> - <p style="margin: 0.5rem 0px; width: inherit; position: relative;"><span class="md-line" style="display: block; width: 452px;"><span style="">打开 "index.js"，并在文件内添加上面的代码</span></span></p> - </li> - <li style="margin: 0px; position: relative; list-style-type: disc;"> - <p style="margin: 0.5rem 0px; width: inherit; position: relative;"><span class="md-focus md-line" style="display: block; width: 452px;"><span style="">执行 </span><span style=""><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">jpm run</code></span></span></p> - </li> -</ul> - -<p><span class="md-expand" style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;">Firefox 将会启动，并在你执行 </span><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">jpm run</code></span><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"> 的命令行窗口显示下面的信息：</span></p> - -<pre>console.log: console: Hello world -</pre> - -<h2 id="在内容脚本（conent_script）中使用_console"><code>在内容脚本（conent script）中使用 console</code></h2> - -<p><span class="md-expand" style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;">与 addon 主代码一样，你可以在<a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">内容脚本</a>中直接使用 console 对象。下面这个扩展在内容脚本中调用了 </span><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">console.log()</code></span><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"> 方法，作用是在控制台打印出每个打开的标签页内的 HTML 内容：</span></p> - -<pre class="brush: js">require("sdk/tabs").on("ready", function(tab) { - tab.attach({ - contentScript: "console.log(document.body.innerHTML);" - }); -}); -</pre> - -<h2 id="控制台输出"><span style="">控制台输出</span></h2> - -<p style="margin-bottom: 1.5em; width: inherit; position: relative; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><span class="md-line" style="display: block; width: 516px;"><span style="">如果你是在命令行启动你的扩展（例如：执行 </span><span style=""><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">jpm run</code></span><span style=""> 或 </span><span style=""><code style="font-family: monospace, monospace; font-size: 0.875em; text-align: left; padding-left: 1ch; padding-right: 1ch; line-height: 1.71428em; background-color: rgb(218, 218, 218);">jpm test</code></span><span style="">），那么控制台信息将在你使用的命令行界面中显示。</span></span></p> - -<p style="margin-bottom: 1.5em; width: inherit; position: relative; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><span class="md-line" style="display: block; width: 516px;"><span style="">如果你将扩展安装到了 Firefox 中，控制台信息将显示在 Firefox <a href="/en-US/docs/Tools/Browser_Console">浏览器控制台</a>中。</span></span></p> - -<p style="margin-bottom: 1.5em; width: inherit; position: relative; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><span class="md-line" style="display: block; width: 516px;"><span style="">但请注意，<strong>默认情况下，任何已经安装的扩展不会在错误控制台中输出任何信息</strong>，包括使用扩展构建程序安装的扩展或者使用其它工具例如：<a href="https://addons.mozilla.org/en-US/firefox/addon/autoinstaller/">Extension Auto-installer</a>。</span></span></p> - -<p style="margin-bottom: 1.5em; width: inherit; position: relative; color: rgb(31, 9, 9); font-family: 'PT Serif', 'Times New Roman', Times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;"><span class="md-focus md-line" style="display: block; width: 516px;"><span style="">关于此项内容的更多信息请参阅控制台参考文档 “<a href="/en-US/Add-ons/SDK/Tools/console#Logging_Levels">日志等级</a>”。</span></span></p> - -<h2 id="更多">更多</h2> - -<p><span style="background-color: rgb(243, 242, 238); color: rgb(31, 9, 9); display: inline !important; float: none; font-family: pt serif,times new roman,times; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 24px; text-align: start; text-indent: 0px; text-transform: none; white-space: pre-wrap;">完整的 console API，请看 </span> <a href="/en-US/Add-ons/SDK/Tools/console">API 参考文档</a>。</p> diff --git a/files/zh-cn/mozilla/add-ons/sdk/tutorials/添加一个菜单项/index.html b/files/zh-cn/mozilla/add-ons/sdk/tutorials/添加一个菜单项/index.html deleted file mode 100644 index 77d743e806..0000000000 --- a/files/zh-cn/mozilla/add-ons/sdk/tutorials/添加一个菜单项/index.html +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 添加菜单项 -slug: Mozilla/Add-ons/SDK/Tutorials/添加一个菜单项 -translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/Add_a_Context_Menu_Item ---- -<div class="note"> - <p>学习本章前，您要先 <a href="/en-US/Add-ons/SDK/Installation">安装SDK</a> 和学习 <a href="/en-US/Add-ons/SDK/Getting_Started_With_cfx"><code>cfx</code>的基本用法 </a></p> -</div> -<p>用<a href="/en-US/Add-ons/SDK/High-Level_APIs/context-menu"><code>右键菜单</code></a>模块添加右键菜单项或子菜单</p> -<p>下面的例子是增加了一个新的上下文菜单项。当页面被选中时才会显示该菜单项，选择的部分会被发送到main.js的add-on代码中，它只是记录：</p> -<pre class="brush: js">var contextMenu = require("sdk/context-menu"); - var menuItem = contextMenu.Item({ - label: "Log Selection", - context: contextMenu.SelectionContext(), - contentScript: 'self.on("click", function () {' + - ' var text = window.getSelection().toString();' + - ' self.postMessage(text);' + - '});', - onMessage: function (selectionText) { - console.log(selectionText); - } -});</pre> -<p>Try it: run the add-on, load a web page, select some text and right-click. You should see the new item appear:</p> -<p>试一试：运行该扩展，加载一个网页，选中一些文本并右键单击。你应该能看到新的项目出现：</p> -<p><img src="https://mdn.mozillademos.org/files/6513/context-menu-selection.png" style="display: block; margin-left: auto; margin-right: auto;"></p> -<p>点击，选中的文本<a href="/en-US/Add-ons/SDK/Tutorials/Logging">记录到控制台</a>:</p> -<pre>info: elephantine lizard -</pre> -<h2 id="细节">细节</h2> -<p><br> - 这个add-on所有的操作是构建一个上下文菜单项。你不需要添加它：一旦你已经建立了项目，它会自动添加在正确的上下文。在这种情况下，构造函数接受四个选项：<code>label</code>，<code>context</code>，和contentscript，onMessage。</p> -<h3 id="label">label</h3> -<p><br> - 标签是字符串的显示。</p> -<h3 id="context">context</h3> -<p><br> - 上下文应该在不同的情境中显示它该做的显示。上下文菜单模块提供了一些简单的内置的上下文，包括selectioncontext()，这意味着：当页面被选中的时候将会显示菜单项。<br> - 如果这些简单的背景是不够的，你可以使用脚本定义更复杂的环境。</p> -<h3 id="contentScript">contentScript</h3> -<p>这将一个脚本项目。在这种情况下，脚本侦听用户点击该项目，然后选定文本用消息发送到add-on。</p> -<h3 id="onMessage">onMessage</h3> -<p>onMessage属性提供附加的代码来响应来自连接到上下文菜单项脚本报文的一种方法。在这种情况下，它只是记录选定的文本。</p> -<p>所以：<br> - 用户点击项目<br> - 内容脚本的点击事件触发，和内容脚本检索选定的文本和发送邮件的附件<br> - 附加的消息事件触发，并附加代码的处理函数是通过选定的文本，它的日志<br> - </p> -<h2 id="获取更多">获取更多</h2> -<p>如果想获取更多信息关于<code>context-menu</code>模块，查看<a href="/en-US/Add-ons/SDK/High-Level_APIs/context-menu"><code>context-menu</code> API reference</a>.</p> |