diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/sdk/high-level_apis/tabs/index.html')
| -rw-r--r-- | files/fr/mozilla/add-ons/sdk/high-level_apis/tabs/index.html | 669 |
1 files changed, 0 insertions, 669 deletions
diff --git a/files/fr/mozilla/add-ons/sdk/high-level_apis/tabs/index.html b/files/fr/mozilla/add-ons/sdk/high-level_apis/tabs/index.html deleted file mode 100644 index 5ffa11d9a4..0000000000 --- a/files/fr/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">Ouvre, manipule, accède et recevoir les événements des onglets.</span></p> - -<h2 id="Utilisation">Utilisation</h2> - -<h3 id="Ouvrez_un_onglet">Ouvrez un onglet</h3> - -<p>Vous pouvez ouvrir un nouvel onglet, en spécifiant diverses propriétés, y compris l'emplacement:</p> - -<pre class="brush: js">var tabs = require("sdk/tabs"); -tabs.open("http://www.example.com");</pre> - -<h3 id="Track_tabs">Track tabs</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="Access_tabs">Access tabs</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="Track_a_single_tab">Track a single tab</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="Manipulate_a_tab">Manipulate a tab</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="Run_scripts_in_a_tab">Run scripts in a tab</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="Attaching_stylesheets">Attaching stylesheets</h3> - -<div class="geckoVersionNote"> -<p>New in 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="Private_windows">Private windows</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="Converting_to_XUL_tabs">Converting to XUL tabs</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="Globals">Globals</h2> - -<h3 id="Functions">Functions</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>Example</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="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>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>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>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="Properties">Properties</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>Example</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="Events">Events</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="Arguments">Arguments</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="Arguments_2">Arguments</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="Arguments_3">Arguments</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="Arguments_4">Arguments</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="Arguments_5">Arguments</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="Methods">Methods</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="Parameters_2">Parameters</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>Example</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="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>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="Returns">Returns</h5> - -<p><strong>Worker</strong> : The <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker">Worker</a> object can be used to communicate with the content script. See <a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Content Scripts guide</a> to learn the details.</p> - -<h3 id="Properties_2">Properties</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>The <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow"><code>window</code></a> object for this tab.</p> - -<h4 class="addon-sdk-api-name" id="readyState"><code>readyState</code></h4> - -<div class="geckoVersionNote"> -<p>New in 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="Events_2">Events</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="Arguments_6">Arguments</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="Arguments_7">Arguments</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="Arguments_8">Arguments</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="Arguments_9">Arguments</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="Arguments_10">Arguments</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="Arguments_11">Arguments</h5> - -<p><strong>Tab</strong> : Listeners are passed the tab object.</p> |