diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/sdk/high-level_apis')
8 files changed, 0 insertions, 2905 deletions
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> |