diff options
Diffstat (limited to 'files/ru/mozilla/add-ons/загрузочные_расширения/index.html')
| -rw-r--r-- | files/ru/mozilla/add-ons/загрузочные_расширения/index.html | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/files/ru/mozilla/add-ons/загрузочные_расширения/index.html b/files/ru/mozilla/add-ons/загрузочные_расширения/index.html deleted file mode 100644 index 934e40e904..0000000000 --- a/files/ru/mozilla/add-ons/загрузочные_расширения/index.html +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: Загружаемые расширения -slug: Mozilla/Add-ons/загрузочные_расширения -tags: - - Bootstrapped - - Extensions - - add-on - - Дополнения -translation_of: Archive/Add-ons/Bootstrapped_extensions ---- -<div class="blockIndicator warning"> -<p>Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.</p> -</div> - -<p>{{LegacyAddonsNotice}}{{AddonSidebar}}</p> - -<p>{{ gecko_minversion_header("2.0") }}</p> - -<p>К традиционным расширениям относятся оверлеи (<strong>overlays</strong>), в их случае приложение может загрузить XUL из пакета расширения и автоматически применить их на верхнем слое своего UI (интерфейса пользователя). При этом создаются расширения, которые добавляются в пользовательский интерфейс относительно легко, но в этом случае обновление, установка или отмена действия расширения требуют перезагрузку приложения.</p> - -<p>Движок Gecko 2.0 {{ geckoRelease("2.0") }} вводит <strong>загружаемые расширения</strong> (<strong>bootstrapped extensions</strong>). Это специальные расширения, которые вместо использования наложения на интерфейс, сами програмно добавляют себя в приложение. Это делается запуском специального скрипта из файла, который включен в расширение и содержит функции, вызываемые браузером, для того чтобы установить, удалить, загрузить, выгрузить.</p> - -<p>Приложение делает вызовы из из этого файла со скриптом; расширение ответственно за добавление и удаление своего интерфейса пользователя и обработку любых других установок и завершения задач, которые требовались в процессе работы.</p> - -<p>Эта статья поясняет как работают загружаемые расширения. Изучите следующее <a href="/en-US/Add-ons/How_to_convert_an_overlay_extension_to_restartless">руководство по преобразованию приложений-оверлеев (overlay) в приложения, не требующие перезагрузки (restartless, то есть bootstrapped)</a>, для получения пошагового руководства по переходу.</p> - -<h2 id="The_startup_and_shutdown_process">The startup and shutdown process</h2> - -<p>A key feature of bootstrapped extensions is that they must be able to start up and shut down on demand by the application. When the extension's <code>startup()</code> function is called, it must manually inject its user interface and other behavior into the application. Similarly, when its <code>shutdown()</code> function is called, it must remove anything that it has added to the application, as well as all references to any of its objects.</p> - -<p>There are several scenarios in which the <code>startup()</code> function may be called; for example:</p> - -<ul> - <li>When the extension is first installed, assuming that it's both compatible with the application and is enabled.</li> - <li>When the extension becomes enabled using the add-ons manager window.</li> - <li>When the application is started up, if the extension is enabled and compatible with the application.</li> -</ul> - -<p>Some examples of when the <code>shutdown()</code> function may be called:</p> - -<ul> - <li>When the extension is uninstalled, if it's currently enabled.</li> - <li>When the extension becomes disabled.</li> - <li>When the user quits the application, if the extension is enabled.</li> -</ul> - -<h2 id="Notes_on_modifying_the_application_user_interface">Notes on modifying the application user interface</h2> - -<h3 id="chrome.manifest_in_bootstrapped_add-ons">chrome.manifest in bootstrapped add-ons</h3> - -<p>You can use a <a href="/en-US/docs/Chrome_Registration"><code>chrome.manifest</code></a> file in bootstrapped add-ons to:</p> - -<ul> - <li>Make your add-on's content available via a <code>chrome://</code> URL (using the <code>content</code>, <code>locale</code>, and <code>skin</code> instructions in the manifest).</li> - <li>Replace existing <code>chrome://</code> URIs with your content (using the <code>override</code> instruction).</li> -</ul> - -<p>Not all <code>chrome.manifest</code> instructions are supported in bootstrapped add-ons, for example you still cannot register <a href="/en-US/docs/XUL_Overlays">XUL Overlays</a> from a bootstrapped add-on. See the <a href="/en-US/docs/Chrome_Registration"><code>chrome.manifest</code></a> documentation for details.</p> - -<p>In Firefox 10 and later the <code>chrome.manifest</code> file located in the root of the add-on's XPI (i.e. a sibling of the <code>install.rdf</code>) is loaded automatically. In Firefox 8 and 9 you had to load/unload the manifest manually using {{ ifmethod("nsIComponentManager", "addBootstrappedManifestLocation") }} and {{ ifmethod("nsIComponentManager", "removeBootstrappedManifestLocation") }}. This feature was unavailable in Firefox versions before 8.</p> - -<h3 id="Adding_user_interface_manually">Adding user interface manually</h3> - -<p>If you decide to go ahead and try to develop a bootstrapped extension that modifies the application's user interface, here are a few suggestions to get you started.</p> - -<p>You need to look up the relevant application UI elements by their ID by calling {{ domxref("document.getElementById()") }}, then manipulate them to inject your UI. For example, you can get access to the menu bar in Firefox with <code>document.getElementById("main-menubar")</code>.</p> - -<p>Be sure that at shutdown time, you remove any user interface you've added.</p> - -<h2 id="Creating_a_bootstrapped_extension">Creating a bootstrapped extension</h2> - -<p>To mark an extension as bootstrappable, you need to add the following element to its <a href="/en-US/docs/Install_Manifests">install manifest</a>:</p> - -<pre><code><em:bootstrap>true</em:bootstrap></code></pre> - -<p>Then you need to add a <a href="/en-US/docs/Extensions/bootstrap.js"><code><strong>bootstrap.js</strong></code> file</a> that contains the required functions; this should be alongside the <a href="/en-US/docs/Install_Manifests"><code>install.rdf</code> file</a> in the extension's package.</p> - -<h3 id="Backward_compatibility">Backward compatibility</h3> - -<p>Because older versions of Firefox don't know about the <code>bootstrap</code> property or <code>bootstrap.js</code> file, it's not overly difficult to create an XPI that will work on both as a bootstrappable extension and as a traditional extension. Create your extension as a bootstrappable extension, then add the traditional overlays as well. Newer versions of Firefox will use the <code>bootstrap.js</code> script, ignoring the components and overlays, while older versions will use the overlays.</p> - -<h2 id="Bootstrap_entry_points">Bootstrap entry points</h2> - -<p>The <code>bootstrap.js</code> script should contain several specific functions, which are called by the browser to manage the extension. The script gets executed in a privileged sandbox, which is cached until the extension is shut down.</p> - -<h3 id="startup">startup</h3> - -<p>Called when the extension needs to start itself up. This happens at application launch time, when the extension is enabled after being disabled or after it has been shut down in order to install an update. As such, this can be called many times during the lifetime of the application.</p> - -<p>This is when your add-on should inject its UI, start up any tasks it may need running and so forth.</p> - -<pre>void startup( - data, - reason -); -</pre> - -<h6 id="Parameters">Parameters</h6> - -<dl> - <dt><code>data</code></dt> - <dd>A <a href="#Bootstrap_data">bootstrap data structure</a>.</dd> - <dt><code>reason</code></dt> - <dd>One of the <a href="#Reason_constants">reason constants</a>, indicating why the extension is being started up. This will be one of <code>APP_STARTUP</code>, <code>ADDON_ENABLE</code>, <code>ADDON_INSTALL</code>, <code>ADDON_UPGRADE</code>, or <code>ADDON_DOWNGRADE</code>.</dd> -</dl> - -<h3 id="shutdown">shutdown</h3> - -<p>Called when the extension needs to shut itself down, such as when the application is quitting or when the extension is about to be upgraded or disabled. Any user interface that has been injected must be removed, tasks shut down, and objects disposed of.</p> - -<pre>void shutdown( - data, - reason -); -</pre> - -<h6 id="Parameters_2">Parameters</h6> - -<dl> - <dt><code>data</code></dt> - <dd>A <a href="#Bootstrap_data">bootstrap data structure</a>.</dd> - <dt><code>reason</code></dt> - <dd>One of the <a href="#Reason_constants">reason constants</a>, indicating why the extension is being shut down. This will be one of <code>APP_SHUTDOWN</code>, <code>ADDON_DISABLE</code>, <code>ADDON_UNINSTALL</code>, <code>ADDON_UPGRADE</code>, or <code>ADDON_DOWNGRADE</code>.</dd> -</dl> - -<h3 id="install">install</h3> - -<p>Your bootstrap script must include an <code>install()</code> function, which the application calls before the first call to <code>startup()</code> after the extension is installed, upgraded, or downgraded.</p> - -<pre>void install( - data, - reason -); -</pre> - -<h6 id="Parameters_3">Parameters</h6> - -<dl> - <dt><code>data</code></dt> - <dd>A <a href="#Bootstrap_data">bootstrap data structure</a>.</dd> - <dt><code>reason</code></dt> - <dd>One of the <a href="#Reason_constants">reason constants</a>, indicating why the extension is being installed. This will be one of <code>ADDON_INSTALL</code>, <code>ADDON_UPGRADE</code>, or <code>ADDON_DOWNGRADE</code>.</dd> -</dl> - -<h3 id="uninstall">uninstall</h3> - -<p>This function is called after the last call to <code>shutdown()</code> before a particular version of an extension is uninstalled.</p> - -<div class="note"><strong>Note:</strong> If you open the add-on manager and then click "Remove" on an add-on, it will not call uninstall function right away. This is a soft uninstall because of the available "Undo" option. If the add-on manager is closed or another event takes place such that the "Undo" option becomes unavailable, then the hard uninstall takes place and the uninstall function is called.</div> - -<div class="note"><strong>Note:</strong> The uninstall function fires on downgrade and upgrade as well so you should make sure it is an uninstall by doing this:<br> -<code>function uninstall(aData, aReason) {</code><br> -<code>if (aReason == ADDON_UNINSTALL) {</code><br> -<code>console.log('really uninstalling');</code><br> -<code>} else {</code><br> -<code>console.log('not a permanent uninstall, likely an upgrade or downgrade');</code><br> -<code>}</code><br> -<code>}</code></div> - -<pre>void uninstall( - data, - reason -); -</pre> - -<h6 id="Parameters_4">Parameters</h6> - -<dl> - <dt><code>data</code></dt> - <dd>A <a href="#Bootstrap_data">bootstrap data structure</a>.</dd> - <dt><code>reason</code></dt> - <dd>One of the <a href="#Reason_constants">reason constants</a>, indicating why the extension is being uninstalled. This will be one of <code>ADDON_UNINSTALL</code>, <code>ADDON_UPGRADE</code>, or <code>ADDON_DOWNGRADE</code>.</dd> -</dl> - -<h2 id="Reason_constants">Reason constants</h2> - -<p>The bootstrap functions accept a <code>reason</code> parameter, which explains to the extension why it's being called. The reason constants are:</p> - -<table class="standard-table"> - <tbody> - <tr> - <td class="header">Constant</td> - <td class="header">Value</td> - <td class="header">Description</td> - </tr> - <tr> - <td><code>APP_STARTUP</code></td> - <td>1</td> - <td>The application is starting up.</td> - </tr> - <tr> - <td><code>APP_SHUTDOWN</code></td> - <td>2</td> - <td>The application is shutting down.</td> - </tr> - <tr> - <td><code>ADDON_ENABLE</code></td> - <td>3</td> - <td>The add-on is being enabled.</td> - </tr> - <tr> - <td><code>ADDON_DISABLE</code></td> - <td>4</td> - <td>The add-on is being disabled. (Also <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=620541">sent during uninstallation</a>)</td> - </tr> - <tr> - <td><code>ADDON_INSTALL</code></td> - <td>5</td> - <td>The add-on is being installed.</td> - </tr> - <tr> - <td><code>ADDON_UNINSTALL</code></td> - <td>6</td> - <td>The add-on is being uninstalled.</td> - </tr> - <tr> - <td><code>ADDON_UPGRADE</code></td> - <td>7</td> - <td>The add-on is being upgraded.</td> - </tr> - <tr> - <td><code>ADDON_DOWNGRADE</code></td> - <td>8</td> - <td>The add-on is being downgraded.</td> - </tr> - </tbody> -</table> - -<h2 id="Bootstrap_data">Bootstrap data</h2> - -<p>Each of the entry points is passed a simple data structure containing some useful information about the add-on being bootstrapped. More information about the add-on can be obtained by calling <code><a href="/en-US/docs/Addons/Add-on_Manager/AddonManager#getAddonByID()">AddonManager.getAddonByID()</a></code>. The data is a simple JavaScript object with the following properties:</p> - -<table class="standard-table"> - <tbody> - <tr> - <td class="header">Property</td> - <td class="header">Type</td> - <td class="header">Description</td> - </tr> - <tr> - <td><code>id</code></td> - <td><code>string</code></td> - <td>The ID of the add-on being bootstrapped.</td> - </tr> - <tr> - <td><code>version</code></td> - <td><code>string</code></td> - <td>The version of the add-on being bootstrapped.</td> - </tr> - <tr> - <td><code>installPath</code></td> - <td><code>nsIFile</code></td> - <td>The installation location of the add-on being bootstrapped. This may be a directory or an XPI file depending on whether the add-on is installed unpacked or not.</td> - </tr> - <tr> - <td><code>resourceURI</code></td> - <td><code>nsIURI</code></td> - <td>A URI pointing at the root of the add-ons files, this may be a <code>jar:</code> or <code>file:</code> URI depending on whether the add-on is installed unpacked or not. {{ gecko_minversion_inline("7.0") }}</td> - </tr> - <tr> - <td><code>oldVersion</code></td> - <td><code>string</code></td> - <td>The previously installed version, if the reason is <code>ADDON_UPGRADE</code> or <code>ADDON_DOWNGRADE</code>, and the method is <code>install</code> or <code>startup</code>. {{ gecko_minversion_inline("22.0") }}</td> - </tr> - <tr> - <td><code>newVersion</code></td> - <td><code>string</code></td> - <td>The version to be installed, if the reason is <code>ADDON_UPGRADE</code> or <code>ADDON_DOWNGRADE</code>, and the method is <code>shutdown</code> or <code>uninstall</code>. {{ gecko_minversion_inline("22.0") }}</td> - </tr> - </tbody> -</table> - -<div class="note"> -<p><strong>Note:</strong> An add-on may be upgraded/downgraded at application startup, in this case the <code>startup</code> method reason is <code>APP_STARTUP</code>, and the <code>oldVersion</code> property is not set. Also be aware that in some circumstances an add-on upgrade/downgrade may occur without the <code>uninstall</code> method being called.</p> -</div> - -<h2 id="Add-on_debugger">Add-on debugger</h2> - -<p>From Firefox 31 onwards, you can use the <a href="/en-US/Add-ons/Add-on_Debugger">Add-on Debugger</a> to debug bootstrapped add-ons.</p> - -<h2 id="Localization_(L10n)">Localization (L10n)</h2> - -<p>Localizing bootstrapped add-ons is very much the same since Firefox 7, as that is when chrome.manifest compatibility landed.</p> - -<h3 id="JS_and_JSM_Files_-_Using_Property_Files">JS and JSM Files - Using Property Files</h3> - -<p>To localize your .js and .jsm files you have to use <a href="/en-US/docs/XUL/Tutorial/Property_Files">property files</a>.</p> - -<p>The absolute minimum needed here is:</p> - -<ol> - <li>File: install.rdf</li> - <li>File: chrome.manifest</li> - <li>File: bootstrap.js</li> - <li>Folder: locale - <ol> - <li>Folder: VALID_LOCALE_HERE - <ol> - <li>File: ANYTHING.properties</li> - </ol> - </li> - </ol> - </li> -</ol> - -<p>In the locale folder you must have folders for each of the languages you want to provide; each folder must be named a valid locale (ex: en-US). Inside this folder must be a property file. Inside the chrome.manifest file these locale must be defined. For example if you had a subfolder of en-US in locale folder your chrome.manifest file will have to contain: <code>locale NAME_OF_YOUR_ADDON en-US locale/en-US/</code></p> - -<p>Here is an example: <a href="https://github.com/Noitidart/l10n/tree/properties">GitHub :: l10n-properties</a> - on startup of this add-on it will show a prompt saying USA or Great Britain, which ever it deems closest to your locale. You can test different locale by going to about:config and changing preference of general.useragent.locale to en-US and then to en-GB and disabling then re-enabling the add-on.</p> - -<h3 id="XUL_and_HTML_Files_-_Using_Entities_from_DTD_Files">XUL and HTML Files - Using Entities from DTD Files</h3> - -<p>Many times HTML pages are used, however they cannot be localized with DTD files. There are three changes you must make:</p> - -<ol> - <li>You have to change the HTML file's extension to be <code>.xhtml</code></li> - <li>The doctype must be defined point to a DTD file in your locale folder such as: <code><!DOCTYPE html SYSTEM <span class="pl-s1">"chrome://l10n/locale/mozilla.dtd"</span>></code></li> - <li>Must add xmlns attribute to html tag for example: <code><<span class="pl-ent">html</span> <span class="pl-e">xmlns</span>=<span class="pl-s1"><span class="pl-pds">"</span>http://www.w3.org/1999/xhtml<span class="pl-pds">"</span></span>></code></li> - <li>If you have multiple DTD files read on here: <a href="/en-US/docs/Using_multiple_DTDs">Using multiple DTDs</a></li> -</ol> - -<p>The bare minimum needed is:</p> - -<ol> - <li>File: install.rdf</li> - <li>File: chrome.manifest</li> - <li>File: bootstrap.js</li> - <li>Folder: locale - <ol> - <li>Folder: VALID_LOCALE_HERE - <ol> - <li>File: ANYTHING.dtd</li> - </ol> - </li> - </ol> - </li> -</ol> - -<p>The chrome.manifest file must include a definition for content for example: <code>content NAME_OF_YOUR_ADDON ./</code></p> - -<p>The chrome.manifest file must also include a line pointing to the locale, just like in the above property section, if you had a folder named en-US in locale, the chrome.manifest file should contain: <code>locale NAME_OF_YOUR_ADDON en-US locale/en-US/</code></p> - -<p>Here is an example add-on that opens an HTML page and a XUL page on install: <a href="https://github.com/Noitidart/l10n/tree/c456cc82a8a66b6d552cd8c2299cd2babc383af0">GitHub :: l10n-xhtml-xul</a>. Here is an example showing how to use a localized HTML page as an options page: <a href="https://github.com/Noitidart/l10n/tree/html-options">GitHub :: l10n-html-options</a>. You can go to about:config and change the value of the preference <code>general.useragent.locale </code>to <code>en-US</code> and then to <code>en-GB</code> and then reload the open pages to see the localization change.</p> - -<h2 id="Further_reading">Further reading</h2> - -<ul> - <li><a href="https://developer.mozilla.org/en-US/Add-ons/How_to_convert_an_overlay_extension_to_restartless">How to convert an overlay extension to restartless</a> a step by step guide. Some code samples are provided. The page is based on and expanded from Dave Garrett's step-by-step guide to <a class="external" href="https://flagfox.wordpress.com/2014/01/19/writing-restartless-addons/">convert an old overlay based extension into a restartless addon</a>.</li> - <li>Dave Townsend provides a basic code base to <a class="external" href="http://www.oxymoronical.com/blog/2011/01/Playing-with-windows-in-restartless-bootstrapped-extensions">load UI for each opened window</a> in a bootstrapped extension.</li> - <li>Mark Finkle provides some simple example code for <a class="external" href="http://starkravingfinkle.org/blog/2011/01/bootstrap-jones-adventures-in-restartless-add-ons/">restartless add-ons in mobile Firefox</a>, <a class="external" href="http://starkravingfinkle.org/blog/2011/01/restartless-add-ons-more-resources/">adding resources (like the options window)</a> to bootstrapped extensions and <a class="external" href="http://starkravingfinkle.org/blog/2011/01/restartless-add-ons-%e2%80%93-default-preferences/">using default preferences</a> without a <code>default/preferences/prefs.js</code> file.</li> - <li>Kris Maglione writes about <a class="external" href="http://maglione-k.users.sourceforge.net/bootstrapped.xhtml">the requirements for the cleanup procedures</a> in bootstrapped extensions.</li> - <li>Edward Lee shows off some <a class="external" href="http://ed.agadak.net/2011/01/restartless-add-on-example-code">helpful coding patterns and examples</a> you can use in your bootstrapped add-on.</li> - <li>Documentation for <a href="/en-US/docs/Extensions/Inline_Options">Inline Options</a> in Firefox 7 and later.</li> -</ul> |