diff options
Diffstat (limited to 'files/ru/mozilla/add-ons/webextensions')
44 files changed, 6048 insertions, 0 deletions
diff --git a/files/ru/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html b/files/ru/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html new file mode 100644 index 0000000000..3ca9e8bae6 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.html @@ -0,0 +1,148 @@ +--- +title: Анатомия Расширения +slug: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +tags: + - Расширение + - веб расширение +translation_of: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +--- +<p>{{AddonSidebar}}</p> + +<p><span class="notranslate">Расширение состоит из набора файлов, упакованных для распространения и установки.</span> <span class="notranslate"> В этой статье мы быстро рассмотрим файлы, которые могут присутствовать в расширении.</span></p> + +<h2 id="manifest.json">manifest.json</h2> + +<p><span class="notranslate">Это единственный файл, который должен присутствовать в каждом расширении.</span> <span class="notranslate"> Он содержит основные метаданные, такие как его имя, версию и требуемые разрешения.</span> <span class="notranslate"> Он также предоставляет указатели на другие файлы в расширении.</span></p> + +<p><span class="notranslate">Этот манифест также может содержать указатели на несколько других типов файлов:</span></p> + +<ul> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">Background pages</a>: <span class="notranslate">Реализует долгоиграющую логику.</span></li> + <li><span class="notranslate">Иконки для расширения и любых кнопок, которые оно может определить.</span></li> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Sidebars_popups_options_pages">Sidebars, popups, and options pages</a>: <span class="notranslate">HTML-документы, которые предоставляют содержимое для различных компонентов пользовательского интерфейса.</span></li> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">Content scripts</a>: <span class="notranslate">JavaScript сценарии вашего расширения, которые будут исполняться на веб-страницах.</span></li> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Web_accessible_resources">Web-accessible resources</a>: Делает контент вашего расширения видимым для веб-страниц и скриптов.</li> +</ul> + +<p><br> + <img alt="" src="https://mdn.mozillademos.org/files/13669/webextension-anatomy.png" style="display: block; height: 581px; margin-left: auto; margin-right: auto; width: 600px;"></p> + +<p><span class="notranslate">Для получения подробной информации см. справочную страницу </span> <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></p> + +<p><span class="notranslate">Помимо ссылок, указанных в манифесте, расширение может включать дополнительные</span> <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Extension_pages">веб-страницы расширения</a><span class="notranslate"> с поддерживающимися файлами.</span></p> + +<h2 id="Фоновые_скрипты">Фоновые скрипты</h2> + +<p><span class="notranslate">Расширения часто должны поддерживать долгосрочное состояние или выполнять долгосрочные операции независимо от срока жизни любой конкретной веб-страницы или окна браузера.</span> <span class="notranslate"> Для этого нужны фоновые сценарии.</span></p> + +<p><span class="notranslate">Фоновые сценарии загружаются сразу после загрузки расширения и остаются загруженными до тех пор, пока расширение не будет отключено или удалено.</span> <span class="notranslate"> Вы можете использовать любой</span> <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/API">API расширений</a> <span class="notranslate">в сценарии, если вы запросили необходимые </span><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">разрешения</a>.</p> + +<h3 id="Спецификации_фоновых_скриптов">Спецификации фоновых скриптов</h3> + +<p><span class="notranslate">Вы можете включить фоновый скрипт, используя <code>background</code> ключ в «manifest.json»:</span></p> + +<pre class="brush: json">// manifest.json + +"background": { + "scripts": ["background-script.js"] +}</pre> + +<p><span class="notranslate">Вы можете указать несколько фоновых сценариев: если вы это сделаете, они выполняются в том же контексте, как и несколько сценариев, загруженных на одной веб-странице.</span></p> + +<p>Вместо указания <span class="notranslate">несколько фоновых сценариев</span> выможете указать фоновую страницу, которая так же преимущества поддержки ES6 модулей:</p> + +<p style="margin-bottom: 0em;"><strong>manifest.json</strong></p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="comment token">// manifest.json</span> + +<span class="key token">"background":</span> <span class="punctuation token">{</span> + <span class="key token">"page":</span> <span class="string token">"background-page.html"</span> +<span class="punctuation token">}</span></code></pre> + +<p style="margin-bottom: 0em;"><strong>background-page.html</strong></p> + +<pre class="brush: html line-numbers language-html"><code class="language-html"><span class="doctype token"><!DOCTYPE html></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"><</span>html</span> <span class="attr-name token">lang</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>en<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>head</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>meta</span> <span class="attr-name token">charset</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>utf-8<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>script</span> <span class="attr-name token">type</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>module<span class="punctuation token">"</span></span> <span class="attr-name token">src</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>background-script.js<span class="punctuation token">"</span></span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"></</span>script</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>head</span><span class="punctuation token">></span></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>html</span><span class="punctuation token">></span></span></code></pre> + +<h3 id="Окружение_фоновых_скриптов">Окружение фоновых скриптов</h3> + +<h4 id="DOM_APIs">DOM APIs</h4> + +<p>Фоновые скрипты запускаются в пространстве специальной страницы, называемой фоновой. Это дает им доступ к глобальному <code><a href="/en-US/docs/Web/API/Window">window</a></code> объекту, а так же ко всем его DOM APIs.</p> + +<h4 id="WebExtension_APIs">WebExtension APIs</h4> + +<p>Фоновые скрипты могут использовать любые <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/API">API расширений</a>, если расширение имеет необходимые <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">разрешения</a>.</p> + +<h4 id="Многоцелевой_доступ">Многоцелевой доступ</h4> + +<p>Фоновые скрипты могут осуществлять XHR запросы к любому домену, если расширение имеет <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">host разрешения</a>.</p> + +<h4 id="Web-содержимое">Web-содержимое</h4> + +<p>Фоновые скрипты не получают прямого доступа к веб-страницам. Однако они могут загружать <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">скрипты содержимого</a> на веб-страницы и <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">взаимодействовать с этими скриптами с помощью API передачи сообщений</a>.</p> + +<h4 id="Политика_безопастности_содержимого">Политика безопастности содержимого</h4> + +<p>Фоновые скрипты ограничены в выполнении потенциально опасных операций, таких как <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>, через политику безопасности содержимого. Подробнее см. <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a>.</p> + +<h2 id="Боковые_панели_(sidebar)_всплывающие_окна_(popup)_страницы_настроек">Боковые панели (sidebar), всплывающие окна (popup), страницы настроек</h2> + +<p>Ваше расширение может иметь разнообразные компоненты интерфейса, определённые в HTML документах:</p> + +<ul> + <li><font color="#0b0116"><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">Боковая панель (sidebar</a></font>) - это панель, отображаемая в окне браузера с левой строны, рядом с веб-страницей</li> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">Всплывающие окна (popup</a>) - диалоговое окно, отображаемое по клику на <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">кнопке</a> на <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">панели инструментов</a> или в адресной строке</li> + <li><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">Страница настроек</a> открывается, когда пользователь обращается к настройкам расширения на странице менеджера расширений.</li> +</ul> + +<p>Для каждого из этих компонентов вы создаете HTML файл и помещаете специальную информацию в <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>. HTML файл может в себя включать CSS и JavaScript файлы, как и любая web-страница.</p> + +<p>Всё это типы <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">веб-страниц расширения</a>, и, в отличие от нормальных веб-страниц, ваш JavaScript может использовать все привелегии WebExtension APIs, как и ваши фоновые скрипты. Они даже могут получить доступ к переменным в фоновой странице, используя {{WebExtAPIRef("runtime.getBackgroundPage()")}}.</p> + +<h2 id="Веб-страницы_расширения">Веб-страницы расширения</h2> + +<p>Вы также можете включить HTML документы в ваше расширение, даже если они не будут включены в какой-либо существующий компонент пользовательского интерфейса. В отличие от документов, которые вы можете предоставить для боковых панелей, всплывающих окон или страниц настроек, эти документы не содержатся в manifest.json. Однако, они также имеют такой же доступ к WebExtension APIs, как и фоновые скрипты.</p> + +<p>Вы можете загрузить такую страницу, используя {{WebExtAPIRef("windows.create()")}} или {{WebExtAPIRef("tabs.create()")}}.</p> + +<p>Подробнее см. <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">Extension pages</a>.</p> + +<h2 id="Встраиваемые_скрипты">Встраиваемые скрипты</h2> + +<p>Используйте встраиваемые скрипты для доступа и изменения веб-страниц. Встраиваемые скрипты загружаются в веб-страницу и исполняются в контексте данной конкретной страницы.</p> + +<p>Встраиваемые скрипты предоставляются расширением; этим они отличаются от скриптов, загруженных самой веб-страницей, включая тех, что загружены с помощью {{HTMLElement("script")}} элемента веб-страницы.</p> + +<p>Встраиваемые скрипты имеют доступ и могут манипулировать DOM, как и обычные скрипты, загруженные веб-страницей.</p> + +<p>В отличие от обычных скриптов, они могут:</p> + +<ul> + <li>Осуществлять XHR запросы.</li> + <li>Использовать часть <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/API">API расширений</a>.</li> + <li>Обмениваться сообщениями с их фоновыми скриптами и таким образом иметь доступ ко всему WebExtension APIs.</li> +</ul> + +<p>Встраиваемые скрипты не могут напрямую взаимодействовать с обычными скриптами на странице, но они могут обмениваться сообщениями с помощью стандартного <code><a href="/en-US/docs/Web/API/Window/postMessage">window.postMessage()</a></code> API.</p> + +<p>Обычно, когда мы говорим о встраиваемых скриптах, мы отсылаемся к JavaScript, но вы так же можете внедрить CSS в веб-страницы, используя этот же механизм.</p> + +<p>Подробнее см. <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a>.</p> + +<h2 id="Веб-доступные_ресурсы"><span class="tlid-translation translation"><span title="">Веб-доступные ресурсы</span></span></h2> + +<p><span class="tlid-translation translation"><span title="">Веб-доступные ресурсы</span></span> - это ресурсы вроде изображений, HTML, CSS и JavaScript, которые вы включаете в расширение и хотите сделать доступными для встраиваемых скриптов и оригинальных скриптов веб-страницы. Такие ресурсы могут быть доступны скриптам через специальную URI схему.</p> + +<p>Например, если встраиваемый скрипт хочет добавить какие-либо изображения в веб-страницу, вы можете включить эти изображения в расширение и сделать их веб-доступными. Тогда встраиваемый скрипт может создать и добавить <code><a href="/en-US/docs/Web/HTML/Element/img">img</a></code> тэги, которые будут ссылаться на эти изображения через <code>src</code> атрибут.</p> + +<p>Подробнее см. <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a> секцию manifest.json.</p> + +<p> </p> + +<p> </p> diff --git a/files/ru/mozilla/add-ons/webextensions/api/cookies/cookie/index.html b/files/ru/mozilla/add-ons/webextensions/api/cookies/cookie/index.html new file mode 100644 index 0000000000..9191b3017a --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/cookies/cookie/index.html @@ -0,0 +1,107 @@ +--- +title: cookies.Cookie +slug: Mozilla/Add-ons/WebExtensions/API/cookies/Cookie +tags: + - API + - Cookies + - cookie + - Дополнения + - Расширения + - Справка + - данные +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies/Cookie +--- +<div>{{AddonSidebar()}}</div> + +<p>Тип <code>Cookie</code> из {{WebExtAPIRef("cookies")}} API представляет собой информацию о HTTP cookie.</p> + +<h2 id="Тип">Тип</h2> + +<p>Значения этого типа - объекты, которые могут содержать следующие свойства:</p> + +<dl class="reference-values"> + <dt><code>name</code></dt> + <dd><code>string</code> - содержит имя cookie.</dd> + <dt><code>value</code></dt> + <dd><code>string</code> - содержит значение cookie.</dd> + <dt><code>domain</code></dt> + <dd><code>string</code> - содержит домен, которому принадлежит cookie (например, "www.google.com", "example.com").</dd> + <dt><code>hostOnly</code></dt> + <dd><code>boolean</code> - <code>true</code> если cookie является host-only (то есть запрашивающий хост должен в точности совпадать с доменом cookie), в ином случае <code>false</code>.</dd> + <dt><code>path</code></dt> + <dd><code>string</code> - содержит path cookie.</dd> + <dt><code>secure</code></dt> + <dd><code>boolean</code> - <code>true</code>, если cookie помечен как secure (то есть его область действия ограничена безопасными каналами, обычно HTTPS), в ином случае <code>false</code>.</dd> + <dt><code>httpOnly</code></dt> + <dd><code>boolean</code> - <code>true</code> если cookie помечен как HttpOnly (то есть он недоступен для клиентских скриптов), иначе <code>false</code>.</dd> + <dt><code>session</code></dt> + <dd><code>boolean</code> - <code>true</code> если cookie является сессионным, <code>false</code> если cookie является постоянным с указанным временем жизни.</dd> + <dt><code>expirationDate</code>{{optional_inline}}</dt> + <dd><code>number</code> - содержит срок годности cookie, который представляется количеством секунд с начала UNIX-эры. Отсутствует для сессионных cookie.</dd> + <dt><code>storeId</code></dt> + <dd><code>string</code> - представляет собой ID хранилища, в котором хранится данный cookie, как указано в соответствии с {{WebExtAPIRef("cookies.getAllCookieStores()")}}.</dd> +</dl> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.cookies.Cookie")}}</p> + +<h2 id="Примеры">Примеры</h2> + +<p>В большинстве методов из cookies API объекты типа <code>Cookie</code> используются как входные параметры методов, либо же как возвращаемые значения. К примеру, вызов {{WebExtAPIRef("cookies.getAll()")}} возвращает массив объектов типа <code>Cookie</code>.</p> + +<p>В примере ниже мы запрашиваем все cookie, а затем выводим в лог некоторые из полей полученных <code>Cookie</code> объектов:</p> + +<pre class="brush: js">function logCookies(cookies) { + for (cookie of cookies) { + console.log(`Domain: ${cookie.domain}`); + console.log(`Name: ${cookie.name}`); + console.log(`Value: ${cookie.value}`); + console.log(`Persistent: ${!cookie.session}`); + } +} + +var gettingAll = browser.cookies.getAll({}); +gettingAll.then(logCookies);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Примечание</strong> + +<p>Это API основано на API Chromiumа <code><a href="https://developer.chrome.com/extensions/cookies#type-Cookie">chrome.cookies</a></code>. Эта документация основана на <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json"><code>cookies.json</code></a> из кода Chromium.</p> + +<p>Информация о совместимости Microsoft Edge предоставлена корпорацией Microsoft и включена здесь под лицензией Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/cookies/index.html b/files/ru/mozilla/add-ons/webextensions/api/cookies/index.html new file mode 100644 index 0000000000..a31f300edf --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/cookies/index.html @@ -0,0 +1,156 @@ +--- +title: cookies +slug: Mozilla/Add-ons/WebExtensions/API/cookies +tags: + - API + - Add-ons + - Cookies + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies +--- +<div>{{AddonSidebar}}</div> + +<p>Позволяет WebExtensions получить и установить куки ,а также сообщить об их изменении.</p> + +<p>Для использования этого API,вам нужно предоставить доступ <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> в вашем файле <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>,а также <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permissions</a> для тех сайтов чьи куки вам нужны для доступа.Смотрите <a href="/en-US/Add-ons/WebExtensions/API/cookies#Permissions">cookie Permissions</a>.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.Cookie")}}</dt> + <dd>Предоставляет информацию о HTTP cookie</dd> + <dt>{{WebExtAPIRef("cookies.CookieStore")}}</dt> + <dd>Represents a cookie store in the browser.</dd> + <dt>{{WebExtAPIRef("cookies.OnChangedCause")}}</dt> + <dd>Represents the reason a cookie changed.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.get()")}}</dt> + <dd>Запрашивает информацию об одном кукис.</dd> + <dt>{{WebExtAPIRef("cookies.getAll()")}}</dt> + <dd>Выдает все кукис которые подходят установленному фильтру.</dd> + <dt>{{WebExtAPIRef("cookies.set()")}}</dt> + <dd>Устанавливает кукис с заданной информацией;в том случае если подобный кукис был информация будет перезаписана.</dd> + <dt>{{WebExtAPIRef("cookies.remove()")}}</dt> + <dd>Удаляет кукис по имени.</dd> + <dt>{{WebExtAPIRef("cookies.getAllCookieStores()")}}</dt> + <dd>Список всех существующих куки</dd> +</dl> + +<h2 id="Event_handlers">Event handlers</h2> + +<dl> + <dt>{{WebExtAPIRef("cookies.onChanged")}}</dt> + <dd>Происходит когда кукис задается или меняется.</dd> +</dl> + +<h2 id="Permissions">Permissions</h2> + +<p>In order to use this API, an add-on must specify the "cookies" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> in its manifest, along with <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permissions</a> for any sites for which it wishes to access cookies. The add-on may read or write any cookies which could be read or written by a URL matching the host permissions. For example:</p> + +<dl> + <dt><code>http://*.example.com/</code></dt> + <dd> + <p>An add-on with this host permission may:</p> + + <ul> + <li>Read a non-secure cookie for <code>www.example.com</code>, with any path.</li> + <li>Write a secure or non-secure cookie for <code>www.example.com</code>, with any path.</li> + </ul> + + <p>It may <em>not</em>:</p> + + <ul> + <li>Read a secure cookie for <code>www.example.com</code>.</li> + </ul> + </dd> + <dt><code>http://www.example.com/</code></dt> + <dd> + <p>An add-on with this host permission may:</p> + + <ul> + <li>Read a non-secure cookie for <code>www.example.com</code>, with any path.</li> + <li>Read a non-secure cookie for <code>.example.com</code>, with any path.</li> + <li>Write a secure or non-secure cookie for <code>www.example.com</code> with any path.</li> + <li>Write a secure or non-secure cookie for <code>.example.com</code> with any path.</li> + </ul> + + <p>It may <em>not</em>:</p> + + <ul> + <li>Read or write a cookie for <code>foo.example.com</code>.</li> + <li>Read or write a cookie for <code>foo.www.example.com</code>.</li> + </ul> + </dd> + <dt><code>*://*.example.com/</code></dt> + <dd> + <p>An add-on with this host permission may:</p> + + <ul> + <li>Read or write a secure or non-secure cookie for <code>www.example.com</code> with any path.</li> + </ul> + </dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.cookies")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<h3 id="Edge_incompatibilities">Edge incompatibilities</h3> + +<p>Promises are not supported in Edge. Use callbacks instead.</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/cookies"><code>chrome.cookies</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json"><code>cookies.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/downloads/index.html b/files/ru/mozilla/add-ons/webextensions/api/downloads/index.html new file mode 100644 index 0000000000..735dab43d5 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/downloads/index.html @@ -0,0 +1,123 @@ +--- +title: downloads +slug: Mozilla/Add-ons/WebExtensions/API/downloads +translation_of: Mozilla/Add-ons/WebExtensions/API/downloads +--- +<div>{{AddonSidebar}}</div> + +<p><span class="tlid-translation translation" lang="ru"><span title="">Позволяет расширениям взаимодействовать с менеджером загрузки браузера.</span> <span title="">Этот модуль API можно использовать для загрузки, отмены, приостановки, возобновления загрузки файлов и отображения загруженных файлов в файловом менеджере.</span></span></p> + +<p>Для использования этого API вам необходимо указать "downloads" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> в вашем <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> файле.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.FilenameConflictAction")}}</dt> + <dd><span class="tlid-translation translation" lang="ru"><span title="">Определяет действия в случае, если имя загружаемого файла конфликтует с именем существующего файла</span></span>.</dd> + <dt>{{WebExtAPIRef("downloads.InterruptReason")}}</dt> + <dd>Defines a set of possible reasons why a download was interrupted.</dd> + <dt>{{WebExtAPIRef("downloads.DangerType")}}</dt> + <dd>Defines a set of common warnings of possible dangers associated with downloadable files.</dd> + <dt>{{WebExtAPIRef("downloads.State")}}</dt> + <dd>Defines different states that a current download can be in.</dd> + <dt>{{WebExtAPIRef("downloads.DownloadItem")}}</dt> + <dd>Represents a downloaded file.</dd> + <dt>{{WebExtAPIRef("downloads.StringDelta")}}</dt> + <dd>Represents the difference between two strings.</dd> + <dt>{{WebExtAPIRef("downloads.DoubleDelta")}}</dt> + <dd>Represents the difference between two doubles.</dd> + <dt>{{WebExtAPIRef("downloads.BooleanDelta")}}</dt> + <dd>Represents the difference between two booleans.</dd> + <dt>{{WebExtAPIRef("downloads.DownloadTime")}}</dt> + <dd>Represents the time a download took to complete.</dd> + <dt>{{WebExtAPIRef("downloads.DownloadQuery")}}</dt> + <dd>Defines a set of parameters that can be used to search the downloads manager for a specific set of downloads.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.download()")}}</dt> + <dd>Downloads a file, given its URL and other optional preferences.</dd> + <dt>{{WebExtAPIRef("downloads.search()")}}</dt> + <dd>Queries the {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} available in the browser's downloads manager, and returns those that match the specified search criteria.</dd> + <dt>{{WebExtAPIRef("downloads.pause()")}}</dt> + <dd>Pauses a download.</dd> + <dt>{{WebExtAPIRef("downloads.resume()")}}</dt> + <dd>Resumes a paused download.</dd> + <dt>{{WebExtAPIRef("downloads.cancel()")}}</dt> + <dd>Cancels a download.</dd> + <dt>{{WebExtAPIRef("downloads.getFileIcon()")}}</dt> + <dd>Retrieves an icon for the specified download.</dd> + <dt>{{WebExtAPIRef("downloads.open()")}}</dt> + <dd>Opens the downloaded file with its associated application.</dd> + <dt>{{WebExtAPIRef("downloads.show()")}}</dt> + <dd>Opens the platform's file manager application to show the downloaded file in its containing folder.</dd> + <dt>{{WebExtAPIRef("downloads.showDefaultFolder()")}}</dt> + <dd>Opens the platform's file manager application to show the default downloads folder.</dd> + <dt>{{WebExtAPIRef("downloads.erase()")}}</dt> + <dd>Erases matching {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} from the browser's download history, without deleting the downloaded files from disk.</dd> + <dt>{{WebExtAPIRef("downloads.removeFile()")}}</dt> + <dd>Removes a downloaded file from disk, but not from the browser's download history.</dd> + <dt>{{WebExtAPIRef("downloads.acceptDanger()")}}</dt> + <dd>Prompts the user to accept or cancel a dangerous download.</dd> + <dt>{{WebExtAPIRef("downloads.drag()")}}</dt> + <dd>Initiates dragging the downloaded file to another application.</dd> + <dt>{{WebExtAPIRef("downloads.setShelfEnabled()")}}</dt> + <dd>Enables or disables the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("downloads.onCreated")}}</dt> + <dd>Fires with the {{WebExtAPIRef("downloads.DownloadItem", "DownloadItem")}} object when a download begins.</dd> + <dt>{{WebExtAPIRef("downloads.onErased")}}</dt> + <dd>Fires with the <code>downloadId</code> when a download is erased from history.</dd> + <dt>{{WebExtAPIRef("downloads.onChanged")}}</dt> + <dd>When any of a {{WebExtAPIRef("downloads.DownloadItem", "DownloadItem")}}'s properties except <code>bytesReceived</code> changes, this event fires with the <code>downloadId</code> and an object containing the properties that changed.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.downloads")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/downloads"><code>chrome.downloads</code></a> API.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/index.html b/files/ru/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..6fcf34ce28 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,53 @@ +--- +title: JavaScript APIs +slug: Mozilla/Add-ons/WebExtensions/API +tags: + - Web-расширение + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>WebExtension JavaScript API может быть использован в <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#%D0%A4%D0%BE%D0%BD%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%BA%D1%80%D0%B8%D0%BF%D1%82%D1%8B">фоновых скриптах</a> расширения, а так же в любых других документах, поставляемых вместе с расширением, таких как документы во всплывающих окнах после нажатия<a href="/en-US/Add-ons/WebExtensions/User_interface_components#Browser_actions"> </a>кнопок активации расширения <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">browser action </a>на панели инструментов<a href="/en-US/Add-ons/WebExtensions/User_interface_components#Browser_actions"> </a>или <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">page action</a> в строке адреса, <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">боковой панели</a>, <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">страницах настроек</a> или <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_url_overrides">новых открытых вкладках</a>. Некоторые из этих API могут быть доступны на <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#%D0%92%D1%81%D1%82%D1%80%D0%B0%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC%D1%8B%D0%B5_%D1%81%D0%BA%D1%80%D0%B8%D0%BF%D1%82%D1%8B">встраиваемых в страницу скриптах</a> (см. <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">список в руководстве по встраиваемым скриптам</a>).</p> + +<p>Для использования отдельных более продвинутых API, необходимо <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">запросить разрешения</a> в manifest.json вашего дополнения.</p> + +<p>Вы можете получить доступ к API, используя пространство имён <code>browser</code>:</p> + +<pre class="brush: js">function logTabs(tabs) { + console.log(tabs); +} + +browser.tabs.query({currentWindow: true}, logTabs);</pre> +</div> + +<div> +<p>Многие API выполняются асинхронно, возвращая <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:</p> + +<pre class="brush: js">function logCookie(c) { + console.log(c); +} + +function logError(e) { + console.error(e); +} + +var setCookie = browser.cookies.set( + {url: "/"} +); +setCookie.then(logCookie, logError);</pre> +</div> + +<div>Обратите внимание, что это отличается от расширений Google Chrome, которые используют пространство имён <code>chrome</code> вместо <code>browser</code> и колбэки для асинхронных функций вместо промисов. + +<p>Для поддержки портирования, реализация Firefox WebExtensions API так же поддерживает пространство имён <code>chrome</code> и использование колбэков. Это позволяет в большинстве случаев не изменять код, изначально написанный для Chrome.</p> + +<p>Mozilla так же предоставляет полифилл, который позволяет коду, использующему <code>browser</code> и промисы, работать без изменений в Chrome: <a class="external external-icon" href="https://github.com/mozilla/webextension-polyfill">https://github.com/mozilla/webextension-polyfill</a>.</p> + +<p>Microsoft Edge использует пространство имен <code>browser</code>, но ещё не поддерживает, основанный на промисах асинхронный API. В Edge на данный момент асинхронные вызовы API должны использовать колбэки.</p> + +<p>Не все браузеры поддерживают все API: детали см. <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Browser support for JavaScript APIs</a>.</p> +</div> + +<div>{{SubpagesWithSummaries}}</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html b/files/ru/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html new file mode 100644 index 0000000000..f506e54335 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/runtime/getmanifest/index.html @@ -0,0 +1,88 @@ +--- +title: runtime.getManifest() +slug: Mozilla/Add-ons/WebExtensions/API/runtime/getManifest +tags: + - API + - Reference + - WebExtensions + - getManifest + - runtime + - Веб-расширения + - Дополнения + - Нестандартный + - Расширения + - Ссылка + - метод +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/getManifest +--- +<div>{{AddonSidebar()}}</div> + +<div>Получить весь файл <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> в виде объекта JavaScript, совместимого с JSON.</div> + +<div></div> + +<h2 id="Синтаксис">Синтаксис</h2> + +<pre class="syntaxbox brush:js">browser.runtime.getManifest() +</pre> + +<h3 id="Параметры">Параметры</h3> + +<p>Нет.</p> + +<h3 id="Возвращаемое_значение">Возвращаемое значение</h3> + +<p><code>object</code> - объект JSON, представляющий манифест.</p> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">Таблица совместимости на этой странице сгенерирована из структурированных данных. Если Вы хотите дополнить эти данные, пожалуйста, посетите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</p> + +<p>{{Compat("webextensions.api.runtime.getManifest")}}</p> + +<h2 id="Примеры">Примеры</h2> + +<p>Получить манифест и вывести его свойство "name":</p> + +<pre class="brush: js">var manifest = browser.runtime.getManifest(); +console.log(manifest.name);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Справка</strong> + +<p>Этот API основан на API Chromium <a href="https://developer.chrome.com/extensions/runtime#method-getManifest"><code>chrome.runtime</code></a>. Настоящая документация унаследована от <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> в коде Chromium.</p> + +<p>Данные о совместимости Microsoft Edge предоставлены Корпорацией Microsoft и включены сюда под лицензией Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/runtime/index.html b/files/ru/mozilla/add-ons/webextensions/api/runtime/index.html new file mode 100644 index 0000000000..62478e3457 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/runtime/index.html @@ -0,0 +1,168 @@ +--- +title: runtime +slug: Mozilla/Add-ons/WebExtensions/API/runtime +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Reference + - TopicStub + - WebExtensions + - runtime +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime +--- +<div>{{AddonSidebar}}</div> + +<p><span class="seoSummary">This module provides information about your extension and the environment it's running in.</span></p> + +<p>It also provides messaging APIs enabling you to:</p> + +<ul> + <li>Communicate between different parts of your extension. For advice on choosing between the messaging options, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#Choosing_between_one-off_messages_and_connection-based_messaging">Choosing between one-off messages and connection-based messaging</a>.</li> + <li>Communicate with other extensions.</li> + <li>Communicate with native applications.</li> +</ul> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.Port")}}</dt> + <dd>Represents one end of a connection between two specific contexts, which can be used to exchange messages.</dd> + <dt>{{WebExtAPIRef("runtime.MessageSender")}}</dt> + <dd> + <p>Contains information about the sender of a message or connection request.</p> + </dd> + <dt>{{WebExtAPIRef("runtime.PlatformOs")}}</dt> + <dd>Identifies the browser's operating system.</dd> + <dt>{{WebExtAPIRef("runtime.PlatformArch")}}</dt> + <dd>Identifies the browser's processor architecture.</dd> + <dt>{{WebExtAPIRef("runtime.PlatformInfo")}}</dt> + <dd>Contains information about the platform the browser is running on.</dd> + <dt>{{WebExtAPIRef("runtime.RequestUpdateCheckStatus")}}</dt> + <dd>Result of a call to {{WebExtAPIRef("runtime.requestUpdateCheck()")}}.</dd> + <dt>{{WebExtAPIRef("runtime.OnInstalledReason")}}</dt> + <dd>The reason that the {{WebExtAPIRef("runtime.onInstalled")}} event is being dispatched.</dd> + <dt>{{WebExtAPIRef("runtime.OnRestartRequiredReason")}}</dt> + <dd>The reason that the {{WebExtAPIRef("runtime.onRestartRequired")}} event is being dispatched.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.lastError")}}</dt> + <dd>This value is set when an asynchronous function has an error condition that it needs to report to its caller.</dd> + <dt>{{WebExtAPIRef("runtime.id")}}</dt> + <dd>The ID of the extension.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.getBackgroundPage()")}}</dt> + <dd>Retrieves the <a href="/en-US/docs/Web/API/Window">Window</a> object for the background page running inside the current extension.</dd> + <dt>{{WebExtAPIRef("runtime.openOptionsPage()")}}</dt> + <dd> + <p>Opens your extension's <a href="/en-US/Add-ons/WebExtensions/user_interface/Options_pages">options page</a>.</p> + </dd> + <dt>{{WebExtAPIRef("runtime.getManifest()")}}</dt> + <dd>Gets the complete <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> file, serialized as an object.</dd> + <dt>{{WebExtAPIRef("runtime.getURL()")}}</dt> + <dd>Given a relative path from the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> to a resource packaged with the extension, returns a fully-qualified URL.</dd> + <dt>{{WebExtAPIRef("runtime.setUninstallURL()")}}</dt> + <dd>Sets a URL to be visited when the extension is uninstalled.</dd> + <dt>{{WebExtAPIRef("runtime.reload()")}}</dt> + <dd>Reloads the extension.</dd> + <dt>{{WebExtAPIRef("runtime.requestUpdateCheck()")}}</dt> + <dd>Checks for updates to this extension.</dd> + <dt>{{WebExtAPIRef("runtime.connect()")}}</dt> + <dd>Establishes a connection from a content script to the main extension process, or from one extension to a different extension.</dd> + <dt>{{WebExtAPIRef("runtime.connectNative()")}}</dt> + <dd> + <div>Connects the extension to a native application on the user's computer.</div> + </dd> + <dt>{{WebExtAPIRef("runtime.sendMessage()")}}</dt> + <dd>Sends a single message to event listeners within your extension or a different extension. Similar to {{WebExtAPIRef('runtime.connect')}} but only sends a single message, with an optional response.</dd> + <dt>{{WebExtAPIRef("runtime.sendNativeMessage()")}}</dt> + <dd>Sends a single message from an extension to a native application.</dd> + <dt>{{WebExtAPIRef("runtime.getPlatformInfo()")}}</dt> + <dd>Returns information about the current platform.</dd> + <dt>{{WebExtAPIRef("runtime.getBrowserInfo()")}}</dt> + <dd>Returns information about the browser in which this extension is installed.</dd> + <dt>{{WebExtAPIRef("runtime.getPackageDirectoryEntry()")}}</dt> + <dd>Returns a DirectoryEntry for the package directory.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("runtime.onStartup")}}</dt> + <dd>Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started.</dd> + <dt>{{WebExtAPIRef("runtime.onInstalled")}}</dt> + <dd>Fired when the extension is first installed, when the extension is updated to a new version, and when the browser is updated to a new version.</dd> + <dt>{{WebExtAPIRef("runtime.onSuspend")}}</dt> + <dd>Sent to the event page just before the extension is unloaded. This gives the extension an opportunity to do some cleanup.</dd> + <dt>{{WebExtAPIRef("runtime.onSuspendCanceled")}}</dt> + <dd>Sent after {{WebExtAPIRef("runtime.onSuspend")}} to indicate that the extension won't be unloaded after all.</dd> + <dt>{{WebExtAPIRef("runtime.onUpdateAvailable")}}</dt> + <dd>Fired when an update is available, but isn't installed immediately because the extension is currently running.</dd> + <dt>{{WebExtAPIRef("runtime.onBrowserUpdateAvailable")}} {{deprecated_inline}}</dt> + <dd>Fired when an update for the browser is available, but isn't installed immediately because a browser restart is required.</dd> + <dt>{{WebExtAPIRef("runtime.onConnect")}}</dt> + <dd>Fired when a connection is made with either an extension process or a content script.</dd> + <dt>{{WebExtAPIRef("runtime.onConnectExternal")}}</dt> + <dd>Fired when a connection is made with another extension.</dd> + <dt>{{WebExtAPIRef("runtime.onMessage")}}</dt> + <dd>Fired when a message is sent from either an extension process or a content script.</dd> + <dt>{{WebExtAPIRef("runtime.onMessageExternal")}}</dt> + <dd>Fired when a message is sent from another extension. Cannot be used in a content script.</dd> + <dt>{{WebExtAPIRef("runtime.onRestartRequired")}}</dt> + <dd>Fired when the device needs to be restarted.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("webextensions.api.runtime")}}</p> + +<div>{{WebExtExamples("h2")}}</div> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/runtime"><code>chrome.runtime</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/tabs/get/index.html b/files/ru/mozilla/add-ons/webextensions/api/tabs/get/index.html new file mode 100644 index 0000000000..25a2126d65 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/tabs/get/index.html @@ -0,0 +1,74 @@ +--- +title: tabs.get() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/get +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/get +--- +<div>{{AddonSidebar()}}</div> + +<p>Получает сведения об указанной вкладке.</p> + +<h2 id="Синтаксис"><span class="short_text" id="result_box" lang="ru"><span>Синтаксис</span></span></h2> + +<pre class="brush: js">browser.tabs.get( + tabId, // integer + function(tab) {...} // function +) +</pre> + +<h3 id="Параметры">Параметры</h3> + +<dl> + <dt><code>tabId</code></dt> + <dd><code>integer</code>.</dd> + <dt><code>callback</code></dt> + <dd><code>function</code>. <span class="short_text" id="result_box" lang="ru"><span>Функция принимает</span> <span>следующие аргументы</span></span>: + <dl class="reference-values"> + <dt><code>tab</code></dt> + <dd>{{WebExtAPIRef('tabs.Tab')}}.</dd> + </dl> + </dd> +</dl> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p>{{Compat("webextensions.api.tabs.get")}}</p> + +<h2 id="Примеры">Примеры</h2> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Благодарность</strong> + +<p>Этот API основан на Chromium <a href="https://developer.chrome.com/extensions/tabs#method-get"><code>chrome.tabs</code></a> API. Это документация получена из <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> в коде Chromium.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/tabs/hide/index.html b/files/ru/mozilla/add-ons/webextensions/api/tabs/hide/index.html new file mode 100644 index 0000000000..a91d67f008 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/tabs/hide/index.html @@ -0,0 +1,79 @@ +--- +title: tabs.hide() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/hide +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/hide +--- +<div>{{AddonSidebar()}}</div> + +<p>Hides one or more tabs.</p> + +<p>Hidden tabs are no longer visible in the browser's tabstrip. Hidden tabs are not automatically <a href="/en-US/Add-ons/WebExtensions/API/tabs/discard">discarded</a>: the code running in them continues to run. You can explicitly discard tabs whenever you hide them: although this is not appropriate in all situations, it will help to reduce the resources used by the browser.</p> + +<p>This is an asynchronous function that returns a <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<p>Not all tabs are eligible for being hidden:</p> + +<ul> + <li>Tabs that are pinned cannot be hidden.</li> + <li>Tabs that are sharing the screen, microphone or camera cannot be hidden.</li> + <li>The current active tab cannot be hidden.</li> + <li>Tabs that are in the process of being closed cannot be hidden.</li> +</ul> + +<p>The first time an extension hides a tab, the browser will tell the user that the tab is being hidden, show them how they can access the hidden tab, and give them the option of disabling the extension instead.</p> + +<p>To use this API you must have the "tabHide" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox brush:js">var hiding = browser.tabs.hide( + tabIds // integer or integer array +) +</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code>tabIds</code></dt> + <dd><code><code>integer</code></code> or <code><code>array</code></code> of <code><code>integer</code></code>. The IDs of the tab or tabs to hide.</dd> + <dd>If any of these tabs are not eligible for being hidden, they will not be hidden, but the call will still succeed and eligible tabs will still be hidden. For example, if you pass <code>[1, 3]</code>, and <code>1</code> identifies the active tab, then only <code>3</code> will be hidden.</dd> + <dd>However, if any of the tab IDs are invalid, the call will fail and no tabs will be hidden.</dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with an array containing the IDs of the tabs that were hidden. If any error occurs, the promise will be rejected with an error message.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.tabs.hide")}}</p> + +<h2 id="Examples">Examples</h2> + +<p>Hide a single tab:</p> + +<pre class="brush: js">function onHidden() { + console.log(`Hidden`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.tabs.hide(2).then(onHidden, onError);</pre> + +<p>Hide multiple tabs:</p> + +<pre class="brush: js">function onHidden() { + console.log(`Hidden`); +} + +function onError(error) { + console.log(`Error: ${error}`); +} + +browser.tabs.hide([15, 14, 1]).then(onHidden, onError);</pre> + +<p>{{WebExtExamples}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/api/tabs/index.html b/files/ru/mozilla/add-ons/webextensions/api/tabs/index.html new file mode 100644 index 0000000000..696329aa4f --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/tabs/index.html @@ -0,0 +1,179 @@ +--- +title: tabs +slug: Mozilla/Add-ons/WebExtensions/API/tabs +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - tabs +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs +--- +<div>{{AddonSidebar}}</div> + +<p>Interact with the browser's tab system. You can use this API to get a list of opened tabs and to create, modify, and rearrange tabs in the browser.</p> + +<p>You can use most of this API without any special permission. However, to access <code>Tab.url</code>, <code>Tab.title</code>, and <code>Tab.faviconUrl</code>, you need to have the "tabs" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>. In Firefox this also means you need "tabs" to {{WebExtAPIRef("tabs.query", "query")}} by URL.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.MutedInfoReason")}}</dt> + <dd>An event that caused a muted state change.</dd> + <dt>{{WebExtAPIRef("tabs.MutedInfo")}}</dt> + <dd>Tab muted state and the reason for the last state change.</dd> + <dt>{{WebExtAPIRef("tabs.Tab")}}</dt> + <dd>Contains various properties of a single tab.</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettingsMode")}}</dt> + <dd>Defines how zoom changes are handled, i.e. which entity is responsible for the actual scaling of the page; defaults to <code>automatic</code>.</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettingsScope")}}</dt> + <dd>Defines whether zoom changes will persist for the page's origin, or only take effect in this tab; defaults to <code>per-origin</code> when in <code>automatic</code> mode, and <code>per-tab</code> otherwise.</dd> + <dt>{{WebExtAPIRef("tabs.ZoomSettings")}}</dt> + <dd>Defines how zoom changes in a tab are handled and at what scope.</dd> + <dt>{{WebExtAPIRef("tabs.TabStatus")}}</dt> + <dd>Whether the tabs have completed loading.</dd> + <dt>{{WebExtAPIRef("tabs.WindowType")}}</dt> + <dd>The type of window.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.TAB_ID_NONE")}}</dt> + <dd>An ID which represents the absence of a browser tab.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.get()")}}</dt> + <dd>Retrieves details about the specified tab.</dd> + <dt>{{WebExtAPIRef("tabs.getCurrent()")}}</dt> + <dd>Gets the tab that this script call is being made from. May be undefined if called from a non-tab context (for example: a background page or popup view).</dd> + <dt>{{WebExtAPIRef("tabs.connect()")}}</dt> + <dd>Connects to the content script(s) in the specified tab. The {{WebExtAPIRef('runtime.onConnect')}} event is fired in each content script running in the specified tab for the current extension. For more details, see <a href="/en-US/Add-ons/WebExtensions/Content_scripts">content script messaging</a>.</dd> + <dt>{{WebExtAPIRef("tabs.sendRequest()")}}</dt> + <dd>Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {{WebExtAPIRef('extension.onRequest')}} event is fired in each content script running in the specified tab for the current extension.</dd> + <dt>{{WebExtAPIRef("tabs.sendMessage()")}}</dt> + <dd>Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {{WebExtAPIRef('runtime.onMessage')}} event is fired in each content script running in the specified tab for the current extension.</dd> + <dt>{{WebExtAPIRef("tabs.getSelected()")}}</dt> + <dd>Gets the tab that is selected in the specified window.</dd> + <dt>{{WebExtAPIRef("tabs.getAllInWindow()")}}</dt> + <dd>Gets details about all tabs in the specified window.</dd> + <dt>{{WebExtAPIRef("tabs.create()")}}</dt> + <dd>Creates a new tab.</dd> + <dt>{{WebExtAPIRef("tabs.duplicate()")}}</dt> + <dd>Duplicates a tab.</dd> + <dt>{{WebExtAPIRef("tabs.query()")}}</dt> + <dd>Gets all tabs that have the specified properties, or all tabs if no properties are specified.</dd> + <dt>{{WebExtAPIRef("tabs.highlight()")}}</dt> + <dd>Highlights the given tabs.</dd> + <dt>{{WebExtAPIRef("tabs.update()")}}</dt> + <dd>Modifies the properties of a tab. Properties that are not specified in <var>updateProperties</var> are not modified.</dd> + <dt>{{WebExtAPIRef("tabs.move()")}}</dt> + <dd>Moves one or more tabs to a new position within its window, or to a new window. Note that tabs can only be moved to and from normal (<code>window.type === "normal"</code>) windows.</dd> + <dt>{{WebExtAPIRef("tabs.reload()")}}</dt> + <dd>Reload a tab.</dd> + <dt>{{WebExtAPIRef("tabs.remove()")}}</dt> + <dd>Closes one or more tabs.</dd> + <dt>{{WebExtAPIRef("tabs.detectLanguage()")}}</dt> + <dd>Detects the primary language of the content in a tab.</dd> + <dt>{{WebExtAPIRef("tabs.captureVisibleTab()")}}</dt> + <dd>Captures the visible area of the currently active tab in the specified window. You must have <code><all_urls></code> permission to use this method.</dd> + <dt>{{WebExtAPIRef("tabs.executeScript()")}}</dt> + <dd>Injects JavaScript code into a page. For details, see the programmatic injection section of the <a href="/en-US/Add-ons/WebExtensions/Content_scripts">content scripts</a> doc.</dd> + <dt>{{WebExtAPIRef("tabs.insertCSS()")}}</dt> + <dd>Injects CSS into a page. For details, see the programmatic injection section of the <a href="/en-US/Add-ons/WebExtensions/Content_scripts">content scripts</a> doc.</dd> + <dt>{{WebExtAPIRef("tabs.setZoom()")}}</dt> + <dd>Zooms a specified tab.</dd> + <dt>{{WebExtAPIRef("tabs.getZoom()")}}</dt> + <dd>Gets the current zoom factor of a specified tab.</dd> + <dt>{{WebExtAPIRef("tabs.setZoomSettings()")}}</dt> + <dd>Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab.</dd> + <dt>{{WebExtAPIRef("tabs.getZoomSettings()")}}</dt> + <dd>Gets the current zoom settings of a specified tab.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("tabs.onCreated")}}</dt> + <dd>Fired when a tab is created. Note that the tab's URL may not be set at the time this event fired, but you can listen to onUpdated events to be notified when a URL is set.</dd> + <dt>{{WebExtAPIRef("tabs.onUpdated")}}</dt> + <dd>Fired when a tab is updated.</dd> + <dt>{{WebExtAPIRef("tabs.onMoved")}}</dt> + <dd>Fired when a tab is moved within a window. Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response. This event is not fired when a tab is moved between windows. For that, see {{WebExtAPIRef('tabs.onDetached')}}.</dd> + <dt>{{WebExtAPIRef("tabs.onSelectionChanged")}}</dt> + <dd>Fires when the selected tab in a window changes.</dd> + <dt>{{WebExtAPIRef("tabs.onActiveChanged")}}</dt> + <dd>Fires when the selected tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to {{WebExtAPIRef('tabs.onUpdated')}} events to be notified when a URL is set.</dd> + <dt>{{WebExtAPIRef("tabs.onActivated")}}</dt> + <dd>Fires when the active tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to onUpdated events to be notified when a URL is set.</dd> + <dt>{{WebExtAPIRef("tabs.onHighlightChanged")}}</dt> + <dd>Fired when the highlighted or selected tabs in a window changes.</dd> + <dt>{{WebExtAPIRef("tabs.onHighlighted")}}</dt> + <dd>Fired when the highlighted or selected tabs in a window changes.</dd> + <dt>{{WebExtAPIRef("tabs.onDetached")}}</dt> + <dd>Fired when a tab is detached from a window, for example because it is being moved between windows.</dd> + <dt>{{WebExtAPIRef("tabs.onAttached")}}</dt> + <dd>Fired when a tab is attached to a window, for example because it was moved between windows.</dd> + <dt>{{WebExtAPIRef("tabs.onRemoved")}}</dt> + <dd>Fired when a tab is closed.</dd> + <dt>{{WebExtAPIRef("tabs.onReplaced")}}</dt> + <dd>Fired when a tab is replaced with another tab due to prerendering or instant.</dd> + <dt>{{WebExtAPIRef("tabs.onZoomChange")}}</dt> + <dd>Fired when a tab is zoomed.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.tabs")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/tabs"><code>chrome.tabs</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> in the Chromium code.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/webrequest/index.html b/files/ru/mozilla/add-ons/webextensions/api/webrequest/index.html new file mode 100644 index 0000000000..3f0da7eada --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/webrequest/index.html @@ -0,0 +1,188 @@ +--- +title: ВебЗапрос +slug: Mozilla/Add-ons/WebExtensions/API/webRequest +translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest +--- +<div>{{AddonSidebar}}</div> + +<p>Добавляет обработчики событий на различных стадиях HTTP запроса. Обработчик получет детальную информацию о запросе и способен изменить или отменить запрос.</p> + +<p>Каждое событие запущено на определённой стадии запроса. Типичный порядок событий такой:<img alt="" src="https://mdn.mozillademos.org/files/13376/webRequest-flow.png" style="display: block; height: 680px; margin-left: auto; margin-right: auto; width: 624px;"></p> + +<p>{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} Может быть запущен в любой момент во время запроса. Чреда событий может отличаться от приведенной выше: например, в Firefox, после <a href="/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security">HSTS</a> обновления, событие <code>onBeforeRedirect</code> будет запущено сразу же после <code>onBeforeRequest</code>.</p> + +<p>Все события, кроме <code>onErrorOccurred</code>, могут принимать три аргумента в <code>addListener()</code>:</p> + +<ul> + <li>сам обработчик</li> + <li>обьект {{WebExtAPIRef("webRequest.RequestFilter", "filter")}} , который позволяет получать оповещения о запросах, сделанных к определённым URL или определённым типам ресурсов.</li> + <li>необязательный обьект <code>extraInfoSpec</code> . Может быть использован для передачи дополнительных срецифических для события инструкций.</li> +</ul> + +<p>Функции - обработчику передается обьект <code>details</code> который содержит информацию о запросе. Она содержит ID запроса, который обеспечен для включения надстройки, которая позволяет соотносить события, ассоциируемые с одним запросом. Это уникально в пределах сессии и контекста надстройки. Информация остается одинаковой везде на протяжении запроса, даже при перенаправлениях и обменах аутентификации.</p> + +<p>Для использования webRequest API для определённого хоста, расширение должно иметь "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> и <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission </a>для этого хоста. Для использования возможности "блокирования" расширение должно также иметь "webRequestBlocking" API разрешение.</p> + +<p>Для перехвата ресурсов, загруженных страницей (таких как картинки, скрипты или таблицы стилей), расширение должно иметь разрешение хоста для ресурса также как и для главной страницы, запрашивающей ресурс. К примеру, если страница на "https://developer.mozilla.org" загружает картинку из "https://mdn.mozillademos.org", тогда расширение должно иметь разрешения обоих хостов чтобы перехватить запрос картинки.</p> + +<h2 id="Модифицирование_заголовков">Модифицирование заголовков</h2> + +<p>Используя некоторые из этих событий, вы можете модифицировать запрос. Конкретно, вы можете:</p> + +<ul> + <li>отменить запрос в: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li> + <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</li> + <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li> + </ul> + </li> + <li>перенаправить запрос в: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li> + <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li> + </ul> + </li> + <li>модифицировать заголовки запроса в: + <ul> + <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} + <ul> + </ul> + </li> + </ul> + </li> + <li>модифицировать заголовки ответа в: + <ul> + <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li> + </ul> + </li> + <li>предоставить учетные данные аутентификации в: + <ul> + <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li> + </ul> + </li> +</ul> + +<p>Чтобы сделать это, вам необходимо передать оцпию со значением "blocking" в аргументе <code>extraInfoSpec</code> к <code>addListener()</code>. Это делает обработчик синхронным. В обработчике, вы можете тогда возвратить обьект {{WebExtAPIRef("webRequest.BlockingResponse", "BlockingResponse")}} который индикует модификацию, какую вам нужно сделать: например, модифицированный заголовок запроса который вы хотите отправить.</p> + +<h2 id="Доступ_к_информации_о_безопасности">Доступ к информации о безопасности</h2> + +<p>В обработчике {{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}} вы имеете доступ к <a href="/en-US/docs/Glossary/TLS">TLS</a> свойствам запроса через вызов {{WebExtAPIRef("webRequest.getSecurityInfo()", "getSecurityInfo()")}}. Чтоды сделать это, вы должны также передать "blocking" в <code>extraInfoSpec</code> аргументе к <code>addListener()</code> события.</p> + +<p>Вы можете прочитать детали TLS хэндшейка, но не можете модифицировать их или перезаписать решения доверы браузера.</p> + +<h2 id="Modifying_responses">Modifying responses</h2> + +<p>Для того, чтобы модифицировать тело HTTP ответа на запрос, вызовите {{WebExtAPIRef("webRequest.filterResponseData")}}, и передайте ID запроса. Это возвратит обьект {{WebExtAPIRef("webRequest.StreamFilter")}} который вы сможете использовать чтобы исследовать и изменять данные когда они получены браузером.</p> + +<p>Чтобы сделать это, у вас дожно быть "webRequestBlocking" API разрешение, а также "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> и <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission </a>от соответствующего хоста.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.BlockingResponse")}}</dt> + <dd> + <p>An object of this type is returned by event listeners that have set <code>"blocking"</code> in their <code>extraInfoSpec</code> argument. By setting particular properties in <code>BlockingResponse</code>, the listener can modify network requests.</p> + </dd> + <dt>{{WebExtAPIRef("webRequest.CertificateInfo")}}</dt> + <dd>An object describing a single X.509 certificate.</dd> + <dt>{{WebExtAPIRef("webRequest.HttpHeaders")}}</dt> + <dd>An array of HTTP headers. Each header is represented as an object with two properties: <code>name</code> and either <code>value</code> or <code>binaryValue</code>.</dd> + <dt>{{WebExtAPIRef("webRequest.RequestFilter")}}</dt> + <dd>An object describing filters to apply to webRequest events.</dd> + <dt>{{WebExtAPIRef("webRequest.ResourceType")}}</dt> + <dd>Represents a particular kind of resource fetched in a web request.</dd> + <dt>{{WebExtAPIRef("webRequest.SecurityInfo")}}</dt> + <dd>An object describing the security properties of a particular web request.</dd> + <dt>{{WebExtAPIRef("webRequest.StreamFilter")}}</dt> + <dd>An object that can be used to monitor and modify HTTP responses while they are being received.</dd> + <dt>{{WebExtAPIRef("webRequest.UploadData")}}</dt> + <dd>Contains data uploaded in a URL request.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES")}}</dt> + <dd>The maximum number of times that <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/WebRequest/handlerBehaviorChanged" title="Suppose an add-on's job is to block web requests against a pattern, and the following scenario happens:"><code>handlerBehaviorChanged()</code></a></code> can be called in a 10 minute period.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.handlerBehaviorChanged()")}}</dt> + <dd>This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.</dd> + <dt>{{WebExtAPIRef("webRequest.filterResponseData()")}}</dt> + <dd>Returns a {{WebExtAPIRef("webRequest.StreamFilter")}} object for a given request.</dd> + <dt>{{WebExtAPIRef("webRequest.getSecurityInfo()")}}</dt> + <dd>Gets detailed information about the <a href="/en-US/docs/Glossary/TLS">TLS</a> connection associated with a given request.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("webRequest.onBeforeRequest")}}</dt> + <dd>Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.</dd> + <dt>{{WebExtAPIRef("webRequest.onBeforeSendHeaders")}}</dt> + <dd>Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.</dd> + <dt>{{WebExtAPIRef("webRequest.onSendHeaders")}}</dt> + <dd>Fired just before sending headers. If your add-on or some other add-on modified headers in <code>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</code>, you'll see the modified version here.</dd> + <dt>{{WebExtAPIRef("webRequest.onHeadersReceived")}}</dt> + <dd>Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.</dd> + <dt>{{WebExtAPIRef("webRequest.onAuthRequired")}}</dt> + <dd>Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.</dd> + <dt>{{WebExtAPIRef("webRequest.onResponseStarted")}}</dt> + <dd>Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.</dd> + <dt>{{WebExtAPIRef("webRequest.onBeforeRedirect")}}</dt> + <dd>Fired when a server-initiated redirect is about to occur.</dd> + <dt>{{WebExtAPIRef("webRequest.onCompleted")}}</dt> + <dd>Fired when a request is completed.</dd> + <dt>{{WebExtAPIRef("webRequest.onErrorOccurred")}}</dt> + <dd>Fired when an error occurs.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.webRequest")}}</p> + +<p><a href="/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities#webRequest_incompatibilities">Extra notes on Chrome incompatibilities</a>.</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/webRequest"><code>chrome.webRequest</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre class="notranslate">// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/windows/createtype/index.html b/files/ru/mozilla/add-ons/webextensions/api/windows/createtype/index.html new file mode 100644 index 0000000000..efc9821f8c --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/windows/createtype/index.html @@ -0,0 +1,65 @@ +--- +title: windows.CreateType +slug: Mozilla/Add-ons/WebExtensions/API/windows/CreateType +translation_of: Mozilla/Add-ons/WebExtensions/API/windows/CreateType +--- +<div>{{AddonSidebar()}}</div> + +<p>Определение типа окна браузера для создания.</p> + +<h2 id="Тип">Тип</h2> + +<p>Значение данного типа <code>strings</code>. Возможные значения:</p> + +<ul> + <li><code>"normal"</code></li> + <li><code>"popup"</code></li> + <li><code>"panel"</code></li> + <li><code>"detached_panel"</code></li> +</ul> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + + + +<p>{{Compat("webextensions.api.windows.CreateType")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/windows#type-CreateType"><code>chrome.windows</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code>windows.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/api/windows/index.html b/files/ru/mozilla/add-ons/webextensions/api/windows/index.html new file mode 100644 index 0000000000..889210561b --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/api/windows/index.html @@ -0,0 +1,106 @@ +--- +title: windows +slug: Mozilla/Add-ons/WebExtensions/API/windows +translation_of: Mozilla/Add-ons/WebExtensions/API/windows +--- +<div>{{AddonSidebar}}</div> + +<p><font><font>Взаимодействие с окнами браузера. </font><font>Вы можете использовать этот API, чтобы получить информацию об открытых окнах, а также открывать, изменять и закрывать окна. </font><font>Вы также можете слушать события открытия, закрытия окна, и активировать события.</font></font></p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.WindowType")}}</dt> + <dd>Тип окна браузера.</dd> + <dt>{{WebExtAPIRef("windows.WindowState")}}</dt> + <dd>Состояние окна браузера.</dd> + <dt>{{WebExtAPIRef("windows.Window")}}</dt> + <dd>Информация об окне браузера.</dd> + <dt>{{WebExtAPIRef("windows.CreateType")}}</dt> + <dd>Specifies the type of browser window to create.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.WINDOW_ID_NONE")}}</dt> + <dd>The <code>windowId</code> value that represents the absence of a browser window.</dd> + <dt>{{WebExtAPIRef("windows.WINDOW_ID_CURRENT")}}</dt> + <dd>The <code>windowId</code> value that represents the current window.</dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.get()")}}</dt> + <dd>Gets details about a window, given its ID.</dd> + <dt>{{WebExtAPIRef("windows.getCurrent()")}}</dt> + <dd>Gets the current window.</dd> + <dt>{{WebExtAPIRef("windows.getLastFocused()")}}</dt> + <dd>Gets the window that was most recently focused — typically the window 'on top'.</dd> + <dt>{{WebExtAPIRef("windows.getAll()")}}</dt> + <dd>Gets all windows.</dd> + <dt>{{WebExtAPIRef("windows.create()")}}</dt> + <dd> + <p>Creates a new window.</p> + </dd> + <dt>{{WebExtAPIRef("windows.update()")}}</dt> + <dd>Updates the properties of a window. Use this to move, resize, and (un)focus a window, etc.</dd> + <dt>{{WebExtAPIRef("windows.remove()")}}</dt> + <dd>Closes a window, and all its tabs.</dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("windows.onCreated")}}</dt> + <dd>Fired when a window is created.</dd> + <dt>{{WebExtAPIRef("windows.onRemoved")}}</dt> + <dd>Fired when a window is closed.</dd> + <dt>{{WebExtAPIRef("windows.onFocusChanged")}}</dt> + <dd>Fired when the currently focused window changes.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.windows")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/windows"><code>chrome.windows</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/windows.json"><code>windows.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html b/files/ru/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html new file mode 100644 index 0000000000..70e5f2e7e1 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html @@ -0,0 +1,331 @@ +--- +title: Chrome incompatibilities +slug: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +translation_of: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +--- +<div>{{AddonSidebar}}</div> + +<p>Веб расширения разработаны с поддержкой совместимости с расширениями Хрома и Оперы на сколько это возможно. Расширения, написанные для этих браузеров, должны работать в Firefox с минимальными изменениями.</p> + +<p>Все же, Firefox на данный момент имеет поддержку только для ограниченного набора функций и API, поддержуемых в Хроме и Опере. Мы работаем над добавлением большей поддержки, но много функций пока еще не поддерживаются и некоторые из них никогда не будут поддерживаться.</p> + +<p>Эта статья перечисляет все функции и API, которые полностью поддерживаются в <span style="line-height: 1.5;">Firefox Developer Edition (на данный момент Firefox 47). Там где функция поддерживается частично, мы указали на проблемные места.</span></p> + +<div class="note"> +<p>You should assume that features and APIs not listed here at all are not yet supported.</p> +</div> + +<h2 id="manifest.json_функция">manifest.json функция</h2> + +<h3 id="Полностью_поддерживаемые_ключи">Полностью поддерживаемые ключи:</h3> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/description">description</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/icons">icons</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/name">name</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/version">version</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code></li> +</ul> + +<h3 id="Частично_поддерживаемые_ключи">Частично поддерживаемые ключи:</h3> + +<h4 id="background">background</h4> + +<p>Firefox не поддерживает <code>"устойчивое"</code> свойство. Фоновые скрипты остаются загруженными всё время.</p> + +<h4 id="commands">commands</h4> + +<p>Firefox не поддерживает:</p> + +<ul> + <li>Media keys как сокращение</li> + <li><code>global</code></li> + <li>специальную комманду <code>_execute_browser_action</code></li> +</ul> + +<h4 id="content_scripts">content_scripts</h4> + +<p>Firefox не поддерживает:</p> + +<ul> + <li><code>match_about_blank</code></li> +</ul> + +<h4 id="content_security_policy">content_security_policy</h4> + +<p>Firefox не поддерживает:</p> + +<ul> + <li>"http://127.0.0.1" or "http://localhost" as script sources: they must be served over HTTPS.</li> +</ul> + +<h4 id="options_ui">options_ui</h4> + +<p>Firefox не поддерживает:</p> + +<ul> + <li><code>chrome_style</code></li> +</ul> + +<p>Using <code>options_ui</code> requires a valid value for the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications.gecko.id</a> property.</p> + +<h4 id="permissions">permissions</h4> + +<p>Firefox не поддерживает следующие разрешения:</p> + +<ul> + <li><code>background</code></li> + <li><code>clipboardRead</code></li> + <li><code>clipboardWrite</code></li> + <li><code>geolocation</code></li> + <li><code>unlimitedStorage</code></li> +</ul> + +<p>Obviously, it doesn't support permissions for APIs that are themselves not supported.</p> + +<h4 id="incognito">incognito</h4> + +<p>Firefox does not support the following incognito (private browsing) modes:</p> + +<ul> + <li><code>split</code></li> +</ul> + +<h2 id="JavaScript_APIs">JavaScript APIs</h2> + +<h3 id="Fully_supported_APIs">Fully supported APIs</h3> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/alarms">alarms</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a> + <ul> + <li>Relative URLs passed to <code>setPopup()</code> are resolved relative to the caller document, rather than to the extension root</li> + </ul> + </li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/commands">commands</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/contextMenus">contextMenus</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies">cookies</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a> + <ul> + <li>Relative URLs passed to <code>setPopup()</code> are resolved relative to the caller document, rather than to the extension root</li> + </ul> + </li> +</ul> + +<h3 id="Partially_supported_APIs">Partially supported APIs</h3> + +<h4 id="bookmarks">bookmarks</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>import()</code></li> + <li><code>export()</code></li> + <li><code>onCreated</code></li> + <li><code>onRemoved</code></li> + <li><code>onChanged</code></li> + <li><code>onMoved</code></li> + <li><code>onChildrenReordered</code></li> + <li><code>onImportBegan</code></li> + <li><code>onImportEnded</code></li> + <li><code>BookmarkTreeNodeUnmodifiable</code></li> + </ul> + </li> + <li>Firefox has special bookmarks like "Recently Bookmarked" or "Recently Visited"</li> +</ul> + +<h4 id="contextMenus">contextMenus</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li>the "browser_action" or "page_action" context types</li> + </ul> + </li> +</ul> + +<h4 id="downloads">downloads</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>drag()</code></li> + <li><code>acceptDanger()</code></li> + <li><code>setShelfEnabled()</code></li> + <li><code>onDeterminingFilename</code></li> + </ul> + </li> + <li>The <code>saveAs</code> option and values other than <code>"GET"</code> for the <code>method</code> option are not supported by <code>download()</code></li> +</ul> + +<h4 id="extension">extension</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>setUpdateUrlData()</code></li> + </ul> + </li> + <li>Additionally, the following deprecated properties will not be supported: + <ul> + <li><code>onRequest</code></li> + <li><code>onRequestExternal</code></li> + <li><code>getExtensionTabs()</code></li> + <li><code>sendRequest()</code></li> + </ul> + </li> +</ul> + +<h4 id="idle">idle</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>onStateChanged</code></li> + <li><code>setDetectionInterval()</code></li> + </ul> + </li> +</ul> + +<p>Additoinally, <code>queryState()</code> always returns <code>"active"</code> in Firefox, regardless of the current system idle state.</p> + +<h4 id="notifications">notifications</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>update()</code></li> + </ul> + </li> + <li>Firefox doesn't provide <code>byUser</code> data.</li> +</ul> + +<h4 id="runtime">runtime</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>getPackageDirectoryEntry()</code></li> + <li><code>reload()</code></li> + <li><code>requestUpdateCheck()</code></li> + <li><code>restart()</code></li> + <li><code>sendNativeMessage()</code></li> + <li><code>onBrowserUpdateAvailable</code></li> + <li><code>onConnectExternal</code></li> + <li><code>onInstalled</code></li> + <li><code>onMessageExternal</code></li> + <li><code>onRestartRequired</code></li> + <li><code>onStartup</code></li> + <li><code>onSuspend</code></li> + <li><code>onSuspendCanceled</code></li> + <li><code>onUpdateAvailable</code></li> + </ul> + </li> +</ul> + +<h4 id="storage">storage</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>managed</code> storage area</li> + <li><code>sync</code> storage area</li> + <li><code>getBytesInUse()</code>.</li> + </ul> + </li> +</ul> + +<h4 id="tabs">tabs</h4> + +<ul> + <li>Firefox treats <code>highlighted</code> and <code>active</code> as the same, since Firefox has no concept of selecting multiple tabs.</li> + <li>In Firefox, you need the <code>tabs</code> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a> if you want to include <code>url</code> in the <code>queryInfo</code> parameter to <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code>.</li> + <li> + <p>In Firefox, relative URLs passed into <code>tabs.executeScript()</code> or <code>tabs.insertCSS()</code> are resolved relative to the current page URL. In Chrome, these URLs are resolved relative to the add-on's base URL. To work cross-browser, you can specify the path as an absolute URL, starting at the add-on's root, like this:</p> + + <pre class="line-numbers language-html"><code class="language-html">/path/to/script.js</code></pre> + </li> + <li>In Firefox, you can't open (using {{WebExtAPIRef("tabs.create")}}), or navigate to (using {{WebExtAPIRef("tabs.update")}}) privileged URLs: + <ul> + <li>chrome: URLs</li> + <li>javascript: URLs</li> + <li>data: URLs</li> + <li>privileged about: URLs (for example, about:config, about:addons, about:debugging)</li> + </ul> + </li> + <li>Additionally, the following deprecated properties will not be supported: + <ul> + <li><code>sendRequest()</code></li> + <li><code>getSelected()</code></li> + <li><code>onActiveChanged</code></li> + <li><code>onHighlightChanged</code></li> + <li><code>onSelectionChanged</code></li> + </ul> + </li> +</ul> + +<h4 id="webNavigation">webNavigation</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>onCreatedNavigationTarget</code></li> + <li><code>onTabReplaced</code></li> + </ul> + </li> +</ul> + +<h4 id="webRequest">webRequest</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>onAuthRequired</code></li> + <li>filtering by <code>windowId</code> and <code>tabId</code></li> + <li>the <code>"requestBody"</code> instruction in <code>opt_extraInfoSpec</code></li> + </ul> + </li> + <li>In Firefox requests can be redirected only if their original URL uses the http or https scheme</li> +</ul> + +<h4 id="windows">windows</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li>the <code>focused </code>option in <code>create()</code></li> + </ul> + </li> + <li>In Firefox <code>onFocusChanged</code> will trigger multiple times for a given focus change.</li> +</ul> + +<h3 id="Planned_APIs">Planned APIs</h3> + +<p>We don't support the following APIs, but plan to, soon:</p> + +<ul> + <li><a class="external text" href="https://developer.chrome.com/extensions/devtools" rel="nofollow">Devtools (mostly panels)</a></li> + <li><a href="https://developer.chrome.com/extensions/debugger">debugger</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/omnibox" rel="nofollow">omnibox</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/permissions" rel="nofollow">permissions</a></li> +</ul> + +<p>This doesn't mean that these are the only additional APIs we will support, but that they are our current priorities.</p> + +<h3 id="Miscellaneous_incompatibilities">Miscellaneous incompatibilities</h3> + +<h4 id="Optional_arguments">Optional arguments</h4> + +<h4 id="URLs_in_CSS">URLs in CSS</h4> + +<p>Firefox resolves URLs in injected CSS files relative to the CSS file itself, rather than to the page it's injected into.</p> + +<h4 id="Additional_incompatibilities">Additional incompatibilities</h4> + +<p>Firefox does not support using <a href="/en-US/docs/Web/API/Window/alert">alert()</a> from background pages. Using <code>alert(message)</code> from a background page will cause the <a href="/en-US/docs/Tools/Browser_Console">Browser Console</a> to be opened and both a line stating "alert() is not supported in background windows; please use console.log instead." and the <code>message</code> will be output to the console.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/content_scripts/index.html b/files/ru/mozilla/add-ons/webextensions/content_scripts/index.html new file mode 100644 index 0000000000..2451aabce6 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/content_scripts/index.html @@ -0,0 +1,495 @@ +--- +title: Встраиваемый скрипт +slug: Mozilla/Add-ons/WebExtensions/Content_scripts +tags: + - Web-расширение + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/Content_scripts +--- +<div>{{AddonSidebar}}</div> + +<p>Встраиваемый скрипт - это часть расширения, которая выполняется в контексте отдельной веб-страницы (в отличии от фоновых скриптов, выполняющихся в контексте целого браузера).</p> + +<p><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#%D0%A4%D0%BE%D0%BD%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%BA%D1%80%D0%B8%D0%BF%D1%82%D1%8B">Фоновые скрипты</a> имеют доступ ко всем методам <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API">WebExtension JavaScript APIs</a>, но они не имеют доступа к контенту отдельных веб-страниц. Так что если вашему расширению необходимо взаимодействие с контентом веб-страницы, вам нужен встраиваемый скрипт.</p> + +<p>Точно так же, как скрипты загружаемые веб-страницами, встраиваемый скрипт может читать и изменять контент веб-страницы, используя DOM API.</p> + +<p>Встраиваемые скрипты имеют доступ только к <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#%D0%92%D0%B7%D0%B0%D0%B8%D0%BC%D0%BE%D0%B4%D0%B5%D0%B9%D1%81%D1%82%D0%B2%D0%B8%D0%B5_%D1%81_%D1%84%D0%BE%D0%BD%D0%BE%D0%B2%D1%8B%D0%BC%D0%B8_%D1%81%D0%BA%D1%80%D0%B8%D0%BF%D1%82%D0%B0%D0%BC%D0%B8">небольшому подмножеству методов WebExtension API</a>, но они могут <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#%D0%92%D0%B7%D0%B0%D0%B8%D0%BC%D0%BE%D0%B4%D0%B5%D0%B9%D1%81%D1%82%D0%B2%D0%B8%D0%B5_%D1%81_%D1%84%D0%BE%D0%BD%D0%BE%D0%B2%D1%8B%D0%BC%D0%B8_%D1%81%D0%BA%D1%80%D0%B8%D0%BF%D1%82%D0%B0%D0%BC%D0%B8">взаимодействовать с фоновыми скриптами</a>, используя систему передачи сообщений, таким образом опосредовано имея доступ ко всему WebExtension API.</p> + +<div class="note"> +<p>Обратите внимание, что встраивание скриптов блокируется на следующих доменах:</p> + +<ul style="display: grid;"> + <li>accounts-static.cdn.mozilla.net</li> + <li>accounts.firefox.com</li> + <li>addons.cdn.mozilla.net</li> + <li>addons.mozilla.org</li> + <li>api.accounts.firefox.com</li> + <li>content.cdn.mozilla.net</li> + <li>content.cdn.mozilla.net</li> + <li>discovery.addons.mozilla.org</li> + <li>input.mozilla.org</li> + <li>install.mozilla.org</li> + <li>oauth.accounts.firefox.com</li> + <li>profile.accounts.firefox.com</li> + <li>support.mozilla.org</li> + <li>sync.services.mozilla.com</li> + <li>testpilot.firefox.com</li> +</ul> + +<p>Если вы попытаетесь встроить скрипт на страницы, находящиеся на вышеперечисленных доменах, у вас ничего не выйдет, и веб-страница сделает запись о <a href="/ru/docs/Web/HTTP/CSP">CSP</a> ошибке.</p> + +<p>По причине того, что список запрещённых доменов включает в себя addons.mozilla.org, пользователи, которые попытаются испытать ваше расширение прямо на странице загрузки, могут посчитать, что расширение не работает! В связи с этим вы могли бы предоставить им соответствующее предупреждение или <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/onboarding_upboarding_offboarding_best_practices">onboarding page</a> чтобы немедленно переадресовать их с addons.mozilla.org.</p> +</div> + +<div class="note"> +<p>Значения, определённые в глобальной области видимости встраиваемого скрипта с помощью <code>var foo</code> или <code>window.foo = "bar"</code> могут исчезать по причине бага <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1408996">1408996</a>.</p> +</div> + +<h2 id="Загрузка_встраиваемого_скрипта">Загрузка встраиваемого скрипта</h2> + +<p>Загрузка встраиваемых скриптов на веб-страницу происходит следующими тремя способами:</p> + +<ol> + <li><strong>Автоматическая загрузка скрипта на страницах с определёнными URL, объявленными при установке:</strong> используя <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> ключ в manifest.json, вы можете запросить браузер загружать встраиваемый скрипт каждый раз, когда браузер загружает веб-страницу, чей URL <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">совпадает с объявленными шаблонами</a>.</li> + <li><strong>Автоматическая загрузка скрипта на страницах с определёнными URL, объявленными в момент работы расширения:</strong> используя {{WebExtAPIRef("contentScripts")}} API, вы можете запросить браузер загружать встраиваемый скрипт каждый раз, когда браузер загружает веб-страницу, чей URL <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">совпадает с объявленными шаблонами</a>. Это очень похоже на первый метод, но позволяет добавлять и удалять правила динамически во время работы расширения.</li> + <li><strong>Загрузка скрипта расширением в конкретную вкладку:</strong> используя <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/Tabs/executeScript">tabs.executeScript()</a></code> API, вы можете загружать встраиваемые скрипты в определённые вкладки когда захотите: например, в ответ на нажатие пользователя на <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">browser action</a>.</li> +</ol> + +<p>Существует только одна глобальная область видимости <em>для одного фрейма, для одного расширения</em>. Это означает, что значения из одного встраиваемого скрипта могут быть доступны для другого встраиваемого скрипта, не зависимо от того, как встраиваемый скрипт был загружен на страницу.</p> + +<p>Используя методы (1) и (2), вы можете загружать скрипты на страницы, чьи URL могут быть представлены, используя <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">шаблон совпадения</a>.</p> + +<p>Используя метод (3), вы к тому же можете загружать скрипты на страницы вашего расширения, но вы не можете загружать скрипты на привилегированные страницы браузеры (например "about:debugging" или "about:addons").</p> + +<h2 id="Условия_работы_встраиваемого_скрипта">Условия работы встраиваемого скрипта</h2> + +<h3 id="Доступ_к_DOM">Доступ к DOM</h3> + +<p>Встраиваемые скрипты имеют доступ и могут изменять DOM на веб-странице, так же как и обычные скрипты. Так же они могут видеть любые изменения сделанные с DOM страничными скриптами.</p> + +<p>При этом, встраиваемые скрипты имеют "чистое DOM представление". Это значит:</p> + +<ul> + <li>Встраиваемые скрипты не могут видеть JavaScript переменных, определённых страничными скриптами.</li> + <li>Если страничный скрипт переназначит встроенное свойство DOM, встраиваемый скрипт всё равно будет видеть его изначальное значение, а не переназначенное.</li> +</ul> + +<p>В Firefox это поведение называется <a href="/ru/docs/Mozilla/Tech/Xray_vision">Xray vision</a>.</p> + +<p>Например, рассмотрите эту веб-страницу:</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8" /> + </head> + + <body> + <script src="page-scripts/page-script.js"></script> + </body> +</html></pre> + +<p>Скрипт "page-script.js" делает следующее:</p> + +<pre class="brush: js">// page-script.js + +// добавляет новый элемент к DOM +var p = document.createElement("p"); +p.textContent = "Этот параграф был добавлен страничным скриптом."; +p.setAttribute("id", "page-script-para"); +document.body.appendChild(p); + +// определяет новое свойство на объекте window +window.foo = "Эта глобальная переменная была добавлена страничным скриптом"; + +// переопределяет встроенную window.confirm() функцию +window.confirm = function() { + alert("Страничный скрипт так же переопределил 'confirm'"); +}</pre> + +<p>Теперь расширение загружает встраиваемый скрипт на страницу:</p> + +<pre class="brush: js">// content-script.js + +// получает доступ и изменяет DOM +var pageScriptPara = document.getElementById("page-script-para"); +pageScriptPara.style.backgroundColor = "blue"; + +// не может видеть свойств определённых страничным скриптом +console.log(window.foo); // undefined + +// видит изначальное значение свойства, переопределённого страничным скриптом +window.confirm("Вы уверены?"); // вызывает оригинальный window.confirm()</pre> + +<p>Те же самые правила применяются и наоборот: страничный скрипт не может видеть JavaScript свойств, добавленных встраиваемым скриптом.</p> + +<p>Это означает, что встраиваемый скрипт может полагаться на то, что DOM свойства всегда будут вести себя предсказуемо, и не беспокоиться о том, что его переменные будут иметь конфликт с переменными из страничного скрипта.</p> + +<p>Одно из последствий такого поведения состоит в том, что встраиваемый скрипт не будет иметь доступ к JavaScript библиотекам, загруженным страничным скриптом. Например, если веб-страница загружает jQuery, встраиваемый скрипт не сможет увидеть эту библиотеку.</p> + +<p>Если встраиваемому скрипту необходимо использовать какую-либо JavaScript библиотеку, тогда эта библиотека должна быть загружена, тем же способом, как и встраиваемый скрипт вместе с ним:</p> + +<pre class="brush: json">"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["jquery.js", "content-script.js"] + } +]</pre> + +<div class="blockIndicator note"> +<p><strong>Примечание:</strong> Firefox предоставляет некоторое API, позволяющее встраиваемому скрипту иметь доступ к JavaScript объектам, созданным страничным скриптом, и предоставлять свои собственные JavaScript объекты страничному скрипту.</p> + +<p>Смотрите <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts">совместное использование объектов со страничным скриптом</a> для получения дополнительной информации.</p> +</div> + +<h3 id="Доступные_WebExtension_API">Доступные WebExtension API</h3> + +<p>В дополнение стандартному DOM API, встраиваемый скрипт может использовать следующие методы WebExtension APIs:</p> + +<p>Из <code><a href="/ru/Add-ons/WebExtensions/API/extension">extension</a></code>:</p> + +<ul> + <li><code><a href="/ru/Add-ons/WebExtensions/API/extension#getURL()">getURL()</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/extension#inIncognitoContext">inIncognitoContext</a></code></li> +</ul> + +<p>Из <code><a href="/ru/Add-ons/WebExtensions/API/runtime">runtime</a></code>:</p> + +<ul> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#connect()">connect()</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#getManifest()">getManifest()</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#getURL()">getURL()</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#onConnect">onConnect</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#onMessage">onMessage</a></code></li> + <li><code><a href="/ru/Add-ons/WebExtensions/API/runtime#sendMessage()">sendMessage()</a></code></li> +</ul> + +<p>Из <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a></code>:</p> + +<ul> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage">getMessage()</a></code></li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getAcceptLanguages">getAcceptLanguages()</a></code></li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getUILanguage">getUILanguage()</a></code></li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/i18n/detectLanguage">detectLanguage()</a></code></li> +</ul> + +<p>Из <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/menus">menus</a></code>:</p> + +<ul> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/menus/getTargetElement">getTargetElement</a></code></li> +</ul> + +<p>Ко всему из <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code>.</p> + +<h3 id="Работа_с_XHR_и_Fetch">Работа с XHR и Fetch</h3> + +<p>Встраиваемые скрипты могут делать запросы используя <code><a href="/ru/docs/Web/API/XMLHttpRequest">window.XMLHttpRequest</a></code> и <code><a href="/ru/docs/Web/API/Fetch_API">window.fetch()</a></code> API.</p> + +<div class="blockIndicator note"> +<p>В Firefox, запросы, совершаемые из встраиваемого скрипта (например, используя <a href="/ru/docs/Web/API/Fetch_API/Using_Fetch">fetch()</a>) происходят в контексте расширения, так что вам необходимо предоставлять полный URL для доступа к контенту страниц. В Chrome, эти запросы совершаются в контексте страницы, так что URL может быть относительным, например <code>/api</code> будет трансформирован в <code>https://[current page URL]/api</code>.</p> +</div> + +<p>Встраиваемый скрипт имеет точно такие же кросс-доменные привилегии, как и всё остальное расширение: так что если расширение запросило кросс-доменный доступ на какой-либо домен используя <code><a href="/ru/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> ключ в manifest.json, тогда его встраиваемый скрипт тоже будет иметь доступ к этому домену.</p> + +<p>Это достигается, предоставляя встраиваемому скрипту более привилегированные XHR and fetch объекты. Что имеет побочный эффект, связанный с отсутствием <code><a href="/ru/docs/Web/HTTP/Headers/Origin">Origin</a></code> и <code><a href="/ru/docs/Web/HTTP/Headers/Referer">Referer</a></code> заголовков, которые имел бы запрос, выполняемый из страничного скрипта. Зачастую это предпочитаемо, для того чтобы предотвратить раскрытие кросс-доменной натуры запроса. Начиная с версии 58 и дальше, расширения, которым необходимо выполнять запросы, которые должны выглядеть будто они отправлены встраиваемым скриптом, могут использовать <code>content.XMLHttpRequest</code> и <code>content.fetch()</code>. Кросс-браузерные расширения должны проверять присутствие этих методов.</p> + +<h2 id="Взаимодействие_с_фоновыми_скриптами">Взаимодействие с фоновыми скриптами</h2> + +<p>Хотя встраиваемые скрипты не могут напрямую использовать большинство методов из WebExtension APIs, они могут взаимодействовать с фоновыми скриптами расширения, используя систему сообщений, и таким образом могут опосредованно иметь доступ к тем же самым API, что и фоновые скрипты.</p> + +<p>Существует два способа общения между фоновым и встраиваемым скриптами: вы можете посылать одиночные сообщения, ожидая необязательного ответа, или вы можете установить долгосрочное соединение на двух сторонах и использовать это соединение для обмена сообщениями.</p> + +<h3 id="Одиночные_сообщения">Одиночные сообщения</h3> + +<p>Для отправки одиночного сообщения и ожидания необязательного ответа, вы можете использовать следующее API:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"></th> + <th scope="col">Во встраиваемом скрипте</th> + <th scope="col">В фоновом скрипте</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Отправка сообщения</th> + <td><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">browser.runtime.sendMessage()</a></code></td> + <td><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/Tabs/sendMessage">browser.tabs.sendMessage()</a></code></td> + </tr> + <tr> + <th scope="row">Получение сообщения</th> + <td><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + <td><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + </tr> + </tbody> +</table> + +<p>Например, представьте встраиваемый скрипт, который прослушивает веб-страницу на нажатие левой кнопки мыши.</p> + +<p>Если нажатие было произведено по ссылке, встраиваемый скрипт отправляет сообщение фоновому скрипту со значение URL в ссылке:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("click", notifyExtension); + +function notifyExtension(e) { + if (e.target.tagName != "A") { + return; + } + browser.runtime.sendMessage({"url": e.target.href}); +}</pre> + +<p>Фоновый скрипт ожидает эти сообщения и, при их получении, отображает уведомления, используя <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/notifications">notifications</a></code> API:</p> + +<pre class="brush: js">// background-script.js + +browser.runtime.onMessage.addListener(notify); + +function notify(message) { + browser.notifications.create({ + "type": "basic", + "iconUrl": browser.extension.getURL("link.png"), + "title": "Вы нажали на ссылку!", + "message": message.url + }); +} +</pre> + +<p>(Этот пример кода частично взят из <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> примера на GitHub.)</p> + +<h3 id="Обмен_сообщениями_через_постоянное_соединение">Обмен сообщениями через постоянное соединение</h3> + +<p>Отправка одиночных сообщений может стать довольно обременительной, если вы пересылаете много сообщений между встраиваемым и фоновым скриптами. Альтернативное решение в этой ситуации будет установить постоянное соединение между двумя скриптами, и использовать его для обмена сообщениями.</p> + +<p>Каждая из сторон имеет <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> объект, который они могут использовать для обмена сообщениями.</p> + +<p>Для создания постоянного соединения:</p> + +<ul> + <li>Одна из сторон должна ждать соединений, используя <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code></li> + <li>Другая сторона должна вызвать: + <ul> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/connect">tabs.connect()</a></code> (при соединении со встраиваемым скриптом); или</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/connect">runtime.connect()</a></code> (при соединении с фоновым скриптом).</li> + </ul> + </li> +</ul> + +<p>Результатом вызова этих методов будет возвращение <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> объекта.</p> + +<ul> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code> методу передаётся аргумент, являющийся собственным портом этого скрипта, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> объект.</li> +</ul> + +<p>Как только обе стороны имеют порт, они могут:</p> + +<ul> + <li>отправлять сообщения, используя <code>runtime.Port.postMessage()</code>, и</li> + <li>получать сообщения используя <code>runtime.Port.onMessage()</code></li> +</ul> + +<p>Например, сразу после загрузки, нижерасположенный встраиваемый скрипт:</p> + +<ul> + <li>Соединяется с фоновым скриптом</li> + <li>Сохраняет <code>Port</code> в переменную <code>myPort</code></li> + <li>Начинает ожидать и записывать сообщения приходящие на <code>myPort</code></li> + <li>Использует <code>myPort</code> для отправки сообщений на фоновый скрипт, когда пользователь нажимает левую кнопку мыши на документе</li> +</ul> + +<pre class="brush: js">// content-script.js + +var myPort = browser.runtime.connect({name:"port-from-cs"}); +myPort.postMessage({greeting: "Привет из встраиваемого скрипта"}); + +myPort.onMessage.addListener(function(m) { + console.log("Во встраиваемом скрипте, получено сообщение из фонового скрипта: "); + console.log(m.greeting); +}); + +document.body.addEventListener("click", function() { + myPort.postMessage({greeting: "Они кликнули по странице!"}); +});</pre> + +<p>Соответствующий фоновый скрипт:</p> + +<ul> + <li>Ожидает попытки соединения от встраиваемого скрипта</li> + <li>Когда он получает эту попытку соединения: + <ul> + <li>сохраняет свой порт в переменную <code>portFromCS</code></li> + <li>отправляет сообщение встраемому скрипту, используя этот порт</li> + <li>начинает ожидать сообщений, приходящих на порт, и записывать их</li> + </ul> + </li> + <li>Отправляет сообщения на встраиваемый скрипт, используя <code>portFromCS</code>, когда пользователь нажимает кнопку расширения в браузере</li> +</ul> + +<pre class="brush: js">// background-script.js + +var portFromCS; + +function connected(p) { + portFromCS = p; + portFromCS.postMessage({greeting: "Привет, встраиваемый скрипт!"}); + portFromCS.onMessage.addListener(function(m) { + console.log("В фоновом скрипте, получено сообщение от встраиваемого скрипта"); + console.log(m.greeting); + }); +} + +browser.runtime.onConnect.addListener(connected); + +browser.browserAction.onClicked.addListener(function() { + portFromCS.postMessage({greeting: "Они нажали кнопку!"}); +}); +</pre> + +<h4 id="Несколько_встраиваемых_скриптов">Несколько встраиваемых скриптов</h4> + +<p>Если вы имеете несколько встраиваемых скриптов, с которыми вы общающаетесь в одно и то же время, вы бы могли сохранять каждое соединение в массиве.</p> + +<ul> +</ul> + +<pre class="brush: js">// background-script.js + +var ports = [] + +function connected(p) { + ports[p.sender.tab.id] = p + //... +} + +browser.runtime.onConnect.addListener(connected) + +browser.browserAction.onClicked.addListener(function() { + ports.forEach(p => { + p.postMessage({greeting: "Они нажали на кнопку!"}) + }) +}); +</pre> + +<ul> +</ul> + +<h2 id="Взаимодействие_с_веб-страницей">Взаимодействие с веб-страницей</h2> + +<p>Хотя по умолчанию встраиваемые скрипты не имеют доступ к объектам, которые созданны страничными скриптами, они могут взаимодействовать со страничными скриптами, используя <code><a href="/ru/docs/Web/API/Window/postMessage">window.postMessage</a></code> и <code><a href="/ru/docs/Web/API/EventTarget/addEventListener">window.addEventListener</a></code> API.</p> + +<p>Например:</p> + +<pre class="brush: js">// page-script.js + +var messenger = document.getElementById("from-page-script"); + +messenger.addEventListener("click", messageContentScript); + +function messageContentScript() { + window.postMessage({ + direction: "from-page-script", + message: "Сообщение со страницы" + }, "*");</pre> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data && + event.data.direction == "from-page-script") { + alert("Встраиваемый скрипт получил сообщение: \"" + event.data.message + "\""); + } +});</pre> + +<p>Для просмотра законченного и полностью рабочего примера, <a href="https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html">посетите эту страницу на GitHub</a> и следуйте инструкциям.</p> + +<div class="warning"> +<p>Заметьте, при взаимодействии с непроверенными страницами этим способом, вам нужно быть очень осторожными . Расширения имеют возможность запускать привилегированный код, который может обладать серьёзными возможностями, и вредоносные веб-страницы легко могут обмануть ваше расширение, ради доступа к этим возможностям.</p> + +<p>Как простейший пример, представим встраиваемый скрипт, который получает сообщение от веб-страницы и делает что-то вроде этого:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data.direction && + event.data.direction == "from-page-script") { + eval(event.data.message); + } +});</pre> + +<p>Теперь страничный скрипт может запускать любой код со всеми привилегиями встраиваемого скрипта.</p> +</div> + +<h2 id="Использование_eval()_во_встраиваемых_скриптах">Использование <code>eval()</code> во встраиваемых скриптах</h2> + +<p>В Chrome, <code><a href="/ru/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> всегда выполняет код в контексте встраиваемого скрипта, а не в контексте веб-страницы.</p> + +<p>В Firefox:</p> + +<ul> + <li>Если вы вызываете <code>eval()</code>, код выполняется в контексте <strong>встраиваемого скрипта</strong>.</li> + <li>Если вы вызываете <code>window.eval()</code>, код выполняется в контексте <strong>страничного скрипта</strong>.</li> +</ul> + +<p>Например, рассмотрите этот встраиваемый скрипт:</p> + +<pre class="brush: js">// content-script.js + +window.eval('window.x = 1;'); +eval('window.y = 2'); + +console.log(`Во встраиваемом скрипте, window.x: ${window.x}`); +console.log(`Во встраиваемом скрипте, window.y: ${window.y}`); + +window.postMessage({ + message: "check" +}, "*");</pre> + +<p>Этот код создаёт переменные <code>x</code> and <code>y</code>, используя <code>window.eval()</code> и <code>eval()</code>, затем записывает их значения, и отправляет сообщение на веб-страницу.</p> + +<p>Получая сообщение, страничный скрипт записывает те же самые переменные:</p> + +<pre class="brush: js">window.addEventListener("message", function(event) { + if (event.source === window && event.data && event.data.message === "check") { + console.log(`In page script, window.x: ${window.x}`); + console.log(`In page script, window.y: ${window.y}`); + } +});</pre> + +<p>В Chrome, в консоли будут записаны следующие строки:</p> + +<pre>In content script, window.x: 1 +In content script, window.y: 2 +In page script, window.x: undefined +In page script, window.y: undefined</pre> + +<p>В Firefox, будут записаны следующие строки:</p> + +<pre>In content script, window.x: undefined +In content script, window.y: 2 +In page script, window.x: 1 +In page script, window.y: undefined</pre> + +<p>Те же правила применимы к <code><a href="/ru/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout()</a></code>, <code><a href="/ru/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></code>, и <code><a href="/ru/docs/Web/JavaScript/Reference/Global_Objects/Function">Function()</a></code>.</p> + +<div class="blockIndicator warning"> +<p>Будьте очень осторожны, запуская код в контексте страничного скрипта. Окружение страничного скрипта может контролироваться потенциально зловредным веб-страницей, которая может переопределить объекты, с которыми вы взаимодействуете, так что их поведение станет совершенно непредсказуемым:</p> + +<pre class="brush: js">// page.js переопределяет console.log + +var original = console.log; + +console.log = function() { + original(true); +} +</pre> + + +<pre class="brush: js">// content-script.js вызывает переопределённую версию + +window.eval('console.log(false)'); +</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/content_security_policy/index.html b/files/ru/mozilla/add-ons/webextensions/content_security_policy/index.html new file mode 100644 index 0000000000..2a620b3a39 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/content_security_policy/index.html @@ -0,0 +1,111 @@ +--- +title: Политика защиты содержимого +slug: Mozilla/Add-ons/WebExtensions/Content_Security_Policy +tags: + - Web-расширение + - Безопасность + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/Content_Security_Policy +--- +<div>{{AddonSidebar}}</div> + +<div class="summary"> +<p>Политика защиты содержимого (англ. Content Security Policy) автоматически применяется ко всем расширениям, разработанным с использованием WebExtension API. Она ограничивает источники, из которых расширение может загружать <a href="/ru/docs/Web/HTML/Element/script"><script></a> и <a href="/ru/docs/Web/HTML/Element/object"><object></a> ресурсы, и препятствует потенциально опасным практикам, например использованию <code><a href="/ru/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>.</p> + +<p>Статья в краткой форме объясняет значимость этой политики, каковы её изначальные правила, как они влияют на расширение, и как расширение может изменять эти правила.</p> +</div> + +<p><a href="/ru/docs/Web/HTTP/CSP">Политика защиты содержимого</a> - это механизм, помогающий веб-сайтам предотвращать выполнение умышленно вредного кода. Веб-сайт устанавливает политику защиты, используя HTTP заголовок, посылаемый с сервера. Главным образом эта политика участвует в устанавливании допустимых источников для загрузки различного вида контента, к примеру, скриптов или встроенных плагинов. Например, веб-сайт может использовать политику защиты для инструктирования браузера, чтобы тот выполнял скрипты, загруженные только с самого сайта, а не из каких-либо других источников. Политика защиты содержимого так же может запретить браузеру использовать потенциально опасные практики, например использование <a href="/ru/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a>.</p> + +<p>Так же как веб-сайты, расширения могут загружать контент из различных источников. Например, всплывающее окно расширения определяется HTML документом, и может подключать JavaScript и CSS файлы из различных источников, точно так же, как и нормальная веб-страница:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + </head> + + <body> + + <!-- Некоторый HTML контент --> + + <!-- + Подключение сторонней библиотеки. + Смотрите так же https://developer.mozilla.org/ru/docs/Web/Security/Subresource_Integrity. + --> + <script> + src="https://code.jquery.com/jquery-2.2.4.js" + integrity="sha256-iT6Q9iMJYuQiMWNd9lDyBUStIq/8PuOW33aOqmvFpqI=" + crossorigin="anonymous"> + </script> + + <!-- Include my popup's own script--> + <script src="popup.js"></script> + </body> + +</html></pre> + +<p>В сравнении с веб-сайтами, расширения имеют доступ к дополнительному привилегированному API, так что вероятность получения к нему доступа сторонним кодом - это очень большой риск. По этой причине:</p> + +<ul> + <li>довольно строгая политика по защите содержимого применяются изначально. Смотрите <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#%D0%98%D0%B7%D0%BD%D0%B0%D1%87%D0%B0%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5_%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BF%D0%BE_%D0%B7%D0%B0%D1%89%D0%B8%D1%82%D0%B5_%D1%81%D0%BE%D0%B4%D0%B5%D1%80%D0%B6%D0%B8%D0%BC%D0%BE%D0%B3%D0%BE">изначальные правила по защите содержимого</a>.</li> + <li>авторы расширений могут изменять изначальную политику, используя <code>content_security_policy</code> ключ в manifest.json, но даже в этом случае существуют ограничения на возможные разрешения. Для дополнительной информации смотрите <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code>.</li> +</ul> + +<h2 id="Изначальные_правила_по_защите_содержимого">Изначальные правила по защите содержимого</h2> + +<p>Следующие правила по защите содержимого являются изначальными:</p> + +<pre>"script-src 'self'; object-src 'self';"</pre> + +<p>Они применяются к любому расширению, которое самостоятельно не указывает свою политику защиты, используя <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code> ключ в manifest.json. Это имеет следующие последствия:</p> + +<ul> + <li> + <p><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#%D0%A0%D0%B0%D1%81%D0%BF%D0%BE%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D0%B5_script_%D0%B8_object_%D1%80%D0%B5%D1%81%D1%83%D1%80%D1%81%D0%BE%D0%B2">Вы можете загружать только локальные к расширению <script> и <object> ресурсы.</a></p> + </li> + <li> + <p><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#eval()_%D0%B8_%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D0%B8%D1%89%D0%B8">Расширению не разрешено выполнять код, представленный в виде JavaScript строк.</a></p> + </li> + <li> + <p><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#%D0%92%D1%81%D1%82%D1%80%D0%B0%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC%D1%8B%D0%B9_(inline)_JavaScript">Встраиваемый (inline) JavaScript код не будет выполняться.</a></p> + </li> +</ul> + +<h3 id="Расположение_script_и_object_ресурсов">Расположение script и object ресурсов</h3> + +<p>Используя изначальную политику защиты содержимого, вы можете загружать только локальные к расширению <a href="/ru/docs/Web/HTML/Element/script"><script></a> и <a href="/ru/docs/Web/HTML/Element/object"><object></a> ресурсы. Например, рассмотрите эту строку из документа расширения:</p> + +<pre class="brush: html"> <script src="https://code.jquery.com/jquery-2.2.4.js"></script></pre> + +<p>Она не будет загружать запрашиваемый ресурс, и вы не сможете найти ни один ожидаемый от ресурса объект. К этой ситуации существует два решения:</p> + +<ul> + <li> + <p>Скачать этот ресурс, упаковать его в ваше расширение и ссылаться к нему локально.</p> + </li> + <li> + <p>Использовать ключ <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code> в manifest.json, чтобы позволить загрузку контента из вышеупомянутого источника..</p> + </li> +</ul> + +<h3 id="eval()_и_товарищи">eval() и товарищи</h3> + +<p>Изначальная политика защиты содержимого не позволяет выполнять код из JavaScript строк. Это означает, что следующие примеры кода изначально запрещены:</p> + +<pre class="brush: js">eval("console.log('some output');");</pre> + +<pre class="brush: js">window.setTimeout("alert('Hello World!');", 500);</pre> + +<pre class="brush: js">var f = new Function("console.log('foo');");</pre> + +<h3 id="Встраиваемый_(inline)_JavaScript">Встраиваемый (inline) JavaScript</h3> + +<p>Изначальная политика защиты содержимого не позволяет выполнять JavaScript код, встраиваемый в HTML теги. Это запрещает как выполнение JavaScript кода вложенного прямо в <code><script></code> тег, так и выполнение вписанных в атрибут обработчиков событий, означая, что следующий код так же не будет работать:</p> + +<pre class="brush: html"><script>console.log("foo");</script></pre> + +<pre class="brush: html"><div onclick="console.log('click')">Click me!</div></pre> + +<p>Вместо того, чтобы использовать код <code><body onload="main()"></code> для запуска вашего скрипта после загрузки страницы, поставьте обработчики событий на <a href="/ru/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> или <a href="/ru/docs/Web/Events/load">load</a>.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/examples/index.html b/files/ru/mozilla/add-ons/webextensions/examples/index.html new file mode 100644 index 0000000000..e59d8c1f7f --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/examples/index.html @@ -0,0 +1,34 @@ +--- +title: Примеры расширений +slug: Mozilla/Add-ons/WebExtensions/Examples +tags: + - WebExtensions + - Веб-расширения + - Интерфейс +translation_of: Mozilla/Add-ons/WebExtensions/Examples +--- +<div>{{AddonSidebar}}</div> + +<p>В целях иллюстрации разработки расширений, мы поддерживаем репозиторий простых демонстрационных расширений по адресу <a href="https://github.com/mdn/webextensions-examples">https://github.com/mdn/webextensions-examples</a>. Данная статья описывает, как использовать эти примеры, и перечисляет их вместе с API Веб-расширений (WebExtensions API), которые они демонстрируют.</p> + +<p>Эти примеры работают в Firefox Nightly: большинство из них работает и в более ранних версиях Firefox, но, чтобы удостовериться, проверьте поле <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">strict_min_version</a> в файле manifest.json.</p> + +<div class="blockIndicator warning"> +<p>Некоторые примеры работают только на специальных доменах или страницах. Подробности о всех ограничениях представлены в файле readme каждого примера. По умолчанию ни один из примеров не работает в приватных окнах браузера, подробности смотрите в <a href="https://support.mozilla.org/en-US/kb/extensions-private-browsing#w_enabling-or-disabling-extensions-in-private-windows">Extensions in Private Browsing</a>.</p> +</div> + +<p>Если Вы хотите попробовать эти примеры, клонируйте репозиторий, а после этого совершите одно из следующих действий:</p> + +<ol> + <li>Загрузите расширение из папки с его исходниками, используя функцию браузера <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Load Temporary Add-on</a>. Расширение останется загруженным до следующего перезапуска Firefox.</li> + <li>Откройте папку с исходниками расширения в командной строке и используйте команду <code><a href="/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a></code>, чтобы запустить расширение. Расширение останется загруженным до следующего перезапуска Firefox.</li> + <li>В браузере Firefox используйте <strong>Файл</strong> > <strong>Открыть файл</strong> и найдите расширение в папке <code><a href="https://github.com/mdn/webextensions-examples/tree/master/build">build</a></code>. Папка <code>build</code> содержит построенные и подписанные версии всех примеров. В результате пример установится надолго, как обычное расширение.</li> +</ol> + +<div class="warning"> +<p><strong>Важно</strong>: Пожалуйста, не публикуйте эти примеры Веб-расширений на addons.mozilla.org (AMO) - Вам не нужно подписывать примеры Веб-расширений для того, чтобы их запустить. Просто следуйте шагам, описанным выше.</p> +</div> + +<p>Если Вы хотите сделать свой вклад в репозиторий, <a href="https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md">отправьте нам pull request!</a></p> + +<p>{{WebExtAllExamples}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/index.html b/files/ru/mozilla/add-ons/webextensions/index.html new file mode 100644 index 0000000000..c25919686b --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/index.html @@ -0,0 +1,109 @@ +--- +title: Расширения браузера +slug: Mozilla/Add-ons/WebExtensions +tags: + - Landing + - WebExtensions + - Дополнения + - Расширения +translation_of: Mozilla/Add-ons/WebExtensions +--- +<div style="">{{AddonSidebar}}</div> + +<p style="">WebExtensions - это кросс-браузерная система разработки дополнений (для браузеров). В значительной степени эта система совместима с <a class="external-icon external" href="https://developer.chrome.com/extensions" style="">API-расширений</a>, поддерживаемых Google Chrome и Opera. Расширения, написанные для этих браузеров, в большинстве случаев будут работать с Firefox или <a href="https://developer.microsoft.com/en-us/microsoft-edge/platform/documentation/extensions/" style="">Microsoft Edge</a> <a href="/ru/Add-ons/WebExtensions/Porting_from_Google_Chrome" style="">лишь с минимальными изменениями</a>. Эти API также полностью совместимы с <a href="/ru/Firefox/Multiprocess_Firefox" style="">мультипоточным Firefox</a>.</p> + +<p style="">Также мы намерены расширять API для поддержки нужд разработчиков дополнений, поэтому, если у вас есть идеи, то мы их с удовольствием выслушаем. Вы можете связаться с нами через <a href="https://mail.mozilla.org/listinfo/dev-addons" style="">dev-addons mailing list</a> или <a href="irc://irc.mozilla.org/webextensions" style="">#webextensions</a> на <a href="https://wiki.mozilla.org/IRC" style="">IRC</a>.</p> + +<div class="row topicpage-table" style=""> +<div class="section" style=""> +<h3 id="Приступая_к_работе" style="">Приступая к работе</h3> + +<ul style=""> + <li style=""><a href="/ru/Add-ons/WebExtensions/What_are_WebExtensions" style="">Что такое WebExtensions?</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Your_first_WebExtension" style="">Первое WebExtension</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Your_second_WebExtension" style="">Второе WebExtension</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Anatomy_of_a_WebExtension" style="">Анатомия WebExtension</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Examples" style="">Примеры WebExtensions</a></li> +</ul> + +<h3 id="How_to" style="">How to</h3> + +<ul style=""> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests" style="">Перехват HTTP-запросов</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page" style="">Изменить веб-страницу</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar" style="">Добавить кнопку на панель инструментов</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page" style="">Реализация страницы настроек</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard" style="">Работа с буфером обмена</a></li> + <li style="">Работа с вкладками браузера</li> + <li style="">Доступ и изменение закладок</li> + <li style="">Доступ и изменение куки (cookies)</li> +</ul> + +<h3 id="Интерфейс_пользователя" style="">Интерфейс пользователя</h3> + +<ul style=""> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface" style="">Введение</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action" style="">Кнопка на панели инструментов</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions" style="">Кнопка в адресной строке</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups" style="">Всплывающие окна</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items" style="">Контекстное меню</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars" style="">Боковые панели </a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_page" style="">Страница настройки дополнения</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages" style="">Дополнительные web-страницы</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications" style="">Уведомления</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox" style="">Угадывание адреса по мере ввода</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels" style="">Панели инструмента разработчика</a></li> +</ul> + +<h3 id="Основные_понятия" style="">Основные понятия</h3> + +<ul style=""> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API" style="">Обзор JavaScript API</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/User_interface_components" style="">Компоненты пользовательского интерфейса</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Content_scripts" style="">Скрипты Content scripts</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Match_patterns" style="">Match patterns (шаблоны совпадения)</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Internationalization" style="">Internationalization</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy" style="">Content Security Policy (политика безопасного контента)</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Native_messaging" style="">Native messaging (нативный обмен сообщениями)</a></li> +</ul> + +<h3 id="Адаптация" style="">Адаптация</h3> + +<ul style=""> + <li style=""><a href="/ru/Add-ons/WebExtensions/Porting_from_Google_Chrome" style="">Портирование расширения из Google Chrome</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Porting_a_legacy_Firefox_add-on" style="">Портирование старых дополнений Firefox</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions" style="">Embedded WebExtensions</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK" style="">Сравнение с Add-on SDK</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions" style="">Сравнение с XUL/XPCOM-расширениями</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities" style="">Несовместимость с Chrome</a></li> +</ul> + +<h3 id="Рабочий_процесс_workflow_Firefox" style="">Рабочий процесс (workflow) Firefox</h3> + +<ul style=""> + <li style=""><a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox" style="">Установка</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Debugging" style="">Отладка</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext" style="">Начало работы с инструментом Web-ext</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference" style="">Справочник команд Web-ext</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID" style="">WebExtensions и Add-on ID</a></li> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension" style="">Публикация вашего дополнения WebExtension</a></li> +</ul> +</div> + +<div class="section" style=""> +<h3 id="Справочники" style="">Справочники</h3> + +<ul style=""> + <li style=""><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API" style="">Обзор JavaScript API</a></li> + <li style=""><a href="/ru/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs" style="">Таблицы совместимости браузера для JavaScript APIs</a></li> +</ul> + +<h4 id="JavaScript_APIs" style="">JavaScript APIs</h4> + +<div class="twocolumns" style="">{{ ListSubpages ("/ru/Add-ons/WebExtensions/API") }}</div> + +<h4 id="Manifest_keys" style="">Manifest keys</h4> + +<div class="twocolumns" style="">{{ ListSubpages ("/ru/Add-ons/WebExtensions/manifest.json") }}</div> +</div> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/intercept_http_requests/index.html b/files/ru/mozilla/add-ons/webextensions/intercept_http_requests/index.html new file mode 100644 index 0000000000..91941e4595 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/intercept_http_requests/index.html @@ -0,0 +1,155 @@ +--- +title: Intercept HTTP requests +slug: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +translation_of: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +--- +<div>{{AddonSidebar}}</div> + +<ul> + <li> + <h2 id="Для_перехвата_HTTP_запросов_используйте_WebExtAPIRefwebRequest_API._Этот_API_позволит_вам_добавлять_слушателей_на_различных_этапах_создания_HTTP_запросов._В_слушателях_вы_можете">Для перехвата HTTP запросов используйте {{WebExtAPIRef("webRequest")}} API. Этот API позволит вам добавлять слушателей, на различных этапах создания HTTP запросов. В слушателях вы можете:</h2> + </li> + <li>получить доступ к заголовкам и телам запроса, к заголовкам ответа</li> + <li>отменять и перенаправлять запросы</li> + <li>изменять запрос и заголовки ответа</li> +</ul> + +<p>В этой статье мы рассмотрим три разных способа использования <code>webRequest</code> модуля:</p> + +<ul> + <li>Логирование URL сделанных запросов.</li> + <li>Перенаправление запросов.</li> + <li>Модификация заголовков запроса.</li> +</ul> + +<h2 id="Логирование_URL_запросов">Логирование URL запросов</h2> + +<p>Создайте новый каталог "requests". В нём создайте файл "manifest.json" со следующим содержимым:</p> + +<pre class="brush: json notranslate">{ + "description": "Demonstrating webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "<all_urls>" + ], + + "background": { + "scripts": ["background.js"] + } +}</pre> + +<p>Далее, создайте файл "background.js" со следующим содержимым:</p> + +<pre class="brush: js notranslate">function logURL(requestDetails) { + console.log("Loading: " + requestDetails.url); +} + +browser.webRequest.onBeforeRequest.addListener( + logURL, + {urls: ["<all_urls>"]} +); + +</pre> + +<p>Здесь мы используем {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} для вызова функции <code>logURL()</code> перед началом запроса. Функция <code>logURL()</code> берёт URL запроса из объекта event и выводит в консоль браузера. <a href="/en-US/Add-ons/WebExtensions/Match_patterns">Шаблон</a> <code>{urls: ["<all_urls>"]}</code> означает, что мы будем перехватывать HTTP запросы ко всем URL.</p> + +<p>Для проверки <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">проинсталлируйте WebExtension</a>, <a href="/en-US/docs/Tools/Browser_Console">откройте консоль браузера</a> и откройте какую-нибудь веб-страницу. В консоли вы должны увидеть URL для каждого ресурса, который запрашивает браузер:</p> + +<p>{{EmbedYouTube("X3rMgkRkB1Q")}}</p> + +<h2 id="Перенаправление_запросов">Перенаправление запросов</h2> + +<p>Теперь давайте использовать <code>webRequest</code> для перенаправления HTTP-запросов. Во-первых, замените manifest.json на это:</p> + +<pre class="brush: json notranslate">{ + + "description": "Demonstrating webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "webRequestBlocking", + "https://mdn.mozillademos.org" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p class="result">Единственное изменение здесь заключается в добавлении <code>"webRequestBlocking"</code> в <code>permission</code>. Мы должны запрашивать это дополнительное разрешение каждый раз, когда мы изменяем запрос.</p> + +<p>Затем замените «background.js» следующим образом:</p> + +<pre class="brush: js notranslate">var pattern = "https://mdn.mozillademos.org/*"; + +function redirect(requestDetails) { + console.log("Redirecting: " + requestDetails.url); + return { + redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif" + }; +} + +browser.webRequest.onBeforeRequest.addListener( + redirect, + {urls:[pattern], types:["image"]}, + ["blocking"] +);</pre> + +<p class="result">Опять же, мы используем {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} прослушиватель событий для запуска функции непосредственно перед каждым запросом. Эта функция заменит целевой URL на <code>redirectUrl</code> указанный в функции.</p> + +<p class="result">На этот раз мы не перехватываем каждый запрос: опция <code>{urls: [pattern], types: ["image"]}</code> указывает, что мы должны перехватывать запросы (1) для URL-адресов, находящихся в разделе «https://mdn.mozillademos.org / "(2) для ресурсов изображения. Подробнее см. {{WebExtAPIRef ("webRequest.RequestFilter")}}.</p> + +<p>Также обратите внимание, что мы передаем опцию <code>"blocking"</code>: нам нужно передать это, когда мы хотим изменить запрос. Это заставляет функцию прослушивателя блокировать сетевой запрос, поэтому браузер ждет, пока слушатель вернется, прежде чем продолжить. Дополнительную информацию о <code>"blocking"</code> смотрите в документации {{WebExtAPIRef ("webRequest.onBeforeRequest")}}.</p> + +<p>Чтобы проверить это, откройте страницу в MDN, которая содержит много изображений (например, https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor), перезагрузите WebExtension и перезагрузите страницу MDN :</p> + +<p>{{EmbedYouTube("ix5RrXGr0wA")}}</p> + +<h2 id="Modifying_request_headers">Modifying request headers</h2> + +<p>Finally we'll use <code>webRequest</code> to modify request headers. In this example we'll modify the "User-Agent" header so the browser identifies itself as Opera 12.16, but only when visiting pages under http://useragentstring.com/".</p> + +<p>The "manifest.json" can stay the same as in the previous example.</p> + +<p>Replace "background.js" with code like this:</p> + +<pre class="brush: js notranslate">var targetPage = "http://useragentstring.com/*"; + +var ua = "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16"; + +function rewriteUserAgentHeader(e) { + for (var header of e.requestHeaders) { + if (header.name.toLowerCase() == "user-agent") { + header.value = ua; + } + } + return {requestHeaders: e.requestHeaders}; +} + +browser.webRequest.onBeforeSendHeaders.addListener( + rewriteUserAgentHeader, + {urls: [targetPage]}, + ["blocking", "requestHeaders"] +);</pre> + +<p>Here we use the {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} event listener to run a function just before the request headers are sent.</p> + +<p>The listener function will be called only for requests to URLs matching the <code>targetPage</code> <a href="/en-US/Add-ons/WebExtensions/Match_patterns">pattern</a>. Also note that we've again passed <code>"blocking"</code> as an option. We've also passed <code>"requestHeaders"</code>, which means that the listener will be passed an array containing the request headers that we expect to send. See {{WebExtAPIRef("webRequest.onBeforeSendHeaders")}} for more information on these options.</p> + +<p>The listener function looks for the "User-Agent" header in the array of request headers, replaces its value with the value of the <code>ua</code> variable, and returns the modified array. This modified array will now be sent to the server.</p> + +<p>To test it out, open <a href="http://useragentstring.com/">useragentstring.com</a> and check that it identifies the browser as Firefox. Then reload the add-on, reload <a href="http://useragentstring.com/">useragentstring.com</a>, and check that Firefox is now identified as Opera:</p> + +<p>{{EmbedYouTube("SrSNS1-FIx0")}}</p> + +<h2 id="Learn_more">Learn more</h2> + +<p>To learn about all the things you can do with the <code>webRequest</code> API, see its <a href="/en-US/Add-ons/WebExtensions/API/WebRequest">reference documentation</a>.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/background/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/background/index.html new file mode 100644 index 0000000000..876f151d60 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/background/index.html @@ -0,0 +1,115 @@ +--- +title: ключ background +slug: Mozilla/Add-ons/WebExtensions/manifest.json/background +tags: + - WebExtensions + - Веб-расширения + - Дополнения + - Манифест + - Расширения +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/background +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Нет</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json no-line-numbers"> +"background": { + "scripts": ["background.js"] +}</pre> + </td> + </tr> + </tbody> +</table> + +<p><span id="result_box" lang="ru"><span>Используйте ключ <code>background</code> для включения одного или нескольких фоновых сценариев </span></span><span lang="ru"><span>и, возможно, фоновой страницы в ваше расширение.</span></span></p> + +<p><span id="result_box" lang="ru"><span>Фоновые сценарии </span></span>—<span lang="ru"><span> это место для размещения кода, который должен поддерживать долгосрочное состояние или выполнять долгосрочные операции, независимо от времени жизни каких-либо конкретных веб-страниц или окон браузера.</span></span></p> + +<p><span id="result_box" lang="ru"><span>Фоновые сценарии загружаются сразу при загрузке расширения и остаются загруженными до тех пор, пока расширение не будет отключено или удалено.</span> <span>Вы можете использовать любой API-интерфейс WebExtension в сценарии, если вы запросили необходимые</span></span> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">права (permissions)</a>.</p> + +<p><span id="result_box" lang="ru"><span>Дополнительную информацию см. В разделе «Справочные страницы»</span></span> в статье <a href="/ru/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_pages">Анатомия расширения</a>.</p> + +<p>Ключ <code>background</code> это объект, у которого есть два следующих необязательных свойства:</p> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>scripts</code></td> + <td> + <p>Массив строк, каждая из которых представляет собой путь к файлу JavaScript. Путь к этим файлам указывают относительно папки, в которой находится файл manifest.json. Это скрипты, которые будут выполняться в фоновой странице расширения.</p> + + <p>У этих скриптов общий глобальный контекст объекта <code>window</code>.</p> + + <p>Скрипты загружаются в том порядке, в котором они указаны в массиве.</p> + + <p>Если вы указали значения с помощью свойства <code>scripts</code>, будет создана пустая фоновая страница, в которой будут работать все эти скрипты.</p> + + <div class="note"> + <p><strong>Примечание:</strong> Если вы хотите добавить скрипт из удалённого расположения с помощью тега <code><script></code> (например, <code><script src = "https://code.jquery.com/jquery-1.7.1.min.js"></code>), может также понадобиться изменить значение ключа <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy">content_security_policy</a></code> в файле manifest.json вашего расширения.</p> + </div> + + <div class="note"> + <p><strong>Примечание:</strong> В Firefox до версии 50, когда открыт отладчик, скрипты не всегда загружаются в том порядке, в котором они расположены в массиве. Чтобы обойти этот баг, можно использовать свойство <code>page</code> (вместо <code>scripts</code>) и добавить фоновые скрипты с помощью тегов <code><script></code> в странице HTML. Этот баг починен в Firefox 50. Начиная с этой версии, скрипты всегда загружаются в том порядке, в котором они следуют в массиве.</p> + </div> + </td> + </tr> + <tr> + <td><code>page</code></td> + <td> + <p>Если вам нужно какое-нибудь содержимое HTML-страницы, можно определить свою фоновую страницу с помощью свойства <code>page</code>. Это строка, которая представляет собой путь к файлу документа HTML, заданный относительно расположения файла manifest.json. Этот файл HTML должен находиться внутри вашего расширения.</p> + + <p>Если используется это свойство, то уже нельзя добавлять скрипты с помощью свойства <code>scripts</code>. Вместо этого нужно добавлять скрипты в страницу — точно таким же образом, как в обычную веб-страницу.</p> + </td> + </tr> + </tbody> +</table> + +<p>Ключ <code>background</code> также может содержать следующее необязательное свойство:</p> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>persistent</code></td> + <td> + <p>Двоичное значение (<code>Boolean</code>).</p> + + <ul> + <li><code>true</code> определяет, что фоновая страница должна храниться в памяти с момента, когда загрузилось расширение или запустился браузер и до того, как расширение будет удалено или выключено, или браузер будет закрыт (то есть фоновая страница постоянна).</li> + <li><code>false</code> определяет, что фоновая страница может быть выгружена из памяти во время бездействия и создана заново, когда будет нужна. Такие фоновые страницы часто называются «Страницами Событий» (Event Pages) — потому, что они загружаются в память только для того, чтобы обрабатывать события, для которых в фоновых скриптах назначены функции-обработчики. Зарегистрированные события остаются когда фоновая страница выгружена из памяти, но остальные значения сбрасываются. Если нужно хранить постоянные данные при использовании страницы событий, используйте <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage API</a>.</li> + </ul> + </td> + </tr> + </tbody> +</table> + +<h2 id="Примеры">Примеры</h2> + +<pre class="brush: json no-line-numbers"> "background": { + "scripts": ["jquery.js", "my-background.js"] + }</pre> + +<p>Загрузит два фоновых скрипта.</p> + +<pre class="brush: json"> "background": { + "page": "my-background.html" + }</pre> + +<p>Загрузит файл фоновой страницы.</p> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">Таблица совместимости сгенерирована из структурированных данных. Если вы хотите дополнить эту информацию, пожалуйста, посетите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</p> + +<p>{{Compat("webextensions.manifest.background", 10)}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.html new file mode 100644 index 0000000000..0efe1fe0d5 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.html @@ -0,0 +1,117 @@ +--- +title: content_security_policy +slug: Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy +tags: + - Web-расширение + - Безопасность + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>Строка</code></td> + </tr> + <tr> + <th scope="row">Обязателен</th> + <td>Нет</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json no-line-numbers"> +"content_security_policy": "default-src 'self'"</pre> + </td> + </tr> + </tbody> +</table> + +<p>Политика защиты содержимого применяется к расширениям автоматически. Изначальная политика защиты содержимого ограничивает источники, из которых расширение может загружать <a href="/ru/docs/Web/HTML/Element/script"><script></a> и <a href="/ru/docs/Web/HTML/Element/object"><object></a> ресурсы, а так же препятствует потенциально опасным практикам, например использованию <code><a href="/ru/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>. Смотрите <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#Изначальные_правила_по_защите_содержимого">изначальные правила защиты содержимого</a>, чтобы узнать о конкретных последствиях применения изначальных правил.</p> + +<p>Ключ <code>"content_security_policy"</code> в manifest.json используется для ослабления или ужесточения политики защиты содержимого. Значения для этого ключа устанавливаются в точно таком же виде, как и для Content-Security-Policy HTTP заголовка. Смотрите <a href="/ru/docs/Web/HTTP/CSP">Использование политики содержимого</a> для получения общего представления о синтаксисе для написания правил политики.</p> + +<p>Примеры использования ключа могут включать в себя:</p> + +<ul> + <li>Разрешение на загрузку не запакованных в расширение скриптов и объектов, предоставляя их URL в {{CSP("script-src")}} и {{CSP("object-src")}} директивах.</li> + <li>Разрешение на выполнение встраиваемых скриптов, <a href="/ru/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#Unsafe_inline_script">предоставляя hash скрипта в <code>"script-src"</code> директиве</a>.</li> + <li>Разрешение на использование <code>eval()</code> и похожих функций, добавляя <code>'unsafe-eval'</code> в {{CSP("script-src")}} директиву.</li> + <li>Ограничение допускаемых источников загрузки для других видов контента, например картинок или файлов стилей, используя соответствующие <a href="/ru/docs/Web/HTTP/Headers/Content-Security-Policy">директивы</a>.</li> +</ul> + +<p>При написании правил по защите содержимого, вы имеете некоторые ограничения:</p> + +<ul> + <li>Правило должно включать в себя {{CSP("script-src")}} и {{CSP("object-src")}} директивы, и {{CSP("script-src")}} директива должна включать ключевое слово <code>'self'</code>.</li> + <li>Удалённые источники должны иметь <code>https:</code> схему.</li> + <li>Удалённые источники не должны определяться через универсальный символ <code>*</code> со следующим за ним <a href="https://publicsuffix.org/list/">доменным публичным суффиксом</a> (например "*.co.uk" и "*.blogspot.com" являются не разрешёнными значениями, но "*.foo.blogspot.com" разрешёно).</li> + <li>У всех источников должен быть определён хост.</li> + <li>Единственные позволенные схемы источников: <code>blob:</code>, <code>filesystem:</code>, <code>moz-extension:</code> и <code>https:</code>.</li> + <li>Единственные позволенные <a href="/ru/docs/Web/HTTP/Headers/Content-Security-Policy/default-src#Sources">ключевые слова</a>: <code>'none'</code>, <code>'self'</code> и <code>'unsafe-eval'</code>.</li> +</ul> + +<h2 id="Примеры">Примеры</h2> + +<h3 id="Работающие_примеры">Работающие примеры</h3> + +<p>Разрешает загрузку скриптов из "https://example.com": <sup>(<em>смотрите примечание</em> <a href="#exampleNote_1">1</a>)</sup></p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' https://example.com; object-src 'self'"</pre> + +<p>Разрешает загрузку скриптов из любого субдомена "jquery.com":</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' https://*.jquery.com; object-src 'self'"</pre> + +<p>Разрешает использование <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#eval()_и_товарищи"><code>eval()</code> и его товарищей</a>:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self';"</pre> + +<p>Разрешает встроить скрипт: <code>"<script>alert('Hello, world.');</script>"</code>:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' 'sha256-qznLcsROx4GACP2dm0UCKCzCG+HiZ1guq6ZZDob/Tng='; object-src 'self'"</pre> + +<p>Оставляет изначальные правила, но так же требует, чтобы могли загружаться только изображения, запакованные вместе с расширением:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self'; object-src 'self'; img-src 'self'"</pre> + +<p>Разрешает загрузку только тех ресурсов, которые были запакованы вместе с расширением:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "default-src 'self'" +</pre> + +<h3 id="Недопустимые_примеры">Недопустимые примеры</h3> + +<p>Политика, не включающая <code>"object-src"</code> директиву:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' https://*.jquery.com;"</pre> + +<p>Политика, не включающая ключевое слово <code>"self"</code> в <code>"script-src"</code> директиве:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src https://*.jquery.com; object-src 'self'"</pre> + +<p>Использование отличной от <code>https</code> схемы для загрузки удалённых ресурсов:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' http://code.jquery.com; object-src 'self'"</pre> + +<p>Использование универсального символа в связке с публичным доменным суффиксом:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' https://*.blogspot.com; object-src 'self'"</pre> + +<p>Указание схемы без хоста:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' https:; object-src 'self'"</pre> + +<p>Использование неподдерживаемого ключевого слова <code>'unsafe-inline'</code>:</p> + +<pre class="brush: json no-line-numbers">"content_security_policy": "script-src 'self' 'unsafe-inline'; object-src 'self'"</pre> + +<p><span id="exampleNote_1">1. <em>Примечание: Работающие примеры демонстрируют правильное написание политики защиты содержимого. Тем не менее, расширения с политикой, включающей ключевые словами 'unsafe-eval', 'unsafe-inline', разрешающей загрузку удалённых скриптов и ресурсов, а так же blob файлов не будут допущены к распространению на addons.mozilla.org из-за значительных проблем с безопасностью.</em></span></p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.content_security_policy")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/description/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/description/index.html new file mode 100644 index 0000000000..46c7310329 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/description/index.html @@ -0,0 +1,44 @@ +--- +title: description +slug: Mozilla/Add-ons/WebExtensions/manifest.json/description +tags: + - Reference + - WebExtensions + - description +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/description +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Нет</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json no-line-numbers"> +"description": "Заменяет картинки на картинки с котиками."</pre> + </td> + </tr> + </tbody> +</table> + +<p>Краткое описание дополнения, предназначенное для показа в интерфейсе браузера.</p> + +<p>Это <a href="/ru/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">локализуемое свойство</a>.</p> + +<h2 id="Пример">Пример</h2> + +<pre class="brush: json no-line-numbers">"description": "Заменяет картинки на картинки с котиками."</pre> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.description")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/icons/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/icons/index.html new file mode 100644 index 0000000000..4352adba81 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/icons/index.html @@ -0,0 +1,80 @@ +--- +title: ключ icons +slug: Mozilla/Add-ons/WebExtensions/manifest.json/icons +tags: + - Icons + - WebExtensions + - Веб-расширение + - Дополнения + - Расширения +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/icons +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Нет</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json"> +"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>Ключ <code>icons</code> определяет, какие иконки (значки) будет использовать ваше дополнение. Эти иконки будут использоваться при показе вашего дополнения в менеджерах компонентов, таких как Менеджер Дополнений.</p> + +<p>Он содержит информацию вида ключ-значение со следующими данными: размер изображения в пикселях и путь к соответствующему изображению относительно директории, в которой содержится дополнение.</p> + +<p>Если иконки не предоставлены с помощью этого ключа <code>icons</code>, вместо них будет использоваться стандартная иконка для расширений.</p> + +<p>Вы должны указать по крайней мере одну главную иконку, в идеале размером 48х48 пикселей. Эта иконка будет использоваться по умолчанию в Менеджере Дополнений. Конечно, можно добавить иконки любого размера, и Firefox постарается найти лучшую из них для показа в разных компонентах.</p> + +<p>Firefox учитывает разрешение экрана, когда выбирает иконку. Чтобы получить наилучший результат на мониторах с большим разрешением, использующих технологию Retina display, добавьте для каждой иконки версию с размерами в два раза больше.</p> + +<h2 id="Пример">Пример</h2> + +<p>Ключи в объекте icons определяют размеры иконок в пикселях, значения - относительный путь к файлам с изображениями. Этот пример содержит иконку размером 48х48 пикселей и увеличенную версию для мониторов высокого разрешения.</p> + +<pre class="brush: json">"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + +<h2 id="SVG">SVG</h2> + +<p>В качестве иконки можно использовать файл SVG. Тогда браузер будет масштабировать иконку так, чтобы она подходила к компоненту, в котором она используется. Но есть два предостережения:</p> + +<ol> + <li>В файле изображения должен быть определён viewBox. Например: + <pre class="brush: html"><svg viewBox="0 0 48 48" width="48" height="48" ...</pre> + </li> + <li>Даже в том случае, если используется всего один файл, нужно определить его для разных размеров иконки в манифесте. Например: + <pre class="brush: json">"icons": { + "48": "icon.svg", + "96": "icon.svg" +}</pre> + </li> +</ol> + +<div class="note"> +<p>Если вы используете программу Inkscape или подобную ей для создания SVG, сохраняйте изображение как "Простой SVG". Иначе Firefox может запутаться во множестве специальных пространств имён и не отобразить картинку.</p> +</div> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">Таблица совместимости на этой странице сгенерирована из структурированных данных. Если вы хотите дополнить эти данные, пожалуйста, навестите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</p> + +<p>{{Compat("webextensions.manifest.icons")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/index.html new file mode 100644 index 0000000000..661cf31e12 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/index.html @@ -0,0 +1,139 @@ +--- +title: manifest.json +slug: Mozilla/Add-ons/WebExtensions/manifest.json +tags: + - WebExtensions + - manifest.json + - Веб-расширения + - Дополнения + - Обзор + - Расширения +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json +--- +<p>{{AddonSidebar}}</p> + +<div class="blockIndicator note"> +<p>В этой статье описан файл manifest.json для веб-расширений. Если Вы ищете информацию о manifest.json для Прогрессивных веб-приложений (PWAs), смотрите статью <a href="/ru/docs/Web/Манифест">Манифест веб-приложения</a>.</p> +</div> + +<p>Файл <code>manifest.json</code> это единственный файл, который обязательно должен быть в каждом расширении, использующем API Веб-расширения (WebExtension APIs).</p> + +<p>Используя manifest.json, Вы определяете базовые метаданные о расширении, такие как имя и версия. Также можно определить некоторые аспекты функционала (такие, как фоновые скрипты, контент скрипты и действия браузера).</p> + +<p>Это файл в формате <a href="ru/docs/Словарь/JSON">JSON</a>, но в нём можно использовать комментарии, каждая строка которых должна начинаться с "<code>//</code>".</p> + +<h2 id="Список_полей_manifest.json">Список полей manifest.json</h2> + +<p>Поддерживаемые <code>manifest.json</code> поля перечислены ниже:</p> + +<div class="twocolumns">{{ListSubpages ("/en-US/Add-ons/WebExtensions/manifest.json") }}</div> + +<h3 class="index" id="Примечания_о_полях_manifest.json">Примечания о полях manifest.json</h3> + +<ul> + <li>Поля <code>"manifest_version"</code>, <code>"version"</code> и <code>"name"</code> являются обязательными.</li> + <li>Поле <code>"default_locale"</code> обязательно, если есть папка <code>"_locales"</code>, иначе его нужно опустить.</li> + <li>Поле <code>"browser_specific_settings"</code> не поддерживается Google Chrome.</li> +</ul> + +<h3 id="Доступ_к_полям_manifest.json_во_время_выполнения">Доступ к полям manifest.json во время выполнения</h3> + +<p>C помощью функции JavaScript {{WebExtAPIRef("runtime.getManifest()")}} можно получить доступ к файлу манифеста расширения:</p> + +<pre class="brush: js; no-line-numbers">browser.runtime.getManifest().version;</pre> + +<h2 id="Пример">Пример</h2> + +<p>В следующем блоке показан основной синтаксис некоторых часто используемых полей манифеста.</p> + +<div class="blockIndicator note"> +<p><strong>Примечание:</strong> Этот пример не рассчитан для того, чтобы его скопировали и вставили в файл реального проекта. Выбор нужных полей зависит от особенностей создаваемого расширения.</p> +</div> + +<p>Если нужны примеры готовых расширений, смотрите <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Examples">Примеры расширений</a>.</p> + +<pre class="brush: json;">{ + "browser_specific_settings": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0" + } + }, + + "background": { + "scripts": ["jquery.js", "my-background.js"], + }, + + "browser_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "commands": { + "toggle-feature": { + "suggested_key": { + "default": "Ctrl+Shift+Y", + "linux": "Ctrl+Shift+U" + }, + "description": "Send a 'toggle-feature' event" + } + }, + + "content_security_policy": "script-src 'self' https://example.com; object-src 'self'", + + "content_scripts": [ + { + "exclude_matches": ["*://developer.mozilla.org/*"], + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ], + + "default_locale": "en", + + "description": "...", + + "icons": { + "48": "icon.png", + "96": "icon@2x.png" + }, + + "manifest_version": 2, + + "name": "...", + + "page_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "permissions": ["webNavigation"], + + "version": "0.1", + + "user_scripts": { + "api_script": "apiscript.js", + }, + + "web_accessible_resources": ["images/my-image.png"] +}</pre> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p>Для полного обзора всех полей манифеста и их содержимого, смотрите <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">полную таблицу совместимости <code>manifest.json</code></a> с браузерами.</p> + +<div class="hidden">Таблица совместимости сгенерирована из структурированных данных. Если Вы хотите дополнить эти данные, пожалуйста, посмотрите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</div> + +<p>{{Compat("webextensions.manifest")}}</p> + +<h2 id="Смотрите_также">Смотрите также</h2> + +<p>{{WebExtAPIRef("permissions")}} JavaScript API</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html new file mode 100644 index 0000000000..1cf7875003 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/manifest_version/index.html @@ -0,0 +1,45 @@ +--- +title: ключ manifest_version +slug: Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version +tags: + - Reference + - WebExtensions + - manifest_version +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>Number</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Да</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json"> +"manifest_version": 2</pre> + </td> + </tr> + </tbody> +</table> + +<p>Этот ключ определяет версию файла "manifest.json", использующуюся в этом дополнении.</p> + +<p>В настоящее время всегда должен быть 2</p> + +<h2 id="Пример">Пример</h2> + +<pre class="brush: json">"manifest_version": 2 +</pre> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">Таблица совместимости на этой странице сгенерирована из структурированных данных. Если вы хотите дополнить эти данные, пожалуйста, посетите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</p> + +<p>{{Compat("webextensions.manifest.manifest_version")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/name/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/name/index.html new file mode 100644 index 0000000000..59c50eafdd --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/name/index.html @@ -0,0 +1,44 @@ +--- +title: ключ name +slug: Mozilla/Add-ons/WebExtensions/manifest.json/name +tags: + - Reference + - WebExtensions + - name +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/name +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Да</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json"> +"name": "My Extension"</pre> + </td> + </tr> + </tbody> +</table> + +<p>Имя расширения. Используется для идентификации расширения в интерфейсе браузера и на сайтах, подобных addons.mozilla.org.</p> + +<p>Это <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">локализуемое свойство</a>.</p> + +<h2 id="Пример">Пример</h2> + +<pre class="brush: json">"name": "My Extension"</pre> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">Таблица совместимости на этой странице сгенерирована из структурированных данных. Если вы хотите дополнить эти данные, пожалуйста, посетите <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> и отправьте нам pull request.</p> + +<p>{{Compat("webextensions.manifest.name")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/permissions/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/permissions/index.html new file mode 100644 index 0000000000..bfe2556a86 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/permissions/index.html @@ -0,0 +1,193 @@ +--- +title: permissions +slug: Mozilla/Add-ons/WebExtensions/manifest.json/permissions +tags: + - Web-расширение + - Полномочия + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/permissions +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>Массив</code></td> + </tr> + <tr> + <th scope="row">Обязателен</th> + <td>Нет</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json; no-line-numbers"> +"permissions": [ + "*://developer.mozilla.org/*", + "webRequest" +]</pre> + </td> + </tr> + </tbody> +</table> + +<p>Используйте ключ<span style='font-family: "Times New Roman","serif"; font-size: 12.0pt; line-height: 115%;'> </span> <code>permissions</code> для получения дополнительных возможностей для вашего расширения. Значением ключа является массив строк, каждая из которых представляет собой запрос на какие-либо полномочия.</p> + +<p>При объявлении запросов полномочий с помощью этого ключа, браузер проинформирует пользователей, о том какие полномочия необходимы расширению во время его установки, и задаст вопрос, согласны ли они выдать их расширению. Браузер так же даёт пользователям возможность изучить полномочия расширения уже после установки. Так как требование дополнительных полномочий может повлиять на желание пользователя использовать ваше расширение, решение использования конкретного функционала может стоить тщательного рассмотрения. К примеру, есть смысл избегать запрашивания необязательных полномочий, и предоставлять информацию о том, зачем вашему расширению нужны какие-либо полномочия в описании расширения. Более подробная информация о проблемах, которые вам стоит рассмотреть касательно этой темы, предоставлена в статье <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Request_the_right_permissions">Запрашивание правильных полномочий</a>.</p> + +<p>Значение ключа может содержать три вида запросов полномочий:</p> + +<ul> + <li>Запрос на полномочия для хоста</li> + <li>Запрос на API полномочия</li> + <li>Запрос на activeTab полномочия</li> +</ul> + +<h2 id="Запрос_полномочий_для_хоста">Запрос полномочий для хоста</h2> + +<p>Запрос на полномочия для хоста объявляется через <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">шаблоны совпадения</a>, где каждый шаблон определяет группу URL, при посещении которых расширение будет иметь эти дополнительные полномочия. Например, запрос на полномочия для хоста может быть задан подобной строкой <code>"*://developer.mozilla.org/*"</code>.</p> + +<p>Полномочия для хоста включают:</p> + +<ul> + <li>Возможность выполнять <a href="/ru/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a> и <a href="/ru/docs/Web/API/Fetch_API">fetch</a> запросы на ресурсы, которые имеют заданный origin, не испытывая cross-origin ограничений (даже для запросов, выполняемых из встраиваемого скрипта)</li> + <li>Возможность встраивать скрипты программным путём, используя <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript</a>, на веб-страницах загруженных с заданного origin</li> + <li>Возможность обрабатывать события из <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a> API для заданных хостов</li> + <li>Доступ к сookies на заданных хостах, используя <a href="/ru/Add-ons/WebExtensions/API/cookies">cookies</a> API, при условии получения дополнительного "cookies" API полномочия.</li> + <li>Возможность обходить защиту от слежения, при условии полностью указанного хоста, без использования универсального символа <code>*</code>. Не будет работать с <code><all_urls></code>.</li> +</ul> + +<p>В Firefox, начиная с версии 56, расширения автоматически получают полномочия для своего собственного хоста, который имеет вид:</p> + +<pre><code>moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/</code></pre> + +<p>где <code>60a20a9b-1ad4-af49-9b6c-c64c98c37920</code> - внутреннее ID расширения. Расширение может получить это URL программным путём, через вызов метода <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/extension/getURL">extension.getURL()</a>:</p> + +<pre class="brush: js;">browser.extension.getURL(""); +// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/ +</pre> + +<h2 id="Запрос_на_API_полномочия">Запрос на API полномочия</h2> + +<p>Запрос на API полномочия объявляется через ключевые слова, каждое из которых представляет собой название <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API">WebExtension API</a>, доступ к которому необходим расширению.</p> + +<p>Следующие ключевые слова доступны на данный момент:</p> + +<ul> + <li><code>activeTab</code></li> + <li><code>alarms</code></li> + <li><code>background</code></li> + <li><code>bookmarks</code></li> + <li><code>browserSettings</code></li> + <li><code>browsingData</code></li> + <li><code>clipboardRead</code></li> + <li><code>clipboardWrite</code></li> + <li><code>contentSettings</code></li> + <li><code>contextMenus</code></li> + <li><code>contextualIdentities</code></li> + <li><code>cookies</code></li> + <li><code>debugger</code></li> + <li><code>dns</code></li> + <li><code>downloads</code></li> + <li><code>downloads.open</code></li> + <li><code>find</code></li> + <li><code>geolocation</code></li> + <li><code>history</code></li> + <li><code>identity</code></li> + <li><code>idle</code></li> + <li><code>management</code></li> + <li><code>menus</code></li> + <li><code>menus.overrideContext</code></li> + <li><code>nativeMessaging</code></li> + <li><code>notifications</code></li> + <li><code>pageCapture</code></li> + <li><code>pkcs11</code></li> + <li><code>privacy</code></li> + <li><code>proxy</code></li> + <li><code>search</code></li> + <li><code>sessions</code></li> + <li><code>storage</code></li> + <li><code>tabHide</code></li> + <li><code>tabs</code></li> + <li><code>theme</code></li> + <li><code>topSites</code></li> + <li><code>unlimitedStorage</code></li> + <li><code>webNavigation</code></li> + <li><code>webRequest</code></li> + <li><code>webRequestBlocking</code></li> +</ul> + +<p>В большинстве случаев полномочие просто делает возможным доступ к определённому API, за исключением следующих ситуаций:</p> + +<ul> + <li><code>tabs</code> предоставляет доступ к <a href="/ru/Add-ons/WebExtensions/API/tabs">привилегированным частям <code>tabs</code> API</a>: <code>Tab.url</code>, <code>Tab.title</code>, and <code>Tab.faviconUrl</code>. В Firefox, вам так же понадобятся <code>tabs</code> полномочия, если вы собираетесь использовать <code>url</code> ключ в параметре <code>queryInfo</code> для <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code> метода. Весь остальной <code>tabs</code> API доступен без запрашивания каких-либо полномочий.</li> + <li><code>webRequestBlocking</code> позволяет вам использовать "blocking" аргумент, для возможности <a href="/ru/Add-ons/WebExtensions/API/WebRequest">изменять и отменять запросы</a>.</li> + <li><code>downloads.open</code> позволяет использовать {{WebExtAPIRef("downloads.open()")}} API.</li> + <li><code>tabHide</code> позволяет использовать {{WebExtAPIRef("tabs.hide()")}} API.</li> +</ul> + +<h2 id="Запрос_на_activeTab_полномочия">Запрос на activeTab полномочия</h2> + +<p>Этот вид запроса объявляется через ключевое слово <code>"activeTab"</code>. <code>activeTab</code> полномочия предоставляются расширению на активной в данный момент вкладке, и вступают в эффект только в момент, когда пользователь взаимодействует с расширением.</p> + +<p>"Взаимодействие пользователя" включает:</p> + +<ul> + <li>Пользователь нажимает на кнопку расширения на панели инструментов или адресной строке</li> + <li>Пользователь взаимодействует с контекстным меню расширения</li> + <li>Пользователь нажимает комбинацию клавиш, ассоциированную с расширением</li> +</ul> + +<p>activeTab полномочия включают:</p> + +<ul> + <li>Возможность программно встраивать JavaScript или CSS на страницу, используя <code><a href="/ru/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript</a></code> и <code><a href="/ru/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS</a></code></li> + <li>Получение доступа к привилегированным частям tabs API для активной вкладки: <code>Tab.url</code>, <code>Tab.title</code> и <code>Tab.faviconUrl</code>.</li> +</ul> + +<p>Цель этих полномочий – позволить расширению выполнять наиболее распространенные сценарии работы, без необходимости выдавать ему более серьёзные привилегии, так как большинство расширений задумано для выполнения какой-либо работы на активной вкладке после взаимодействия с пользователем. Например, представьте расширение, которое встраивает скрипт на текущую страницу, после того как пользователь нажимает на кнопку расширения на панели инструментов. Если бы <code>activeTab</code> полномочий не существовало, расширению бы пришлось запрашивать <code><all_urls></code>. Но они бы давали расширению намного больше привилегий, чем ему было бы необходимо: расширение могло бы встраивать скрипты на любую вкладку и в любой момент, когда пожелает.</p> + +<p>Заметьте, что вы сможете иметь доступ к привилегированному tab API, только на момент взаимодействия расширения с пользователем, и пока вкладка не изменила своё состояние. То есть расширение перестанет иметь данные привилегии при изменении адреса страницы или каком-либо другом событии с вкладкой.</p> + +<p>Обычно вкладкой, получающей <code>activeTab</code> полномочия, является активная в данный момент вкладка, за исключением одного случая. <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/menus">menus</a></code> API позволяет расширению создавать элементы контекстного меню, которые будут появляться непосредственно при нажатии на вкладку (элемент на панели вкладок, при нажатии на который изменяется активная вкладка). Если пользователь вызывает контекстное меню на этом элементе, тогда <code>activeTab</code> полномочия выдадутся для вкладки, по которой было произведено нажатие, несмотря на то, что она могла бы не является активной ({{bug(1446956)}} начиная с Firefox версии 63).</p> + +<h2 id="Доступ_к_буферу_обмена">Доступ к буферу обмена</h2> + +<p>Два полномочия предоставляют расширению привилегии для взаимодействия с буфером обмена:</p> + +<ul> + <li><code>clipboardWrite</code>: для записи в буфер обмена с помощью {{DOMxRef("Clipboard.write()")}}, {{DOMxRef("Clipboard.writeText()")}}, <code>document.execCommand("copy")</code> или <code>document.execCommand("cut")</code></li> + <li><code>clipboardRead</code>: для чтения из буфера обмена с помощью {{DOMxRef("Clipboard.read()")}}, {{DOMxRef("Clipboard.readText()")}} или <code>document.execCommand("paste")</code></li> +</ul> + +<p>Смотрите <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard">Взаимодействие с буфером обмена</a> для более подробной информации.</p> + +<h2 id="Неограниченное_хранилище">Неограниченное хранилище</h2> + +<p>Полномочие <code>unlimitedStorage</code>:</p> + +<ul> + <li>Позволяет расширению превышать любые ограничения размера хранимой информации для {{WebExtAPIRef("storage.local")}} API</li> + <li>В Firefox, позволяет расширению создавать <a href="/ru/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria#Firefox_specifics">"persistent" базу данных IndexedDB</a>, не запрашивая разрешения у пользователя в момент её создания.</li> +</ul> + +<h2 id="Примеры">Примеры</h2> + +<pre class="brush: json no-line-numbers"> "permissions": ["*://developer.mozilla.org/*"]</pre> + +<p>Запрашивает полномочия для хостов, имеющих developer.mozilla.org в их URL.</p> + +<pre class="brush: json no-line-numbers"> "permissions": ["tabs"]</pre> + +<p>Запрашивает доступ к привилегированным частям <code>tabs</code> API.</p> + +<pre class="brush: json no-line-numbers"> "permissions": ["*://developer.mozilla.org/*", "tabs"]</pre> + +<p>Запрашивает несколько типов полномочий из примеров выше.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.permissions")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/manifest.json/version/index.html b/files/ru/mozilla/add-ons/webextensions/manifest.json/version/index.html new file mode 100644 index 0000000000..42892c82af --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/manifest.json/version/index.html @@ -0,0 +1,49 @@ +--- +title: ключ version +slug: Mozilla/Add-ons/WebExtensions/manifest.json/version +tags: + - Reference + - WebExtensions + - version +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/version +--- +<p>{{AddonSidebar}}</p> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Тип</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">Обязательный</th> + <td>Да</td> + </tr> + <tr> + <th scope="row">Пример</th> + <td> + <pre class="brush: json no-line-numbers"> +"version": "0.1"</pre> + </td> + </tr> + </tbody> +</table> + +<p>Версия дополнения, отформатированная как числа и символы ASCII, разделенные точками. Подробнее о формате версий смотрите страницу <a href="https://developer.mozilla.org/ru/docs/Toolkit_version_format">Version format</a>.</p> + +<p>Обратите внимание, что <a href="https://developer.chrome.com/extensions/manifest/version">синтаксис ключа <code>version</code> для Chrome</a> более ограниченный, чем у Firefox:</p> + +<ul> + <li>значения <code>version</code> которые действительны для Chrome, всегда будут действительны для Firefox</li> + <li>значения <code>version</code> которые действительны для Firefox, могут быть не действительны для Chrome</li> +</ul> + +<h2 id="Пример">Пример</h2> + +<pre class="brush: json no-line-numbers">"version": "0.1"</pre> + +<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.version")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/match_patterns/index.html b/files/ru/mozilla/add-ons/webextensions/match_patterns/index.html new file mode 100644 index 0000000000..17ac749843 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/match_patterns/index.html @@ -0,0 +1,426 @@ +--- +title: Шаблоны совпадения в расширении +slug: Mozilla/Add-ons/WebExtensions/Match_patterns +translation_of: Mozilla/Add-ons/WebExtensions/Match_patterns +--- +<div>{{AddonSidebar}}</div> + +<p>Шаблоны совпадения - являются способом обозначения необходимых групп URL. Они используются в нескольких местах в WebExtensions API, главным образом для объявления какие веб-страницы должны загружать <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">встраиваемые скрипты</a> и по каким URL необходимо ожидать событий из <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a></code> API.</p> + +<p>API, которое использует шаблоны совпадения, обычно принимает их списками, и выполняет соответствующие действия, если URL имеет совпадение с одним из шаблонов. Например, взгляните на <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> ключ в manifest.json.</p> + +<h2 id="Структура_шаблона_совпадения">Структура шаблона совпадения</h2> + +<div class="note"> +<p><strong>Заметьте:</strong> Некоторые браузеры не поддерживают определённые схемы.<br> + Смотрите <a href="#Browser_compatibility">Browser compatibility table</a> для дополнительной информации.</p> +</div> + +<p>Все шаблоны совпадения объявляются в виде строк. За исключением специального <code><a href="/ru/Add-ons/WebExtensions/Match_patterns#%3Call_urls%3E"><all_urls></a></code> шаблона, шаблоны совпадения состоят из трёх компонентов: <em>схема</em>, <em>хост</em> и <em>путь</em>. Схема и хост разделяются с помощью <code>://</code>.</p> + +<pre><схема>://<хост><путь></pre> + +<h3 id="Схема">Схема</h3> + +<p>Компонент<em> схема</em> может принимать один из двух видов:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Вид</th> + <th scope="col">Совпадение</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>*</code></td> + <td>Только "http" and "https", так же <a href="/ru/docs/Web/API/WebSockets_API">"ws" и "wss"</a> в некоторых браузерах.</td> + </tr> + <tr> + <td>Одно из <code>http</code>, <code>https</code>, <code>ws</code>, <code>wss</code>, <code>ftp</code>, <code>ftps</code>, <code>data</code> или <code>file</code>.</td> + <td>Только данная схема.</td> + </tr> + </tbody> +</table> + +<h3 id="Хост">Хост</h3> + +<p>Компонент<em> хост</em> может принимать один из трёх видов:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Form</th> + <th scope="col">Matches</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>*</code></td> + <td>Любой хост.</td> + </tr> + <tr> + <td><code>*.</code> за которыми следует частичное имя хоста.</td> + <td>Данный хост и любые его субдомены.</td> + </tr> + <tr> + <td>Полное название хоста без <code>*</code>.</td> + <td>Только данный хост.</td> + </tr> + </tbody> +</table> + +<p><em>Хост</em> не должен включать в себя значение порта.</p> + +<p><em>Хост</em> не обязателен, если <em>схема </em>задана, как "file".</p> + +<p>Заметьте, что <code>*</code> звёздочка (символ универсального значения) может быть написана только в начале строки.</p> + +<h3 id="Путь">Путь</h3> + +<p>Компонент<em> путь</em> должен начинаться с <code>/</code> символа.</p> + +<p>Вслед за ним он может иметь любую комбинацию символов и <code>*</code> звёздочек, которые позволено использовать для обозначения URL и строки параметров (начинается после <code>?</code>). В отличии от <em>хоста</em>, <em>путь</em> может содержать <code>*</code> звёздочку в середине или в конце строки, и <code>*</code> звёздочка может появляться в строке более одного раза.</p> + +<p>Значение <em>пути</em> сравнивается со строкой, которая представляет из себя URL и <a href="https://en.wikipedia.org/wiki/Query_string">строку параметров</a>. Если строка параметров присутствует в URL, тогда она отделяется от основного URL знаком <code>?</code>. Если вы хотите иметь соответствие с URL на любом домене, где URL путь кончается на <code>foo.bar</code>, не зависимо от присутствия строки параметров, тогда вам нужно иметь массив шаблонов совпадений, например <code>['*://*/*foo.bar', '*://*/*foo.bar?*']</code>. В этой ситуации необходимо использовать <code>?*</code>, а не <code>bar*</code>, для того чтобы обозначить, что <code>*</code> будет применяться к строке параметров, а не к основной части URL пути.</p> + +<p>Ни <a href="https://en.wikipedia.org/wiki/Fragment_identifier">идентификатор якоря</a>, ни предшествующая ему <code>#</code>, не считаются частями<em> пути</em>.</p> + +<h3 id="<all_urls>"><all_urls></h3> + +<p>Специальное значение <code><all_urls></code> совпадает со всеми URL, если они используются со следующими схемами: "http", "https", "ws", "wss", "ftp", "data", and "file".</p> + +<h2 id="Примеры">Примеры</h2> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 33%;">Шаблон</th> + <th scope="col" style="width: 33%;">Пример совпадения</th> + <th scope="col" style="width: 33%;">Пример несовпадения</th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p><code><all_urls></code></p> + + <p>Совпадение со всеми URL.</p> + </td> + <td> + <p><code>http://example.org/</code></p> + + <p><code>https://a.org/some/path/</code></p> + + <p><code>ws://sockets.somewhere.org/</code></p> + + <p><code>wss://ws.example.com/stuff/</code></p> + + <p><code>ftp://files.somewhere.org/</code></p> + + <p><code>ftps://files.somewhere.org/</code></p> + </td> + <td> + <p><code>resource://a/b/c/</code><br> + (неподдерживаемая схема)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://*/*</code></p> + + <p>Совпадение со всеми HTTP, HTTPS и WebSocket URL.</p> + </td> + <td> + <p><code>http://example.org/</code></p> + + <p><code>https://a.org/some/path/</code></p> + + <p><code>ws://sockets.somewhere.org/</code></p> + + <p><code>wss://ws.example.com/stuff/</code></p> + </td> + <td> + <p><code>ftp://ftp.example.org/</code><br> + (несовпадающая схема)</p> + + <p><code>ftps://ftp.example.org/</code><br> + (несовпадающая схема)</p> + + <p><code>file:///a/</code><br> + (несовпадающая схема)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://*.mozilla.org/*</code></p> + + <p>Совпадение со всеми HTTP, HTTPS и WebSocket URL, которые находятся на "mozilla.org" или одном из её субдоменов.</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + + <p><code>http://a.mozilla.org/</code></p> + + <p><code>http://a.b.mozilla.org/</code></p> + + <p><code>https://b.mozilla.org/path/</code></p> + + <p><code>ws://ws.mozilla.org/</code></p> + + <p><code>wss://secure.mozilla.org/something</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (несовпадающая схема)</p> + + <p><code>http://mozilla.com/</code><br> + (несовпадающий хост)</p> + + <p><code>http://firefox.org/</code><br> + (несовпадающий хост)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://mozilla.org/</code></p> + + <p>Совпадение со всеми HTTP, HTTPS и WebSocket URL, которые находятся исключительно на "mozilla.org/".</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + + <p><code>ws://mozilla.org/</code></p> + + <p><code>wss://mozilla.org/</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (несовпадающая схема)</p> + + <p><code>http://a.mozilla.org/</code><br> + (несовпадающий хост)</p> + + <p><code>http://mozilla.org/a</code><br> + (несовпадающий путь)</p> + </td> + </tr> + <tr> + <td> + <p><code>ftp://mozilla.org/</code></p> + + <p>Совпадение только с "ftp://mozilla.org/".</p> + </td> + <td><code>ftp://mozilla.org</code></td> + <td> + <p><code>http://mozilla.org/</code><br> + (несовпадающая схема)</p> + + <p><code>ftp://sub.mozilla.org/</code><br> + (несовпадающий хост)</p> + + <p><code>ftp://mozilla.org/path</code><br> + (несовпадающий путь)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path</code></p> + + <p>Совпадение со всеми HTTPS URL на любом хосте, чей путь точно соответсвует "path".</p> + </td> + <td> + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://a.mozilla.org/path</code></p> + + <p><code>https://something.com/path</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (несовпадающая схема)</p> + + <p><code>https://mozilla.org/path/</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/a</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/path?foo=1</code><br> + (несовпадающий путь из-за строки параметров)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path/</code></p> + + <p>Совпадение со всеми HTTPS URL на любом хосте, чей путь точно соответсвует "path/" и не имеет строки параметров.</p> + </td> + <td> + <p><code>https://mozilla.org/path/</code></p> + + <p><code>https://a.mozilla.org/path/</code></p> + + <p><code>https://something.com/path</code>/</p> + </td> + <td> + <p><code>http://mozilla.org/path/</code><br> + (несовпадающая схема)</p> + + <p><code>https://mozilla.org/path</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/a</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/path/</code><code>?foo=1</code><br> + (несовпадающий путь из-за строки параметров)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*</code></p> + + <p>Совпадение со всеми HTTPS URL только на домене "mozilla.org", с любым URL путём и строкой параметров.</p> + </td> + <td> + <p><code>https://mozilla.org/</code></p> + + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://mozilla.org/another</code></p> + + <p><code>https://mozilla.org/path/to/doc</code></p> + + <p><code>https://mozilla.org/path/to/doc?foo=1</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (несовпадающая схема)</p> + + <p><code>https://mozilla.com/path</code><br> + (несовпадающий хост)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p>Совпадение только с данным URL, или данным URL, имеющим идентификатор якоря.</p> + </td> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p><code>https://mozilla.org/a/b/c/#section1</code></p> + </td> + <td>Всё остальное.</td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*/b/*/</code></p> + + <p>Совпадение только с HTTPS URL, которые находятся на "mozilla.org", чей путь имеет сегмент "b" где-то в середине. Совпадёт с URL со строкой параметров, если эта строка параметров заканчивается на <code>/</code>.</p> + </td> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p><code>https://mozilla.org/d/b/f/</code></p> + + <p><code>https://mozilla.org/a/b/c/d/</code></p> + + <p><code>https://mozilla.org/a/b/c/d/#section1</code></p> + + <p><code>https://mozilla.org/a/b/c/d/?foo=/</code></p> + + <p><code>https://mozilla.org/a?foo=21314&bar=/b/&extra=c/</code></p> + </td> + <td> + <p><code>https://mozilla.org/b/*/</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/a/b/</code><br> + (несовпадающий путь)</p> + + <p><code>https://mozilla.org/a/b/c/d/?foo=bar</code><br> + (несовпадающий путь из-за строки параметров)</p> + </td> + </tr> + <tr> + <td> + <p><code>file:///blah/*</code></p> + + <p>Совпадает с любым FILE URL, чей путь начинается с "blah".</p> + </td> + <td> + <p><code>file:///blah/</code></p> + + <p><code>file:///blah/bleh</code></p> + </td> + <td><code>file:///bleh/</code><br> + (несовпадающий путь)</td> + </tr> + </tbody> +</table> + +<h3 id="Недопустимые_шаблоны_совпадения">Недопустимые шаблоны совпадения</h3> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Недопустимый шаблон</th> + <th scope="col">Причина</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>resource://path/</code></td> + <td>Неподдерживаемая схема.</td> + </tr> + <tr> + <td><code>https://mozilla.org</code></td> + <td>Отсутствие пути.</td> + </tr> + <tr> + <td><code>https://mozilla.*.org/</code></td> + <td>"*" в хосте должна присутствовать только в начале.</td> + </tr> + <tr> + <td><code>https://*zilla.org/</code></td> + <td>"*" в хосте должен быть единственным символом или сопровождаться ".".</td> + </tr> + <tr> + <td><code>http*://mozilla.org/</code></td> + <td>"*" в схеме должен быть единственным символом.</td> + </tr> + <tr> + <td><code>https://mozilla.org:80/</code></td> + <td>Хост не должен включать в себя номер порта.</td> + </tr> + <tr> + <td><code>*://*</code></td> + <td>Пустой путь: должно быть переписано, как "<code>*://*/*</code>".</td> + </tr> + <tr> + <td><code>file://*</code></td> + <td>Пустой путь: должно быть переписано, как "<code>file:///*</code>".</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<h3 id="scheme">scheme</h3> + + + +<p>{{Compat("webextensions.match_patterns.scheme",10)}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/prerequisites/index.html b/files/ru/mozilla/add-ons/webextensions/prerequisites/index.html new file mode 100644 index 0000000000..e18158e724 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/prerequisites/index.html @@ -0,0 +1,8 @@ +--- +title: Prerequisites +slug: Mozilla/Add-ons/WebExtensions/Prerequisites +translation_of: Mozilla/Add-ons/WebExtensions/Prerequisites +--- +<div>{{AddonSidebar}}</div> + +<p>Всё что вам нужно - это Firefox 45 или выше. Смотрите <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">Your first WebExtension</a> для того чтобы начать.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/browser_action/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/browser_action/index.html new file mode 100644 index 0000000000..ba7e259817 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/browser_action/index.html @@ -0,0 +1,50 @@ +--- +title: Кнопка в панели инструментов +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +tags: + - Кнопка панели инструментов +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +<div>{{AddonSidebar}}</div> + +<p>Кнопка на панели инструментов браузера (оригинальное название <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browser action</a>) - это иконка, которую можно вывести в панель инструментов. Пользователь взаимодействует с расширением нажимая на нее как на кнопку.<br> + <img alt="" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="display: block; height: 387px; margin-left: auto; margin-right: auto; width: 782px;"></p> + +<p>Кнопка на панели инструментов одинаково отображается для любой открытой вкладки. Это предполагает, что расширение единообразно работает со всеми страницами.</p> + +<p>Например, предустановленная кнопка "обновить" перезагружает любую страницу в активной вкладке, кнопка "добавить в избранное" добавляет любой адрес активной вкладки в список избранного. Кнопка загрузок показывает единый для всего браузера список скачанных файлов, независимо от того что за страница открыта в активной вкладке.</p> + +<p>Применимые лишь к определенным страницам кнопки следует реализовывать с помощью кнопки в адресной строке (<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Page_actions">page action</a>).</p> + +<h2 id="Объявление_в_manifest.json"><span class="short_text" id="result_box" lang="ru"><span>Объявление в manifest.json</span></span></h2> + +<p>За кнопку на панели инструментов отвечает свойство манифеста <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code>:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"browser_action":</span> <span class="punctuation token">{</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span> +<span class="punctuation token">}</span></code></pre> + +<p>Свойство кнопки <code>default_icon</code> обязательно, оно определяет внешний вид кнопки - иконку, которая окажется на панели инструментов.</p> + +<p>Расширение может иметь только одну кнопку для панели инструментов.</p> + +<p>Возможны два способа реакции на нажатие кнопки: отображение <a href="/en-US/Add-ons/WebExtensions/Popups">всплывающего окна</a> (описано в отдельном разделе) или отправка события в background script расширения. В таком случае реакция на нажатие обеспечивают обработчики событий, подключенные к <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/BrowserAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>browserAction.onClicked</code></a>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>Если же указать в качестве реакции на нажатие всплывающее окно, то событие передано не будет. Вместо этого около кнопки отобразится всплывающее окно - отдельная маленькая страница, дальнейшее взаимодействие с пользователем берет на себя она. Подробнее этот сценарий описан на отдельной странице, посвященной <a href="/en-US/Add-ons/WebExtensions/Popups">всплывающим окнам</a>.</p> + +<p>Все свойства кнопки на панели инструментов можно изменить программно через API <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code>.</p> + +<h2 id="Примеры">Примеры</h2> + +<p><span id="result_box" lang="ru"><span>В GitHub репозитории</span></span> <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> представлены <span id="result_box" lang="ru"><span>несколько примеров расширений, которые создают кнопку на панели инструментов:</span></span></p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> использует событие browserAction.onClicked.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> открывает всплывающее окно.</li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html new file mode 100644 index 0000000000..229d378a2f --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html @@ -0,0 +1,54 @@ +--- +title: Контекстное меню +slug: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +<div> +<div>{{AddonSidebar}}</div> + +<div> +<p>Эта возможность пользовательского интерфейса позволяет добавлять новые элементы в контекстное меню браузера, появляющееся при нажатии правой кнопки мыши. Вкладки браузера также имеют контекстное меню доступное через<a href="/en-US/Add-ons/WebExtensions/API/menus"> browser.menus API</a>.</p> + +<p><img alt="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15756/context_menu_example.png" style="display: block; height: 382px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>Возможность добавления элементов в контекстное меню позволяет предоставлять пользователю различные функции в зависимости от его действий на странице или в браузере. Например, можно отобразить элемент, который открывает графический редактор, если пользователь нажимает на изображение, или же предложить функцию для сохранения содержимого страницы, если выбрана некоторая её часть. Элементы могут представлять из себя не только текст, но и, например, кнопку-переключатель или разделитель (см. <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus/ItemType">типы элементов меню</a>). После того, как элемент контекстного меню был добавлен с помощью {{WebExtAPIRef("contextMenus.create")}}, он отображается во всех вкладках браузера, но вы можете удалить его при помощи {{WebExtAPIRef("contextMenus.remove")}}.</p> +</div> +</div> + +<h2 id="Создание_элементов_контекстного_меню">Создание элементов контекстного меню</h2> + +<p>Управление элементами контекстного меню осуществляется с помощью {{WebExtAPIRef("contextMenus")}} API. Однако, вам необходимо указать разрешение <code>contextMenus</code> в manifest.json, чтобы им воспользоваться.</p> + +<pre class="brush: json">"permissions": ["contextMenus"]</pre> + +<p>Затем вы сможете добавлять, обновлять и удалять элементы контекстного меню в <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">фоновом сценарии</a> вашего расширения. Для создания элемента необходимо указать его id,<em> </em>заголовок и контекст, в котором элемент будет показан. В примере ниже элемент меню появляется, когда выделен текст или какая-либо другая часть страницы:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "log-selection", + title: browser.i18n.getMessage("contextMenuItemSelectionLogger"), + contexts: ["selection"] +}, onCreated);</pre> + +<p>Затем вы можете добавить обработчик события нажатия на элемент. Передаваемая обработчику информация о контексте, в котором произошло нажатие, и о вкладке, где контекстное меню было вызвано, может быть использована вами для определения дальнейшего поведения расширения.</p> + +<pre class="brush: js">browser.contextMenus.onClicked.addListener(function(info, tab) { + switch (info.menuItemId) { + case "log-selection": + console.log(info.selectionText); + break; + ... + } +})</pre> + +<h2 id="Иконки">Иконки</h2> + +<p>Чтобы добавить элементам меню икноки, смотрите документацию <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> в <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a>.</p> + +<h2 id="Примеры">Примеры</h2> + +<p>Репозиторий <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> на GitHub содержит два примера расширений, в которых реализована работа элементов контекстного меню:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/menu-demo">menu-demo</a> добавляет несколько элементов в контекстное меню;</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-copy-link-with-types">context-menu-copy-link-with-types</a> добавляет элемент контекстного меню, который копирует URL ссылки в буфер в виде текста и форматированного HTML.</li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html new file mode 100644 index 0000000000..fdb63f2252 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html @@ -0,0 +1,73 @@ +--- +title: Страницы расширения +slug: Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages +tags: + - UI + - WebExtensions + - Веб-расширения + - Для начинающих +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages +--- +<div>{{AddonSidebar()}}</div> + +<p><span class="seoSummary">В расширение можно добавить HTML-страницы, чтобы предоставить пользователю формы, помощь или другое необходимое содержимое.</span></p> + +<p><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15752/bundled_page_as_panel_small.png" style="display: block; height: 216px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>Эти страницы получат доступ к привилегированным средствам JavaScript API — таким же как те, что доступны фоновым скриптам расширения. Но каждая из них будет открыта в своей отдельной вкладке — со своей очередью задач JavaScript, своими глобальными переменными и т. д.</p> + +<p>Фоновую страницу можно считать "невидимой страницей расширения".</p> + +<h2 id="Определение_страниц_расширения">Определение страниц расширения</h2> + +<p>К расширению можно подключить файлы HTML и используемые в них файлы CSS и JavaScript. Можно расположить все эти файлы в корне папки расширения, а можно организовать более сложную структуру каталога.</p> + +<pre>/my-extension + /manifest.json + /my-page.html + /my-page.js</pre> + +<h2 id="Отображение_страниц_расширения">Отображение страниц расширения</h2> + +<p>Есть два способа отобразить страницу расширения: {{WebExtAPIRef("windows.create()")}} и {{WebExtAPIRef("tabs.create()")}}.</p> + +<p>Например для того, чтобы создать окно сообщения, можно с помощью функции <code>windows.create()</code> открыть страницу HTML в отсоединённой панели (detached panel) — в окне без строки адреса, полосы закладок и других обычных элементов управления:</p> + +<pre class="brush: js">let createData = { + type: "detached_panel", + url: "panel.html", + width: 250, + height: 100 +}; +let creating = browser.windows.create(createData);</pre> + +<p>Когда окно больше не будет нужно, его можно закрыть программно.</p> + +<p>Например, когда пользователь нажмёт на кнопку, можно вызвать функцию {{WebExtAPIRef("windows.remove()")}} и передать ей идентификатор текущего окна:</p> + +<pre class="brush: js">document.getElementById("closeme").addEventListener("click", function(){ + let winId = browser.windows.WINDOW_ID_CURRENT; + let removing = browser.windows.remove(winId); +}); </pre> + +<h2 id="Страницы_расширения_и_история">Страницы расширения и история</h2> + +<p>По умолчанию страницы, открытые таким образом, будут сохранены в истории браузера — точно так же, как и обычные веб-страницы. Если такое поведение не нужно, используйте {{WebExtAPIRef("history.deleteUrl()")}}, чтобы удалить запись:</p> + +<pre class="brush: js" id="ct-4">function onVisited(historyItem) { + if (historyItem.url == browser.extension.getURL(myPage)) { + browser.history.deleteUrl({url: historyItem.url}); + } +} + +browser.history.onVisited.addListener(onVisited);</pre> + +<p>Для использования API истории браузера нужно добавить разрешение "<code>history</code>" с помощью элемента <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a> в файле <code><a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code>.</p> + +<h2 id="Дизайн_веб-страницы">Дизайн веб-страницы</h2> + +<p>Подробности о том, как сделать, чтобы дизайн Ваших страниц совпадал со стилем Firefox, смотрите на сайте <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Система дизайна Photon</a> (на английском языке) и в документации <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles">browser styles</a>.</p> + +<h2 id="Примеры">Примеры</h2> + +<p>В репозитории <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> на GitHub есть пример <a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/window-manipulator">window-manipulator</a>, в котором используются некоторые из возможностей для создания окон.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..c35b6146c6 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,107 @@ +--- +title: Пользовательский интерфейс +slug: Mozilla/Add-ons/WebExtensions/user_interface +tags: + - Пользовательский интерфейс +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>У расширений WebExtensions есть несколько органов взаимодействия с пользователем, с их помощью человек пользуется <em>расширенным</em> функционалом. Все они перечислены ниже, с инструкцией как использовать в своем расширении каждый из них<span id="result_box" lang="ru"><span>.</span></span></p> + +<div class="note"> +<p><span id="result_box" lang="ru"><span>Советы как с помощью этих элементов пользовательского интерфейса (UI)</span></span><span lang="ru"><span> обеспечить отличное взаимодействие человека с программой вы найдёте в статье </span></span><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_experience_best_practices">User experience best practices</a>.</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Элемент UI</th> + <th scope="col">Назначение</th> + <th scope="col" style="width: 350px;">Как выглядит?</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">Кнопка на панели инструментов</a></td> + <td> + <p>Кнопка на панели инструментов доступна изо всех вкладок.<br> + Реакцию на нажатие кнопки обеспечивает расширение.</p> + </td> + <td><img alt="Example of a WebExtension toolbar button" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="height: 99px; width: 350px;"></td> + </tr> + <tr> + <td> + <p><s>Browser toolbar button with a <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popup</a></s></p> + </td> + <td> + <p><s>Кнопка со всплывающим окном на панели инструментов браузера, которая открывается при нажатии. Всплывающее окно определяется в документе HTML, который обрабатывает взаимодействие пользователя.</s></p> + </td> + <td> + <p><s><img alt="Example of a WebExtension toolbar button with a popup" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="height: 156px; width: 350px;"></s></p> + </td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">Кнопка в адресной строке</a></td> + <td>В отличие от панели инструментов, в адресной строке кнопка должна появляться только рядом с адресом предназначенной для нее страницы.</td> + <td><img alt="Example showing an address bar button (page action)" src="https://mdn.mozillademos.org/files/15047/address_bar_button.png" style="height: 127px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">Всплывающие окна</a></td> + <td>При нажатии на кнопку всплывает (popup) web-страница с органами управления.</td> + <td><img alt="Example of a popup on the address bar button" src="https://mdn.mozillademos.org/files/15053/page_action_popup.png" style="height: 250px; width: 330px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">Контекстное меню</a></td> + <td>Органы управления могут быть упорядочены в ветвящейся структуре контекстных меню браузера.</td> + <td><img alt="" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="height: 359px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">Боковая панель</a></td> + <td> + <p dir="ltr">В боковой панели рядом с интернет-сайтом открывается web-страница с интерфейсом пользователя. Человек может ее закрыть и открыть когда в ней появится потребность.</p> + </td> + <td><img alt="Example of a WebExtension's sidebar" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="height: 209px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">Страница настройки дополнения</a></td> + <td> + <p><span id="result_box" lang="ru"><span>Страница пользовательских настроек доступна из меню управления дополнениями единообразно </span></span>для всех расширений.</p> + </td> + <td><img alt="Example showing the options page content added in the favorite colors example." src="https://mdn.mozillademos.org/files/15055/options_page.png" style="height: 259px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">Дополнительные веб-страницы</a></td> + <td> + <p>Некоторые варианты содержимого (например, справку или форму обратной связи) удобнее расположить на дополнительной web-странице, которая открывается в собственной вкладке или окне.</p> + </td> + <td><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15063/bundled_page_as_panel_small.png" style="height: 180px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">Уведомления</a></td> + <td> + <p>Пользователю можно сообщить что-либо средствами уведомления, предусмотренными в ОС.<br> + Расширение отреагирует когда уведомление будет либо прочитано пользователем, либо скрыто (явным решением человека или логикой программы) так и оставшись непрочтённым.</p> + </td> + <td><img alt="Example notification from a WebExtension" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="height: 95px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">Угадывание адреса по мере ввода</a></td> + <td><span id="noHighlight_0.4753766294143369">Предлагать настраиваемые варианты адресной строки при вводе пользователем ключевого слова.</span></td> + <td><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15059/omnibox_example_small.png" style="height: 242px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">Панели инструмента разработчика</a></td> + <td><span id="result_box" lang="ru"><span>Вкладка со связанным HTML-документом, который отображается в инструментах разработчика браузера.</span></span></td> + <td><img alt="New panel tab in the Developer Tools tab bar" src="https://mdn.mozillademos.org/files/15049/developer_panel_tab.png" style="height: 180px; width: 350px;"></td> + </tr> + </tbody> +</table> + +<p><span id="noHighlight_0.852967693850544">В следующих руководствах приведены пошаговые инструкции по созданию некоторых из этих параметров пользовательского интерфейса:</span></p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">Add a button to the toolbar</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">Implement a settings page</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools</a></li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/notifications/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/notifications/index.html new file mode 100644 index 0000000000..4bb1099110 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/notifications/index.html @@ -0,0 +1,51 @@ +--- +title: Уведомления +slug: Mozilla/Add-ons/WebExtensions/user_interface/Notifications +tags: + - Web-расширение + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Notifications +--- +<div>{{AddonSidebar}}</div> + +<div> +<p><span class="seoSummary">Уведомления позволяют вам передавать информацию пользователям вашего расширения через службу уведомлений в операционной системе.</span></p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15754/notify-shadowed.png" style="display: block; height: 147px; margin-left: auto; margin-right: auto; width: 390px;"></p> + +<p>Уведомления могут включать в себя призывы к выполнению каких-либо действий, а ваше расширение может обрабатывать события закрытия или нажатия на уведомления.</p> + +<h2 id="Управление_уведомлениями">Управление уведомлениями</h2> + +<p>Управление уведомлениями происходит программным путём с помощью {{WebExtAPIRef("notifications")}} API. Для использования этого API вы должны иметь <code>notifications</code> полномочия в manifest.json:</p> + +<pre class="brush: json"><span class="pl-s"><span class="pl-pds">"</span>permissions<span class="pl-pds">"</span></span>: [<span class="pl-s"><span class="pl-pds">"</span>notifications<span class="pl-pds">"</span></span>]</pre> + +<p>После этого вы можете использовать {{WebExtAPIRef("notifications.create")}} для создания ваших уведомлений, как, например, в нижеприведённом коде, взятом из <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n:</a></p> + +<pre class="brush: js">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url); +browser.notifications.create({ + "type": "basic", + "iconUrl": browser.extension.getURL("icons/link-48.png"), + "title": title, + "message": content +});</pre> + +<p>Этот код создаёт уведомление с иконкой, заголовком и сообщением.</p> + +<p>Если уведомление имеет цель призвать пользователя к какому-либо действию, вы можете установить обработчик события на нажатия на уведомления:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>notifications<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span> +</code></pre> + +<p>Если вы собираетесь призывать пользователей к действиям с помощью уведомлений, вам так же будет полезно определять <code>id</code> этих уведомлений, для того чтобы вы в дальнейшем имели возможность различать на какое конкретно уведомление было произведено нажатие.</p> + +<h2 id="Иконки">Иконки</h2> + +<p>Смотрите статью <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> в документации <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> для получения информации по созданию иконок для уведомлений.</p> + +<h2 id="Примеры">Примеры</h2> + +<p>Репозиторий образцов расширений <a href="https://github.com/mdn/webextensions-examples">webextensions-examples </a>на GitHub включает в себя расширение <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a>, которое реализует систему уведомлений.</p> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/omnibox/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/omnibox/index.html new file mode 100644 index 0000000000..cb7285ba92 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/omnibox/index.html @@ -0,0 +1,68 @@ +--- +title: Адресная строка +slug: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox +tags: + - Web-расширение + - Расширение +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox +--- +<div>{{AddonSidebar()}}</div> + +<p>Используя {{WebExtAPIRef("omnibox")}} API, расширения могут взаимодействовать с адресной строкой и заполнять её выпадающий список предложений своими значениями, после введения пользователем определённого ключевого слова.</p> + +<p><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15749/omnibox_example_small.png" style="display: block; height: 232px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>Это могло бы позволить вам написать расширение, которое, например, искало бы бесплатные книги в электронной библиотеке, или как в примере выше, строки кода из репозитория.</p> + +<h2 id="Настраивание_взаимодействия_с_адресной_строкой">Настраивание взаимодействия с адресной строкой</h2> + +<p>Чтобы получить возможность взаимодействия с адресной строкой, вам необходимо добавить ключ <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox">omnibox</a> в <a href="https://developer.mozilla.org/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> файл, и присвоить ему значение в виде объекта, определяющего ключевое слово, после введения которого расширение активирует взаимодействие:</p> + +<pre class="brush: json line-numbers language-json"> "omnibox": { "keyword" : "cs" }</pre> + +<p>При желании, используя метод {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, вы можете изменить текст изначального предложения, которое всегда будет появляться первым в списке предложений адресной строки. Как вариант, оно может быть использовано для описания предоставляемого расширением функционала:</p> + +<pre class="brush: js line-numbers language-js">browser.omnibox.setDefaultSuggestion({ + description: `Искать в кодовой базе firefox + (пример: "hello world" | "path:omnibox.js onInputChanged")` +});</pre> + +<p>Далее, вы можете зарегистрировать обработчики на событие {{WebExtAPIRef("omnibox.onInputStarted")}}, которое будет распространяться после введения пользователем ключевого слова и нажатия на пробел, и на событие {{WebExtAPIRef("omnibox.onInputChanged")}}, которое будет распространяться при изменении пользователем строки адреса. Так же, с помощью обработчика события {{WebExtAPIRef("omnibox.onInputChanged")}}, вы будете иметь возможность заполнять выпадающий список своими предложениями. К примеру, в случае поиска кода на сайте https://searchfox.org/mozilla-central, используя введённые пользователем слова:</p> + +<pre class="brush: js">browser.omnibox.onInputChanged.addListener((text, addSuggestions) => { + let headers = new Headers({"Accept": "application/json"}); + let init = {method: 'GET', headers}; + let url = buildSearchURL(text); + let request = new Request(url, init); + + fetch(request) + .then(createSuggestionsFromResponse) + .then(addSuggestions); +});</pre> + +<p>Заметьте, что изначальное предложение в любом случае будет оставаться первым в выпадающем списке.</p> + +<p>Чтобы обрабатывать нажатия пользователя на предложения из выпадающего списка, подпишитесь на событие {{WebExtAPIRef("omnibox.onInputEntered")}}. При нажатии на изначальное предложение в функцию обработчика будет передана набранная в данный момент строка адреса, во всех остальных случаях будет передаваться значение из выбранного предложения. Вторым аргументом в функцию обработчика будет передана информация из настроек браузера о том, каким образом пользователь предпочитает открывать новые ссылки. Например, в нижерасположенном коде, нажатие на изначальное предложение запустит поиск, тогда как нажатие на все остальные предложения просто откроет определённые них URL:</p> + +<pre class="brush: js">browser.omnibox.onInputEntered.addListener((text, disposition) => { + let url = text; + if (!text.startsWith(SOURCE_URL)) { + // Обновить url, если пользователь нажал на изначальное предложение. + url = `${SEARCH_URL}?q=${text}`; + } + switch (disposition) { + case "currentTab": + browser.tabs.update({url}); + break; + case "newForegroundTab": + browser.tabs.create({url}); + break; + case "newBackgroundTab": + browser.tabs.create({url, active: false}); + break; + } +});</pre> + +<h2 id="Примеры">Примеры</h2> + +<p>Репозиторий образцов расширений <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> на GitHub включает в себя расширение <a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/firefox-code-search">firefox-code-search</a>, демонстрирующее взаимодействие с адресной строкой.</p> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/popups/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/popups/index.html new file mode 100644 index 0000000000..23541f5a60 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/popups/index.html @@ -0,0 +1,50 @@ +--- +title: Всплывающие окна +slug: Mozilla/Add-ons/WebExtensions/user_interface/Popups +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Popups +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>A popup is a dialog that's associated with a <a href="/en-US/Add-ons/WebExtensions/Browser_action">toolbar button</a> or <a href="/en-US/Add-ons/WebExtensions/Page_actions">address bar button</a>.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="display: block; height: 389px; margin-left: auto; margin-right: auto; width: 500px;"></p> + +<p>When the user clicks the button, the popup is shown. When the user clicks anywhere outside the popup, the popup is closed. The popup can be closed programmatically by calling <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/close">window.close()</a></code> from a script running in the popup. However, you can't open the popup programmatically from an extension's JavaScript: it can only be opened in response to a user action.</p> + +<p>You can define a keyboard shortcut that opens the popup using the <code>"_execute_browser_action"</code> and <code>"_execute_page_action"</code> shortcuts. See the documentation for the manifest.json key <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands">commands</a></code><span style="display: none;"> </span>.</p> + +<h2 id="Specifying_a_popup">Specifying a popup</h2> + +<p>The popup is specified as an HTML file, which can include CSS and JavaScript files, as a normal web page does. Unlike a normal page, though, the JavaScript can use all the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> that the extension has <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a> for.</p> + +<p>The HTML file is included in the extension and specified as part of the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> or <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> key by <code>"default_popup"</code> in the manifest.json:</p> + +<pre class="brush: json"> "browser_action": { + "default_icon": "icons/beasts-32.png", + "default_title": "Beastify", + "default_popup": "popup/choose_beast.html" + }</pre> + +<p>You can ask the browser to include a stylesheet in your popup that will make it look consistent with the browser's UI. To do this, include <code>"browser_style": true</code> in the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> or <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> key.</p> + +<p>Popups have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>. See <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> for more details on this.</p> + +<h2 id="Debugging_popups">Debugging popups</h2> + +<p>You can debug a popup's markup and JavaScript using the Add-on Debugger, but you'll need to turn on the Disable popup auto hide feature to prevent popups from hiding when you click outside them.<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging#Debugging_popups"> Read about debugging popups</a>.</p> + +<h2 id="Popup_resizing">Popup resizing</h2> + +<p>Popups resize automatically to fit their content. The algorithm for this may differ from one browser to another.</p> + +<p>In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the <code><a href="/en-US/docs/Web/HTML/Element/body"><body></a></code> element. For quirks mode, it's the <code><a href="/en-US/docs/Web/HTML/Element/html"><html></a></code> element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will grow to a size of <strong>800x600 pixels</strong> at most if that fits on the user's screen. If the user <a href="https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar">moves the extension's button to the menu</a> or it appears in the toolbar overflow, then the popup appears inside the menu's panel and is given a fixed width.</p> + +<h2 id="Examples">Examples</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo on GitHub, contains several examples of extensions that use a browser action:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> uses a browser action.</li> +</ul> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/user_interface/sidebars/index.html b/files/ru/mozilla/add-ons/webextensions/user_interface/sidebars/index.html new file mode 100644 index 0000000000..5a4f1e82f1 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/user_interface/sidebars/index.html @@ -0,0 +1,56 @@ +--- +title: Боковые панели (Sidebars) +slug: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +tags: + - Sidebar + - Боковая панель +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>Боковая панель - это панель, которая отображается в левой части окна браузера, рядом с веб-страницей. В браузере предусмотрен пользовательский интерфейс, который позволяет пользователю видеть доступные боковые панели и выбирать боковую панель для отображения. Например, Firefox имеет меню "Вид > Боковая панель". Одновременно может отображаться только одна боковая панель, и эта боковая панель будет отображаться для всех вкладок и всех окон браузера.</p> + +<p>Браузер может включать в себя ряд встроенных боковых панелей. Например, Firefox включает боковую панель для взаимодействия с закладками:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="display: block; height: 761px; margin-left: auto; margin-right: auto; width: 728px;">Используя ключ <code>sidebar_action</code> в manifest.json, расширение может добавить свою боковую панель в браузер. Она будет доступна наравне со встроенными панелями, и пользователь сможет открыть ее, используя тот же механизм, что и для встроенных боковых панелей.</p> + +<p>Как и в случае всплывающих окон (Popups), вы задаете содержимое боковой панели как документ HTML. Когда пользователь открывает боковую панель, этот документ загружается в каждое открытое окно браузера. Каждое окно получает свой экземпляр документа. Когда открываются новые окна, они также получат свои собственные экземпляры документа боковой панели.</p> + +<p>Вы можете задать HTML документ для конкретной вкладки, используя функцию {{WebExtAPIRef("sidebarAction.setPanel()")}}. Боковая панель может определить, к какому окну она принадлежит используя {{WebExtAPIRef("windows.getCurrent()")}} API:</p> + +<pre class="brush: js">// sidebar.js +browser.windows.getCurrent({populate: true}).then((windowInfo) => { + myWindowId = windowInfo.id; +});</pre> + +<p>Это полезно, если боковая панель хочет отображать различный контент для разных окон. Использование такого подхода см. в примере <a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">"annotate-page" example</a>.</p> + +<p>HTML документ боковай панели получает доступ к тому же набору привилегированных JavaScript API, что и background и popup сценарии этого расширения. Они могут получить прямой доступ к фоновой странице с помощью {{WebExtAPIRef("runtime.getBackgroundPage()")}}, и могут взаимодействовать с сценариями контента или нативными приложениями, используя API интерфейса обмена сообщениями, такие как {{WebExtAPIRef("tabs.sendMessage()")}} и {{WebExtAPIRef("runtime.sendNativeMessage()")}}.</p> + +<p>Документы боковой панели выгружаются, когда окно браузера закрывается или пользователь закрывает боковую панель. Это означает, что в отличие от background страниц документы боковой панели не остаются загруженными все время, но в отличие от popup окон они остаются загруженными, пока пользователь взаимодействует с веб-страницами.</p> + +<p>После первой установки расширения, использующего боковую панель, его панель будет открыта автоматически. Это сделано для того, чтобы помочь пользователю понять, что расширение использует боковую панель. Обратите внимание, что расширение не может открывать боковые панели программно: боковые панели могут открываться только пользователем.</p> + +<h2 id="Использование_боковых_панелей">Использование боковых панелей</h2> + +<p>Чтобы использовать боковую панель в своем расширении, укажите с помощью ключа <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code> в manifest.json key, HTML-документ панели, а также заголовок и значок по умолчанию:</p> + +<pre class="brush: json">"sidebar_action": { + "default_title": "My sidebar", + "default_panel": "sidebar.html", + "default_icon": "sidebar_icon.png" +}</pre> + +<p>Вы можете изменить название и значок панели программно, используя {{WebExtAPIRef("sidebarAction")}} API.</p> + +<p>Заголовок и значок отображаются пользователю в любом UI, предоставляемом браузером, для отображения боковых панелей, например меню "Вид > Боковые панели" в Firefox.</p> + +<h2 id="Примеры">Примеры</h2> + +<p>В репозитории <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> на GitHub содержится несколько примеров расширений, которые используют боковую панель:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">annotate-page</a> использует боковую панель.</li> +</ul> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/what_are_webextensions/index.html b/files/ru/mozilla/add-ons/webextensions/what_are_webextensions/index.html new file mode 100644 index 0000000000..ff947610ee --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/what_are_webextensions/index.html @@ -0,0 +1,95 @@ +--- +title: Что такое WebExtensions? +slug: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +tags: + - Extensions + - WebExtensions + - Дополнения + - Расширения +translation_of: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>Дополнения расширяют и изменяют функциональность браузера. Они разрабатываются с использованием стандартных Веб-технологий - JavaScript, HTML и CSS, а также некоторых специальных JavaScript API, которые позволяют вам делать намного больше, чем то, на что вы способны на любом из сайтов. Вот некоторые из примеров того, что вы можете делать:</p> +</div> + +<div> +<p><strong>Расширять или дополнять сайты</strong>: Используйте дополнения, чтобы предоставить информацию или дополнительные функции для браузера. Позвольте пользователям собирать информацию с посещённых ими страниц для улучшения предлагаемых вами услуг.</p> +</div> + +<div><img alt="Пример использования Amazon Assistant for Firefox" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15808/f81a8cc5b196af29cd9d558ee3c5dbdc/Amazon_add_on.png" style="height: 438px; width: 700px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/amazon-browser-bar/">Amazon Assistant for Firefox</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/onenote-clipper/">OneNote Web Clipper</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/grammarly-1/">Grammarly for Firefox</a>.</p> +</div> + +<div> +<p><strong>Дайте пользователям продемонстрировать себя</strong>: Дополнения могут управлять содержимым сайтов, например, позволять пользователям добавлять их любимые изображения как фоновые картинки для каждого сайта, которые они посещают. Ещё дополнения могут изменять и то, как выглядит сам интерфейс Firefox, делая это тем же способом, что и <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Themes/Theme_concepts">обычные темы</a>.</p> +</div> + +<div><img alt="Как расширение может изменить фоновую картинку сайта" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15809/ce69d140dc91da804ce6eb8f20d03c07/MyWeb_New_Tab_add_on.png" style="height: 398px; width: 540px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/myweb-new-tab/">MyWeb New Tab</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/tabliss/">Tabliss</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/vivaldifox/">VivaldiFox</a>.</p> +</div> + +<div> +<p><strong>Добавьте или скройте содержимое веб-страниц</strong>: Возможно, вы захотите помочь пользователям заблокировать назойливую рекламу, дать доступ к туристическоим путеводителям, когда на странице упоминается страна или город, или отформатировать содержимое страницы так, чтобы дать незабываемый опыт прочтения. С доступом к HTML и CSS дополнения могут помогать пользователям смотреть на Интернет так, как они хотят.</p> +</div> + +<div><img alt="Как работает uBlock Origin, популярный блокировщик рекламы" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15807/4e85eb0560fc8d5945e64cf75a1a8e50/ublock_origin_add_on.png" style="height: 480px; width: 640px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/ublock-origin/">uBlock Origin</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/reader/">Reader</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/toolbox-google-play-store/">Toolbox for Google Play Store™</a>.</p> +</div> + +<div> +<p><strong>Дайте новые инструменты и функции</strong>: Добавляйте новые пункты в список дел или генерируйте QR-коды для текста страницы или различных ссылок. При помощи гибких опций интерфейса и мощью WebExtensions API вы можете с лёгкостью добавлять новые функции в браузер. Причём вы можете расширить таким образом функциональность любого сайта, он не обязательно должен быть вашим.</p> +</div> + +<div><img alt="Как выглядит генератор QR-кодов QRUTILS.com" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15806/b9070a5f71c40c18d0a4ae722bca2e4a/QR_Code_Image_Generator_add_on.png" style="height: 512px; width: 700px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/swimlanes-for-trello/">Swimlanes for Trello</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/tomato-clock/">Tomato Clock</a>.</p> +</div> + +<div> +<p><strong>Игры</strong>: Давайте геймерам тот же опыт, что и в традиционных компьютерных играх - или же исследуйте новые игровые возможности, например, внедряя геймплей в ежедневный просмотр веб-страниц.</p> +</div> + +<div><img alt="Пример игры Asteroids in Popup" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15805/259d5d3c0620469521d43a897a7b653b/Asteroids_in_Popup_add_on%20.png" style="height: 438px; width: 700px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/asteroids-in-popup/">Asteroids in Popup</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/solitaire-card-game-new-tab/">Solitaire Card Game New Tab</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/2048-prime/">2048 Prime</a>.</p> +</div> + +<div> +<p><strong>Добавляйте инструменты для разработки</strong>: Вы можете предлагать инструменты разработки как часть вашего бизнеса, или же как то, что вы нового открыли для веб-разработки и чем хотите поделиться. Например, вы можете добавлять свои инструменты во встроенный набор инструментов разработчика Firefox.</p> +</div> + +<div><img alt="То, как интегрируется aXe в инструменты разработчика Firefox" src="https://media.prod.mdn.mozit.cloud/attachments/2018/02/13/15804/a2f3ed2cd857626d42352dd0de550486/aXe_Developer_Tools_add_on.png" style="height: 261px; width: 700px;"></div> + +<div> +<p>Примеры: <a href="https://addons.mozilla.org/en-US/firefox/addon/web-developer/">Web Developer</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/react-devtools/">Web React Developer Tools</a> и <a href="https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/">aXe Developer Tools</a>.</p> +</div> + +<div> +<p>WebExtensions - это кросс-браузерная система для разработки дополнений для браузера. В значительной степени ее API совместим с <a class="external external-icon" href="https://developer.chrome.com/extensions">extension API</a>, который поддерживается браузерами Google Chrome и Opera. Расширения, разработанные для этих браузеров, в большинстве случаев будут работать в Firefox или Microsoft Edge с минимальными изменениями. Также API полностью совместим с <a href="/ru/Firefox/Multiprocess_Firefox">мультипроцессным Firefox</a>.</p> +</div> + +<div> +<p>Мы также намерены расширять API для поддержки нужд разработчиков дополнений, и если у вас есть идеи, мы будем рады услышать их. Вы можете связаться с нами через рассылку <a class="external external-icon" href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons mailing list</a> или на <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a> канале <a href="irc://irc.mozilla.org/webextensions">#webextensions</a>.</p> +</div> + +<div> +<p>До появления WebExtensions разработка дополнения для Firefox осуществлялась одним из трех различных способов: <a href="/en-US/Add-ons/Overlay_Extensions">XUL/XPCOM overlays</a>, <a href="/en-US/docs/Mozilla/Add-ons/Bootstrapped_extensions">bootstrapped extensions</a> или <a href="/en-US/docs/Mozilla/Add-ons/SDK">Add-on SDK</a>. В будущем WebExtensions станет рекомендуемым способом разработки дополнений для Firefox, а остальные способы будут считаться устаревшими.</p> +</div> + +<h2 id="Что_дальше">Что дальше?</h2> + +<ul> + <li>Чтобы посмотреть примеры некоторых дополнений, см. <a href="/en-US/Add-ons/WebExtensions/Examples">Example WebExtensions</a>.</li> + <li>Чтобы узнать больше о структуре дополнений, см. <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">Anatomy of a WebExtension</a>.</li> + <li>Чтобы посмотреть пример разработки простого дополнения, см. <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">Ваш первый WebExtension</a>.</li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/your_first_webextension/index.html b/files/ru/mozilla/add-ons/webextensions/your_first_webextension/index.html new file mode 100644 index 0000000000..e9e4e74784 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/your_first_webextension/index.html @@ -0,0 +1,191 @@ +--- +title: Ваш первый WebExtension +slug: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +tags: + - Beginner + - Extensions + - Guide + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>В этой статье мы пройдем весь путь создания WebExtension для Firefox, от начала и до конца. Это дополнение будет просто добавлять красную рамку ко всем страницам, загруженным с "mozilla.org" или любого из его поддоменов.</p> + +<p>Исходный код этого дополнения доступен на GitHub: <a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">https://github.com/mdn/webextensions-examples/tree/master/borderify</a>.</p> + +<p>Для начала вам нужен Firefox 45 или более поздней версии.</p> + +<h2 id="Написание_WebExtension">Написание WebExtension</h2> + +<p>Создайте новую директорию (папку) и перейдите в нее:</p> + +<pre class="brush: bash">mkdir borderify +cd borderify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Теперь создайте новый файл, назовите его "manifest.json" в папке "borderify". Вставьте туда следующий код:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Borderify", + "version": "1.0", + + "description": "Adds a solid red border to all webpages matching mozilla.org.", + "icons": { + "48": "icons/border-48.png" + }, + + "applications": { + "gecko": { + "id": "borderify@mozilla.org", + "strict_min_version": "45.0" + } + }, + + "content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ] + +}</pre> + +<ul> + <li>Первые три ключа: <code><a href="/ru/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="/ru/Add-ons/WebExtensions/manifest.json/name">name</a> и <a href="/ru/Add-ons/WebExtensions/manifest.json/version">version</a></code>, являются обязательными и содержат основные метаданные о дополнении.</li> + <li><code><a href="/ru/Add-ons/WebExtensions/manifest.json/description">description</a></code> не обязателен, но рекомендуется: это описание отображается в Менеджере Дополнений.</li> + <li><code><a href="/ru/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> не обязателен, но рекомендуется: позволяет указать значок для дополнения, который будет виден в Менеджере Дополнений.</li> + <li><code><a href="/ru/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> <span id="result_box" lang="ru"><span>является обязательным для</span> <span>Firefox</span><span>,</span> <span>и</span> <span>определяет</span></span> ID дополнения. Он так же может использоваться для указания минимальной и максимальной версии Firefox, поддерживаемой расширением.</li> +</ul> + +<p>Самый интересный ключ здесь - это <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code>, который говорит Firefox загружать скрипт на Web страницах, чей URL совпадает с заданным шаблоном. В нашем случае, мы просим Firefox загрузить скрипт с названием "borderify.js" на всех HTTP или HTTPS страницах, полученных с "mozilla.org" или любого из его поддоменов.</p> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/Content_scripts">Узнать больше content scripts.</a></li> + <li><a href="/ru/Add-ons/WebExtensions/Match_patterns">Узнать больше о match patterns</a>.</li> +</ul> + +<div class="warning"> +<p><a href="/ru/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_Add-on_ID">В некоторых случаях вам нужно указать ID для вашего дополнения</a>. Если вам нужно указать ID дополнения включите ключ <code><a href="/ru/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> в <code>manifest.json</code> и установите его свойство <code>gecko.id</code>:</p> + +<pre class="brush: json">"applications": { + "gecko": { + "id": "borderify@example.com" + } +}</pre> +</div> + +<h3 id="iconsborder-48.png">icons/border-48.png</h3> + +<p>Дополнение должно иметь иконку (значок). Эта иконка будет показана в списке дополнений в Менеджере Дополнений. Наш файл manifest.json сообщает, что иконка будет находиться в файле "icons/border-48.png".</p> + +<p>Создайте директорию (папку) "icons" внутри директории "borderify" . Сохраните в ней иконку под именем "border-48.png". Вы можете использовать <a href="https://github.com/mdn/webextensions-examples/blob/master/borderify/icons/border-48.png">иконку из нашего примера</a>, которая взята из набора иконок Google Material Design, и используется по лицензии <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike</a>.</p> + +<p>Вы можете использовать собственную иконку. Её размер должен быть 48x48 пикселей. Вы можете также использовать иконку размером 96x96 пикселей для отображения на мониторах высокого разрешения. В этом случае Вам необходимо указать её в качестве свойства "96" объекта "<code>icons"</code> в файле manifest.json:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/border-48.png", + "96": "icons/border-96.png"</span> +<span class="punctuation token">}</span></code></pre> + +<p>Также Вы можете создать иконку в формате SVG и она будет корректно масштабироваться.</p> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/manifest.json/icons">Узнать больше о ключе icons</a></li> +</ul> + +<h3 id="borderify.js">borderify.js</h3> + +<p>Наконец, создайте в директории "borderify" файл с именем "borderify.js" и поместите туда следующий код:</p> + +<pre class="brush: js">document.body.style.border = "5px solid red";</pre> + +<p>Этот скрипт будет встраиваться в страницу, которая совпадает с шаблоном, указанном в ключе <code>content_scripts</code> файла manifest.json. Этот скрипт имеет прямой доступ ко всему документу, как если бы он был загружен самой страницей.</p> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/Content_scripts">Узнать больше о content scripts</a></li> +</ul> + +<h2 id="Пробуем">Пробуем</h2> + +<p>Сначала внимательно проверьте, что Вы правильно разместили файлы и дали им правильные имена:</p> + +<pre>borderify/ + icons/ + border-48.png + borderify.js + manifest.json</pre> + +<h3 id="Установка">Установка</h3> + +<p>Начиная с версии Firefox 45 Вы можете временно установить WebExtension с локального диска.</p> + +<p>Откройте страницу "about:debugging", кликните "Load Temporary Add-on" и выберите файл manifest.json:</p> + +<p>{{EmbedYouTube("SKb-CNYpl6Q")}}</p> + +<p>Теперь ваше дополнение установлено и останется в браузере до его перезапуска.</p> + +<p>Для проверки, зайдите на страницу "about:addons" чтобы открыть Менеджер Дополнений. Вы должны увидеть своё дополнение с именем и иконкой:</p> + +<p>{{EmbedYouTube("WpUL3-qmenE")}}</p> + +<p>Также, Вы можете запускать WebExtension из командной строки, используя <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a>.</p> + +<h3 id="Тестирование">Тестирование</h3> + +<p>Теперь зайдите на любую страницу домена "mozilla.org" и вы должны будете увидеть красную границу вокруг страницы:</p> + +<p>{{EmbedYouTube("exUAH0sIyBw")}}</p> + +<p>Поэкспериментируйте немного. Поменяйте цвет границы или сделайте ещё что-нибудь с содержимым на странице. После того, как изменённый скрипт будет сохранён, а страница перезагружена, вы сразу увидите изменения:</p> + +<p>{{EmbedYouTube("t6s_4yF8dRk")}}</p> + +<div class="note"> +<p>Обратите внимание, что после изменения файла manifest.json, вы должны вручную перезагрузить своё дополнение. В настоящий момент это значит, что вам нужно перезагрузить Firefox, а затем снова загрузить своё дополнение на странице "about:debugging". Мы работаем над улучшением этого процесса. </p> +</div> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/Packaging_and_installation#Loading_from_disk">Узнать больше о временной установке дополнений</a></li> +</ul> + +<h2 id="Упаковка_и_публикация">Упаковка и публикация</h2> + +<div class="hidden"> +<p>Оригинальная статья ссылается на отдельную статью. Убрать параграф туда?</p> +</div> + +<p>Чтобы другие люди могли использовать ваше дополнение, вам необходимо запаковать его. Дополнения Firefox в запакованном виде являются XPI файлами, которые представляют собой обычные ZIP архивы с расширением "xpi".</p> + +<p>При упаковке необходимо учитывать следующее: в ZIP архиве должны быть только файлы, а не содержащая их директория (директория "borderify" не должна попасть в архив). Для того, чтобы создать правильный XPI файл из вашего дополнения, в командной строке перейдите в директорию "borderify" и выполните следующую команду:</p> + +<p><code class="language-bash">zip -r ../borderify.xpi *</code></p> + +<p>Начиная с Firefox 43 все дополнения должны быть подписаны прежде чем они будут установлены в браузер. Вы можете снять это ограничение <em>только</em> в <a class="external external-icon" href="https://www.mozilla.org/en-US/firefox/developer/">Firefox Developer Edition</a> или <a class="text external external-icon" href="https://nightly.mozilla.org/" rel="nofollow">Firefox Nightly</a> при помощи следующих шагов: </p> + +<ul> + <li>перейдите на страницу <code>about:config</code> в Firefox</li> + <li>при помощи строки поиска найдите <code>xpinstall.signatures.required</code></li> + <li>дважды кликнув на этом свойстве или при помощи локального меню (через клик правой кнопкой мыши), выберите "Toggle", чтобы установить значение <code>false</code>.</li> +</ul> + +<p>{{EmbedYouTube("HgtBYDWtH4w")}}</p> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/Packaging_and_installation">Узнать больше об упаковке и инсталляции</a></li> + <li><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension">Узнать больше о подписи и распространении</a></li> +</ul> + +<h2 id="Что_дальше">Что дальше?</h2> + +<p>Теперь, когда вы имеете представление о разработке дополнений для Firefox, вы можете:</p> + +<ul> + <li><a href="/ru/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">Прочитать больше об анатомии WebExtensions</a></li> + <li><a href="/ru/Add-ons/WebExtensions/Your_second_WebExtension">Создать более сложное WebExtensions</a></li> + <li><a href="/ru/Add-ons/WebExtensions/API">Прочитать больше об API JavaScript, доступном для WebExtensions</a></li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/your_second_webextension/index.html b/files/ru/mozilla/add-ons/webextensions/your_second_webextension/index.html new file mode 100644 index 0000000000..db8eec8f90 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/your_second_webextension/index.html @@ -0,0 +1,363 @@ +--- +title: Ваш второй WebExtension +slug: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +tags: + - Beginner + - Example + - Guide + - WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +--- +<div>{{AddonSidebar}} +<p>Если Вы уже прочитали статью <a dir="ltr" href="/ru/Add-ons/WebExtensions/Your_first_WebExtension" lang="ru-ru">Ваш первый WebExtension</a>, то уже представляете, как создавать WebExtension. В этой статье мы напишем более сложное дополнение, которое демонстрирует еще несколько API.</p> + +<p>Дополнение добавляет новую кнопку на панель инструментов Firefox. Когда пользователь кликает по кнопке, мы показываем ему всплывающую панель с предложением выбрать животное. Когда животное выбрано, мы заменяем содержимое текущей страницы на изображение выбранного животного.</p> + +<p>Чтобы реализовать это, мы:</p> + +<ul> + <li><strong>определим <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/Browser_action">browser action</a> - кнопку, прикрепленную к панели инструментов Firefox.</strong><br> + Для кнопки мы предоставим: + <ul> + <li>иконку с именем "beasts-32.png"</li> + <li>всплывающую панель, если кнопка нажата. Панель состоит из HTML, CSS, и JavaScript.</li> + </ul> + </li> + <li><strong>определим иконку для дополнения</strong> с именем "beasts-48.png". Иконка будет показана в Менеджере дополнений.</li> + <li><strong>напишем сценарий содержимого(content script) "beastify.js", который будет встроен в веб-страницы</strong>.<br> + Это тот код, который и будет изменять страницы.</li> + <li><strong>упакуем несколько изображений животных для замены изображений на веб-странице</strong>.<br> + Мы сделаем изображения "доступными веб-ресурсами"(web accessible resources), чтобы веб-страница могла ссылаться на них.</li> +</ul> + +<p>Вы можете представить общую структуру дополнения вот так:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13671/Untitled-1.png" style="display: block; height: 1200px; margin-left: auto; margin-right: auto; width: 860px;"></p> + +<p>Это простое дополнение, но показывает множество основных концепций WebExtensions API:</p> + +<ul> + <li>добавление кнопки на панель инструментов</li> + <li>определение всплывающей панели используя HTML, CSS, и JavaScript</li> + <li>встраивание контент-скрипта в веб-страницы</li> + <li>взаимодействие между сценарием содержимого и остальным дополнением</li> + <li>упаковка ресурсов с Вашим дополнением, которые будут использованы веб-страницами</li> +</ul> + +<p>Вы можете найти <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">полный исходный код дополнения на GitHub</a>.</p> + +<p>Чтобы написать это дополнение, Вам нужен Firefox 45 или новее.</p> + +<h2 id="Написание_WebExtension">Написание WebExtension</h2> + +<p>Создайте новую директорию и перейдите в нее:</p> + +<pre class="brush: bash">mkdir beastify +cd beastify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Теперь создайте файл "manifest.json" и вставьте в него следующее содержимое:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Beastify", + "version": "1.0", + + "description": "Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. See https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#beastify", + "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/beastify", + "icons": { + "48": "icons/beasts-48.png" + }, + + "permissions": [ + "activeTab" + ], + + "browser_action": { + "default_icon": "icons/beasts-32.png", + "default_title": "Beastify", + "default_popup": "popup/choose_beast.html" + }, + + "web_accessible_resources": [ + "beasts/frog.jpg", + "beasts/turtle.jpg", + "beasts/snake.jpg" + ] + +} +</pre> + +<ul> + <li>Первые три ключа: <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name">name</a></code>, <code>и <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version">version</a></code>, являются обязательными и содержат основные мета-данные для дополнения.</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description">description</a></code> <code>и <a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url</a></code> необязательны, но рекомендуемы: они предоставляют полезную информацию о дополнении.</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> необязательный, но рекомендуемый: позволяет Вам определять иконку для дополнения, которая будет показана в Менеджере Дополнений.</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> перечисляет разрешения для нужд дополнения. Здесь мы просто спрашиваем разрешения для <a href="/ru/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>activeTab</code> permission</a>.</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> задает кнопку на панели инструментов. Здесь мы предоставляем три вида информации: + <ul> + <li><code>default_icon</code> это обязательная иконка для кнопки</li> + <li><code>default_title</code> необязательный заголовок, будет показан в подсказке</li> + <li><code>default_popup</code> используется, если Вы хотите, чтобы всплывающая панель была показана когда пользователь кликает по кнопке. В нашем примере мы использовали этот ключ и он указывает на HTML файл, подключенный к дополнению.</li> + </ul> + </li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code> перечисляет файлы, которые мы хотим сделать доступными для веб-страниц. Поскольку дополнение заменяет содержимое страницы на изображения, которые мы упаковали вместе с дополнением, нам нужно сделать эти изображения доступными для страницы.</li> +</ul> + +<p>Обратите внимание, что все пути указаны относительно файла manifest.json.</p> + +<h3 id="Иконка">Иконка</h3> + +<p>Дополнение должно иметь иконку. Она будет показана рядом с дополнением в Менеджере Дополнений (Вы можете открыть менеджер перейдя по ссылке "about:addons"). Наш manifest.json обещает, что у нас будет иконка для панели инструментов по адресу "icons/beasts-48.png".</p> + +<p>Создайте папку "icons" и сохраните там иконку с именем "beasts-48.png". Вы можете использовать <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-48.png">иконку из нашего примера</a>, которая взята из <a href="https://www.iconfinder.com/iconsets/free-retina-icon-set">набора Aha-Soft’s Free Retina</a> и используется на условиях этой <a href="http://www.aha-soft.com/free-icons/free-retina-icon-set/">лицензии</a>.</p> + +<p>Если Вы выберете свою иконку, она должна быть размером 48x48 пикселей. Вы также можете предоставить иконку размером 96x96 пикселей для дисплеев с высоким разрешением, определив свойство <code>"96"</code> объекта <code>icons</code> в файле manifest.json:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/beasts-48.png"</span><span class="punctuation token">,</span> + <span class="key token">"96":</span> <span class="string token">"icons/beasts-96.png"</span> +<span class="punctuation token">}</span></code></pre> + +<h3 id="Кнопка_панели_инструментов">Кнопка панели инструментов</h3> + +<p>Кнопка панели инструментов также нуждается в иконке, и наш manifest.json обещает, что у нас будет иконка для панели инструментов по адресу "icons/beasts-32.png".</p> + +<p>Сохраните иконку с именем "beasts-32.png" в папке "icons". Вы можете использовать <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png">иконку из нашего примера</a>, которая взята из набора <a href="http://www.iconbeast.com/free">IconBeast Lite </a>и используется на условиях этой <a href="http://www.iconbeast.com/faq/">лицензии</a>.</p> + +<p>Если Вы не предоставите всплывающую панель, то событие click отправляется в Ваше дополнение, когда пользователь кликает кнопку. Если Вы предоставите всплывающую панель, то событие click не отправляется, зато появляется всплывающая панель. Мы хотим панель, давайте создадим ее.</p> + +<h3 id="Всплывающая_панель">Всплывающая панель</h3> + +<p>Функция панели - позволить пользователю выбрать одного из трех зверей.</p> + +<p>Создайте новую папку с именем "popup" в корневой папке дополнения. Здесь мы сохраним код для панели. Панель будет состоять из трех файлов:</p> + +<ul> + <li><strong><code>choose_beast.html</code></strong> определяет содержимое панели</li> + <li><strong><code>choose_beast.css</code></strong> стили для содержимого</li> + <li><strong><code>choose_beast.js</code></strong> обрабатывает выбор пользователя, выполняя content script в активной вкладке</li> +</ul> + +<h4 id="choose_beast.html">choose_beast.html</h4> + +<p>HTML выглядит так:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_beast.css"/> + </head> + + <body> + <div class="button beast">Frog</div> + <div class="button beast">Turtle</div> + <div class="button beast">Snake</div> + <div class="button clear">Reset</div> + + <script src="choose_beast.js"></script> + </body> + +</html></pre> + +<p>У нас есть элемент для каждого животного. Обратите внимание, что мы подключаем CSS и JS файлы из HTML файла, как на обыкновенной веб-странице.</p> + +<h4 id="choose_beast.css">choose_beast.css</h4> + +<p>CSS фиксирует размер всплывающей панели, гарантирует что три варианта заполняют пространство и дает им основной стиль:</p> + +<pre class="brush: css">html, body { + width: 100px; +} + +.button { + margin: 3% auto; + padding: 4px; + text-align: center; + font-size: 1.5em; + cursor: pointer; +} + +.beast:hover { + background-color: #CFF2F2; +} + +.beast { + background-color: #E5F2F2; +} + +.clear { + background-color: #FBFBC9; +} + +.clear:hover { + background-color: #EAEAC9; +} +</pre> + +<h4 id="choose_beast.js">choose_beast.js</h4> + +<p>В JavaScript для всплывающего окна мы слушаем click события. Если click был на одном из трех вариантов наших животных, мы добавляем content script в активную вкладку. После того, как content script загрузится, мы отправляем ему сообщение с выбранным животным:</p> + +<pre class="brush: js">/* +Учитывая имя зверя, получаем URL соответствующего изображения. +*/ +function beastNameToURL(beastName) { + switch (beastName) { + case "Frog": + return browser.extension.getURL("beasts/frog.jpg"); + case "Snake": + return browser.extension.getURL("beasts/snake.jpg"); + case "Turtle": + return browser.extension.getURL("beasts/turtle.jpg"); + } +} + +/* +Слушаем события клика во всплывающей панели. + +Если кликнули одного из зверей: + Добавляем "beastify.js" к активной вкладке. + + Затем получаем активную вкладку и отправляем сценарию "beastify.js" + сообщение, содержащее URL к картинке с выбранным зверем. + +Если кликнули кнопку, класс которой содержит "clear": + Перезагрузить страницу. + Закрыть всплывающую панель. Это необходимо, так как content script + неисправен после перезагрузки страницы. +*/ + +document.addEventListener("click", (e) => { + if (e.target.classList.contains("beast")) { + var chosenBeast = e.target.textContent; + var chosenBeastURL = beastNameToURL(chosenBeast); + + browser.tabs.executeScript(null, { + file: "/content_scripts/beastify.js" + }); + + var gettingActiveTab = browser.tabs.query({active: true, currentWindow: true}); + gettingActiveTab.then((tabs) => { + browser.tabs.sendMessage(tabs[0].id, {beastURL: chosenBeastURL}); + }); + } + else if (e.target.classList.contains("clear")) { + browser.tabs.reload(); + window.close(); + } +}); +</pre> + +<p>Скрипт использует три функции WebExtension API:</p> + +<ul> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript</a></code> добавляет content script, найденный по адресу content_scripts/beastify.js", к активной вкладке</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">browser.tabs.query</a></code> запрашивает активную вкладку</li> + <li><code><a href="/ru/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">browser.tabs.sendMessage</a></code> отправляет сообщение для content script, который работает в активной вкладке. Сообщение содержит URL изображения выбранного зверя.</li> +</ul> + +<h3 id="Сontent_script">Сontent script</h3> + +<p>Создайте новую папку с именем "content_scripts" в корневой папке дополнения и создайте в ней новый файл с именем "beastify.js", со следующим кодом:</p> + +<pre class="brush: js">/* +beastify(): +* удаляет каждый узел в document.body, +* затем вставляет выбранного зверя +* затем удаляется как слушатель +*/ +function beastify(request, sender, sendResponse) { + removeEverything(); + insertBeast(request.beastURL); + browser.runtime.onMessage.removeListener(beastify); +} + +/* +Удаляет каждый узел в document.body +*/ +function removeEverything() { + while (document.body.firstChild) { + document.body.firstChild.remove(); + } +} + +/* +Учитывая URL изображения зверя, создает и стилизует узел IMG, +указывающий на это изображение, затем вставляет узел в документ. +*/ +function insertBeast(beastURL) { + var beastImage = document.createElement("img"); + beastImage.setAttribute("src", beastURL); + beastImage.setAttribute("style", "width: 100vw"); + beastImage.setAttribute("style", "height: 100vh"); + document.body.appendChild(beastImage); +} + +/* +Назначает beastify() слушателем сообщений расширения. +*/ +browser.runtime.onMessage.addListener(beastify); +</pre> + +<p>Content script добавляет слушателя к сообщениям от дополнения (в частности как в файле "choose_beast.js" выше). В слушателе скрипт:</p> + +<ul> + <li>удаляет каждый элемент из <code>document.body</code></li> + <li>создает <code><img></code> элемент, указывающий на переданный URL, и вставляет элемент в DOM</li> + <li>удаляет слушатель сообщений.</li> +</ul> + +<h3 id="Звери">Звери</h3> + +<p>Наконец, нам нужно подключить изображения животных.</p> + +<p>Создайте новую папку с именем "beasts" и добавьте туда три изображения с соответствующими именами. Вы можете получить изображения из <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts">GitHub репозитория</a>, или прямо здесь:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11459/frog.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11461/snake.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11463/turtle.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"></p> + +<h2 id="Тестирование">Тестирование</h2> + +<p>Во-первых, дважды проверьте, что у вас все файлы на своих местах:</p> + +<pre>beastify/ + + beasts/ + frog.jpg + snake.jpg + turtle.jpg + + content_scripts/ + beastify.js + + icons/ + beasts-32.png + beasts-48.png + + popup/ + choose_beast.css + choose_beast.html + choose_beast.js + + manifest.json</pre> + +<p>Начиная с Firefox 45 Вы можете временно установить дополнения с жесткого диска.</p> + +<p>Откройте "about:debugging" в Firefox, кликните "Загрузить временное дополнение", и выберете Ваш файл manifest.json. После этого Вы должны увидеть иконку дополнения на панели инструментов Firefox:</p> + +<p>{{EmbedYouTube("sAM78GU4P34")}}</p> + +<p>Откройте веб-страницу, затем щелкните иконку, выберите зверя и посмотрите как страница изменится:</p> + +<p>{{EmbedYouTube("YMQXyAQSiE8")}}</p> + +<h2 id="Разработка_из_командной_строки">Разработка из командной строки</h2> + +<p>Вы можете автоматизировать этап временной установки используя <a href="/ru/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a>. Попробуйте это:</p> + +<pre class="brush: bash">cd beastify +web-ext run</pre> +</div> diff --git a/files/ru/mozilla/add-ons/webextensions/интернационализация/index.html b/files/ru/mozilla/add-ons/webextensions/интернационализация/index.html new file mode 100644 index 0000000000..36a37820d9 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/интернационализация/index.html @@ -0,0 +1,405 @@ +--- +title: Интернационализация +slug: Mozilla/Add-ons/WebExtensions/Интернационализация +translation_of: Mozilla/Add-ons/WebExtensions/Internationalization +--- +<div>{{AddonSidebar}}</div> + +<p>API <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> предоставляет полезный модуль для интернационализации расширений — <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a>. В этой статье мы рассмотрим его особенности и пример его работы. Система для расширений, построенных с помощью API WebExtension, i18n похожа на библиотеки JavaScript для i18n, такие как <a href="http://i18njs.com/">i18n.js</a>.</p> + +<div class="note"> +<p>Расширение, используемое в этой статье в качестве примера, — <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> — доступно на GitHub. Читая последующие секции этой статьи, Вы можете исследовать его исходный код.</p> +</div> + +<h2 id="Структура_интернализированного_расширения">Структура интернализированного расширения</h2> + +<p>Интернационализированное расширение может содержать такие же элементы, как и любое другое расширение — <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">фоновые скрипты</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">встраиваемые скрипты</a>, и т. д. — а также дополнительные инструмены, позволяющие переключаться между разными локализациями. Их можно представить следующим деревом директорий:</p> + +<ul class="directory-tree"> + <li>корневая-директория-расширения/ + <ul> + <li>_locales + <ul> + <li>en + <ul> + <li>messages.json + <ul> + <li>Сообщения на английском (строки)</li> + </ul> + </li> + </ul> + </li> + <li>de + <ul> + <li>messages.json + <ul> + <li>Сообщения на немецком (строки)</li> + </ul> + </li> + </ul> + </li> + <li>и т. д.</li> + </ul> + </li> + <li>manifest.json + <ul> + <li>Метаданные, зависящие от локализации</li> + </ul> + </li> + <li>myJavascript.js + <ul> + <li>Файл JavaScript, получающий локализацию браузера, сообщения, зависящие от локализации, и т. д.</li> + </ul> + </li> + <li>myStyles.css + <ul> + <li>CSS, зависящий от локализации</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Давайте отдельно рассмотрим каждый элемент — последующие секции представляют собой шаги, которым стоит следовать во время интернационализации вашего расширения.</p> + +<h2 id="Добавление_локализованных_строк_в__locales">Добавление локализованных строк в _locales</h2> + +<div class="pull-aside"> +<div class="moreinfo">Вы можете определить тэг языка при помощи инструмента <em>Find</em> на <a href="https://r12a.github.io/app-subtags/">странице определения языковых тегов</a>. Обратите внимание на то, что при поиске еужно использовать английское название языка</div> +</div> + +<p>Каждая система i18n требует предоставить строки во всех локализациях, которые Вы хотите поддерживать. В расширениях они хранятся в директории <code>_locales</code>, размещенной внутри корневой директории. Строки каждой локализации (также называемые сообщениями) хранятся в файле <code>messages.json</code>, находящемся в поддиректории <code>_locales</code>, название которой - тег языка локализации.</p> + +<p>Стоит заметить, что если тег включает в себя и базовый язык, и его региональный вариант, то по конвенции эти язык и вариант разделяются дефисом: например, "en-US". Однако в поддиректориях <code>_locales</code>, <strong>вместо дефиса используется нижнее подчеркивание</strong>: "en_US".</p> + +<p>Таким образом, <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n/_locales">в нашем примере</a> существую директории "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Внутри каждой из них находится файл <code>messages.json</code> .</p> + +<p>Давайте рассмотрим структуру одного из этих файлов (<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/_locales/en/messages.json">_locales/en/messages.json</a>):</p> + +<pre class="brush: json notranslate">{ + "extensionName": { + "message": "Notify link clicks i18n", + "description": "Name of the extension." + }, + + "extensionDescription": { + "message": "Shows a notification when the user clicks on links.", + "description": "Description of the extension." + }, + + "notificationTitle": { + "message": "Click notification", + "description": "Title of the click notification." + }, + + "notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } + } +}</pre> + +<p>Это стандартный файл JSON — каждый из его элементов является объектом с именем, содержащим сообщение (<code>message)</code> и описание (<code>description)</code>. Оба предмета - строки; <code>$URL$</code> — это заполнитель, который заменяется подстрокой, когда элемент <code>notificationContent</code> вызывается расширением. Вы научитесь это делать в секции {{anch("Получение сообщений из JavaScript")}}.</p> + +<div class="note"> +<p><strong>Примечание</strong>: Вы можете найти больше информации о структуре <code>messages.json</code> <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">здесь</a>.</p> +</div> + +<h2 id="Интернационализация_manifest.json">Интернационализация manifest.json</h2> + +<p>Для интернационализации файла manifest.json нужно предпринять несколько шагов.</p> + +<h3 id="Получение_локализованных_строк_в_манифестах">Получение локализованных строк в манифестах</h3> + +<p>Ваш файл <a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/manifest.json">manifest.json</a> содержит строки, отображаемые пользователю, такие как имя и описание расширения. Если Вы интернационализируете эти строки и поместите их переводы в messages.json, то эти переводы будут отображаться пользователю в зависимости от локализации его браузера.</p> + +<p>Чтобы интернационализировать строки, их нужно указывать следующим образом:</p> + +<pre class="brush: json notranslate">"name": "__MSG_extensionName__", +"description": "__MSG_extensionDescription__",</pre> + +<p>Здесь мы получаем сообщения, зависящие от локализации браузера, а не просто статические строки.</p> + +<p>Чтобы получить строку сообщения, ее нужно указать следующим образом:</p> + +<ol> + <li>Два подчеркивания</li> + <li>Строка "MSG"</li> + <li>Одно подчеркивание</li> + <li>Имя сообщения так как оно указано в <code>messages.json</code></li> + <li>Два подчеркивания</li> +</ol> + +<pre class="notranslate"><strong>__MSG_</strong> + <em>messageName</em> + <strong>__</strong></pre> + +<h3 id="Локализация_по_умолчанию">Локализация по умолчанию</h3> + +<p>Еше одно поле. которое нужно указать в manifest.json — это <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a>:</p> + +<pre class="brush: json notranslate">"default_locale": "en"</pre> + +<p>Этот параметр устанавливает локализацию по умолчанию, используемую, если расширение не поддерживает локализацию браузера пользователя. Любые сообщения, недоступные в текущей локализации, будут браться из той локализации, которая установлена по умолчанию. There are some more details to be aware of in terms of how the browser selects strings — see {{anch("Выбор локализованной строки")}}.</p> + +<h2 id="CSS_зависящий_от_локализации">CSS, зависящий от локализации</h2> + +<p>Локализованные строки также можно получить из CSS-файлов расширения. Например, Вы можете создать поля CSS, зависящие от локализации, так:</p> + +<pre class="brush: css notranslate">header { + background-image: url(../images/__MSG_extensionName__/header.png); +}</pre> + +<p>Этот функционал может быть полезен, однако, возможно, для этих целей стоит использовать {{anch("Заранее определенные сообщения")}}.</p> + +<h2 id="Получение_сообщений_из_JavaScript">Получение сообщений из JavaScript</h2> + +<p>Допустим, Вы добавили сообщения в Ваш manifest.json. Чтобы Ваше расширение начало использовать правильные языки, соответствующие сообщения следует вызывать при помощи JavaScript. <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">API i18n</a> достаточно прост и содержит всего 4 основных метода:</p> + +<ul> + <li>Скорее всего, наиболее часто Вы будете использовать {{WebExtAPIRef("i18n.getMessage()")}} — этот сетод используется для получения конкретного сообщения. Примеры его использования можно увидеть ниже.</li> + <li>Методы {{WebExtAPIRef("i18n.getAcceptLanguages()")}} и {{WebExtAPIRef("i18n.getUILanguage()")}} используются, если UI надо менять в зависимости от локализации — например, если Вы хотите, чтобы предпочтения, свойственные носителям какого-либо языка, находились выше в списке, или чтобы формат дат соответствовал локализации браузера.</li> + <li>Метод {{WebExtAPIRef("i18n.detectLanguage()")}} используется для получения языка информации, введенной пользователем, и ее форматирования.</li> +</ul> + +<p>В нашем примере <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> , <a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/background-script.js">фоновый скрипт</a> содержит следующие строки:</p> + +<pre class="brush: js notranslate">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url);</pre> + +<p>Первая из них получает поле <code>notificationTitle message</code> из доступного файла <code>messages.json</code>, соответствующее наиболее подходящей локализации . Вторая строка похожа на первую, но в ней метод принимает URL в качестве второго параметра. Зачем? С помощью этого параметра мы указываем, на что нужно заменить заполнитель <code>$URL$</code> в поле <code>notificationContent message</code>:</p> + +<pre class="brush: json notranslate">"notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } +} +</pre> + +<p>Объект <code>"placeholders"</code> определяет все заполнители и то, откуда их нужно получать. Заполнитель <code>"url"</code> указывает, что информация о нем должна содержаться в $1 — первое значение, заданное внутри второго параметра <code>getMessage()</code>. Поскольку заролнитель называется <code>"url"</code>, <code>$URL$</code> используется для его вызова внутри сообщения (то есть для заполнителя <code>"name"</code> нужно использовать <code>$NAME$</code>, и т. д.). Если Вы хотите задать значения нескольких заполнителей, их можно передавать во второй аргумент {{WebExtAPIRef("i18n.getMessage()")}} в виде массива — массив <code>[a, b, c]</code> передает значения <code>$1</code>, <code>$2</code> и <code>$3</code>, и т. д. внутрь <code>messages.json</code>.</p> + +<p>Давайте посмотрим на пример: изначально сообщение <code>notificationContent</code> в файле <code>en/messages.json</code> такое:</p> + +<pre class="notranslate">You clicked $URL$.</pre> + +<p>Пусть эта ссылка указывает на <code>https://developer.mozilla.org</code>. После вызова {{WebExtAPIRef("i18n.getMessage()")}}, содержание второго параметра становится доступно в messages.json в качестве значения <code>$1</code>, замещающего <code>$URL$</code>, так как это указано в заполнителе <code>"url"</code>. Таким образом, итоговое значение строки:</p> + +<pre class="notranslate">You clicked https://developer.mozilla.org.</pre> + +<h3 id="Прямое_использование_заполнителей">Прямое использование заполнителей</h3> + +<p>Переменные (<code>$1</code>, <code>$2</code>, <code>$3</code>, и т. д.) можно вставлять напрямую в сообщения. Например, можно переписать объект <code>"notificationContent"</code> следующим образом:</p> + +<pre class="brush: json notranslate">"notificationContent": { + "message": "You clicked $1.", + "description": "Tells the user which link they clicked." +}</pre> + +<p>Этот метод может показаться более быстрым и простым, но другой способ (использование <code>"placeholders"</code>) считается лучшей практикой. Это вызвано тем, что имена заполнителей (например <code>"url"</code>) и примеры помогают понять, что означают заполнители — через неделю после написания кода Вы, наверное, забудете, что обозначают заполнители <code>$1</code>–<code>$8</code>, что менее вероятно, если заполнители именованы.</p> + +<h3 id="Заданные_замены">Заданные замены</h3> + +<p>Значения заполнителей можно задавать вручную, если Вы хотите, чтобы каждый раз это значение было одним и тем же, а не определялось переменной в коде. Например:</p> + +<pre class="brush: json notranslate">"mdn_banner": { + "message": "For more information on web technologies, go to $MDN$.", + "description": "Tell the user about MDN", + "placeholders": { + "mdn": { + "content": "https://developer.mozilla.org/" + } + } +}</pre> + +<p>В этом примере мы сами задаем значение заполнителя, а не получаем его из переменной, такой как <code>$1</code>. Это может быть полезно, если сообщение очень сложное, и Вы хотите разделить значения, чтобы сделать строки более читаемыми. К тому же, доступ к этим значениям можно получить внутри программы.</p> + +<p>Вы также можете использовать такие замены для указания частей строки, не нуждающихся в переводе, таких как имена или названия.</p> + +<h2 id="Выбор_локализованной_строки">Выбор локализованной строки</h2> + +<p>Локализации могут быть указаны с помощью кода языка, например <code>fr</code> или <code>en</code>. Они также могут содержать региональный код, например <code>en_US</code> или <code>en_GB</code>, описывающий региональный вариант языка. Когда вы запрашиваете строку у системы i18n, системы возвращает ее используя следующий алгоритм:</p> + +<ol> + <li>Если для текущей локализации существует файл <code>messages.json</code>, содержащий требуемую строку, возвращается она.</li> + <li>Иначе,если текущая локализация — региональный вариант (например <code>en_US</code>) и существует файл <code>messages.json</code> для этого языка, но без указания региона (например <code>en</code>), содержащий строку, возвращается она.</li> + <li>Иначе, если существует файл <code>messages.json</code> для <code>default_locale</code>, указанной в <code>manifest.json</code>, и этот файл содержит нужную строку, возвращается она.</li> + <li>В противном случае возвращается пустая строка.</li> +</ol> + +<p>Рассмотрим следующий пример:</p> + +<ul class="directory-tree"> + <li>корневая-директория-расширения/ + <ul> + <li>_locales + <ul> + <li>en_GB + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + en + + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "color", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + </li> + <li>fr + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "<span lang="fr">couleur</span>", "description": "Color." }, ...}</code></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Пусть <code>default_locale</code> установлен как <code>fr</code>, а текущая локализация браузера — <code>en_GB</code>:</p> + +<ul> + <li>Вызов <code>getMessage("colorLocalised")</code> вернет "colour".</li> + <li>Если бы в <code>en_GB</code> не было "colorLocalized", то вызов <code>getMessage("colorLocalised")</code>, вернул бы "color", а не "couleur".</li> +</ul> + +<h2 id="Заранее_определенные_сообщения">Заранее определенные сообщения</h2> + +<p>Модуль i18n module предоставляет заранее определенные сообщения, которые можно вызвать таким же образом, как мы это делали в разделе {{anch("Интернационализация manifest.json")}}. Например:</p> + +<pre class="notranslate">__MSG_extensionName__</pre> + +<p>Заранее определенные сообщения используют такой же синтаксис, за исключением <code>@@</code> перед именем сообщения, например:</p> + +<pre class="notranslate">__MSG_@@ui_locale__</pre> + +<p>Следующая таблица содержит различные заранее определенные сообщения:</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Message name</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>@@extension_id</code></td> + <td> + <p>Внутренний UUID расширения. Эту строку можно использовать для создания URL ресурсов внутри расширения.Даже нелокализованные расширения могут использовать это сообщения.</p> + + <p>Это сообщения нельзя использовать в manifest.json.</p> + + <p>Также стоит заметить, что этот ID — <em>не</em> ID аддона, которое возвращает {{WebExtAPIRef("runtime.id")}}, и которое может быть установлено с помощью ключа <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> в manifest.json. Это сгенерированный UUID, содержащийся в URL аддона. Это означает, что данную величину нельзя использовать в качестве параметра <code>extensionId</code> метода {{WebExtAPIRef("runtime.sendMessage()")}}, или для проверки поля <code>id</code> объекта {{WebExtAPIRef("runtime.MessageSender")}}.</p> + </td> + </tr> + <tr> + <td><code>@@ui_locale</code></td> + <td>Текущая локализация; эту строку можно использовать для создания URL, зависящих от локализации.</td> + </tr> + <tr> + <td><code>@@bidi_dir</code></td> + <td>Направления чтения, либо "ltr" для языков, таких как английский, где текст читается слева направо, либо "rtl" для языков, считающихся справа налево, таких как арабский.</td> + </tr> + <tr> + <td><code>@@bidi_reversed_dir</code></td> + <td>Если <code>@@bidi_dir</code> имеет значение "ltr", то возвращает "rtl"; иначе "ltr".</td> + </tr> + <tr> + <td><code>@@bidi_start_edge</code></td> + <td>Если <code>@@bidi_dir</code> имеет значение "ltr", то возвращает "left"; иначе "right".</td> + </tr> + <tr> + <td><code>@@bidi_end_edge</code></td> + <td>Если <code>@@bidi_dir</code> имеет значение "ltr", то возвращает "right"; иначе "left".</td> + </tr> + </tbody> +</table> + +<p>Возвращаясь к нашему примеру, лучше было бы написать:</p> + +<pre class="brush: css notranslate">header { + background-image: url(../images/__MSG_@@ui_locale__/header.png); +}</pre> + +<p>Теперь мы можем хранить изображения в директориях поддерживаемых локализаций — en, de, и т. д. — что выглядит логичней.</p> + +<p>Давайте рассмотрим пример использования сообщений <code>@@bidi_*</code> в файле CSS:</p> + +<pre class="brush: css notranslate">body { + direction: __MSG_@@bidi_dir__; +} + +div#header { + margin-bottom: 1.05em; + overflow: hidden; + padding-bottom: 1.5em; + padding-__MSG_@@bidi_start_edge__: 0; + padding-__MSG_@@bidi_end_edge__: 1.5em; + position: relative; +}</pre> + +<p>Для языков, в которых текст читается слева направо, таких как английский, правила CSS, использующие заранее определенные сообщения, сверху задают такие значения:</p> + +<pre class="brush: css notranslate">direction: ltr; +padding-left: 0; +padding-right: 1.5em; +</pre> + +<p>Для языков, читающихся справа налево, значения будут следующими:</p> + +<pre class="brush: css notranslate">direction: rtl; +padding-right: 0; +padding-left: 1.5em;</pre> + +<h2 id="Тестирование_расширения">Тестирование расширения</h2> + +<p>Начиная с Firefox 45, расширения могут быть временно установлены с диска — подробнее об этом написано в статье <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Packaging_and_installation#Loading_from_disk">Loading from disk</a>. Сделайте это и попробуйте протестировать наше расширение <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a>. Перейдите на одну из Ваших любимых страниц и нажмите на ссылку, чтобы проверить, появляется ли сообщения, содержащее URL нажатой ссылки.</p> + +<p>Затем измените локализацию Firefox на какую-либо поддерживающуюся расширением, которое Вы хотите протестировать.</p> + +<ol> + <li>Откройте "about:config" в Firefox, и найдите параметр <code>intl.locale.requested</code> (обратите внимание на версию Firefox: в версиях до Firefox 59 этот параметр называется <code>general.useragent.locale</code>).</li> + <li>Если параметр существует, нажмите на него дважды (или нажмите Return/Enter), чтобы выбрать его, введите языковой код локализации, которую Вы хотите протестировать и нажмите "OK" (или Return/Enter). Например, в нашем примере расширение поддерживает "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Вы также можете указать пустую строку (<code>""</code>) в качестве значения. В этом случае браузер выберет язык Вашей ОС по умолчанию.</li> + <li>Если параметр <code>intl.locale.requested</code> не существует, нажмите правой кнопкой мыши на список параметров (или откройте контекстное меню при помощи клавиатуры), и выберите "New", а затем "String". Введите <code>intl.locale.requested</code> как имя настройки и, "de", "nl", и т. д. как значение, как это описано в шаге 2.</li> + <li>Найдите <code>intl.locale.matchOS</code> и, если параметр существует и равен <code>true</code>, дважды нажмите на него и установите на <code>false</code>.</li> + <li>Перезапустите браузер, чтобы изменения вступили в силу.</li> +</ol> + +<div class="note"> +<p><strong>Примечание</strong>: Этот метод работает, даже если у Вас не установлен <a href="https://addons.mozilla.org/en-US/firefox/language-tools/">языковой пакет</a> для выбранного языка. В этом случае UI браузера просто будет использовать Ваш язык по умолчанию.</p> +</div> + +<ol> +</ol> + +<div class="note"> +<p><strong>Примечание:</strong> Чтобы изменить результат <code>getUILanguage</code> требуется языковой пакет, поскольку он отражает язык UI браузера, а не язык сообщений расширения.</p> +</div> + +<p>Еше раз загрузите расширение с диска и протестируйте локализацию:</p> + +<ul> + <li>Еще раз откройте "about:addons" — теперь Вы должны увидеть Ваше расширение, его иконку, имя и описание на выбранном языке.</li> + <li>Еще раз протестируйте расширение. Для нашего примера, Вам следовало бы посетить другую страницу и, нажав на ссылку, проверить, появляется ли сообщение на нужном языке.</li> +</ul> + +<p>{{EmbedYouTube("R7--fp5pPGg")}}</p> diff --git a/files/ru/mozilla/add-ons/webextensions/модификация_веб_страницы/index.html b/files/ru/mozilla/add-ons/webextensions/модификация_веб_страницы/index.html new file mode 100644 index 0000000000..0f58364706 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/модификация_веб_страницы/index.html @@ -0,0 +1,238 @@ +--- +title: Модификация веб страницы +slug: Mozilla/Add-ons/WebExtensions/модификация_веб_страницы +translation_of: Mozilla/Add-ons/WebExtensions/Modify_a_web_page +--- +<p> </p> + +<div>{{AddonSidebar}}</div> + +<p>Одним из наиболее распространённых вариантов использования расширений является внесение изменение в веб-страницу. К примеру, расширение может изменить стиль, применённый к странице, скрыть существующие или вставить на страницу дополнительные DOM-узлы.</p> + +<p>Существует два способа сделать это используя WebExtensions API:</p> + +<ul> + <li><strong>Декларативно</strong>: объявить шаблон, которому соответствует набор URL-адресов, и загрузить набор скриптов на страницы, которые попадают в под этот шаблон.</li> + <li><strong>Программно</strong>: используя JavaScript API, загрузить скрипт на страницу, из определённой вкладки.</li> +</ul> + +<p>В любом случае, эти скрипты называются <em>контентными скриптами</em>, и отличаются от других скриптов, которые составляют расширение:</p> + +<ul> + <li>Они получают доступ к малому подмножеству WebExtension API.</li> + <li>Они получают прямой доступ к странице, на которой были загружены.</li> + <li>Они взаимодействуют с остальными скриптами расширения, используя API сообщений.</li> +</ul> + +<p>В этой статье мы рассмотрим оба способа загрузки скрипта.</p> + +<h2 id="Модификация_страниц_подпадающих_под_URL-шаблон">Модификация страниц, подпадающих под URL-шаблон</h2> + +<p>Прежде всего создадим новую директорию, назовём её "modify-page". В этой директории, создадим файл "manifest.json", со следующим содержимым:</p> + +<pre class="brush: json notranslate">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["https://developer.mozilla.org/*"], + "js": ["page-eater.js"] + } + ] + +}</pre> + +<p>Ключ <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> - это как мы загружаем скрипты на страницы, соответстующие URL-шаблону. В нашем случае, <code>content_scripts</code> говорит браузеру загрузить скрипт "page-eater.js" на все страницы, начинающиеся с <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>.</p> + +<div class="note"> +<p>Поскольку свойство <code>"js"</code> ключа <code>content_scripts</code> это массив, вы можете использовать его, для внедрения более одного скрипта. Если вы сделаете это, страницы получат набор, как если бы эти скрипты были загружены самой страницей, они будут загружены в той же очерёдности, в которой они расположены в массиве.</p> +</div> + +<div class="note"> +<p>Ключ <code>content_scripts</code> также имеет свойство <code>"css"</code>, которое вы можете использовать для вставки CSS-таблиц.</p> +</div> + +<p>Далее, создадим файл "page-eater.js", внутри директории "modify-page":</p> + +<pre class="brush: js notranslate">document.body.textContent = ""; + +var header = document.createElement('h1'); +header.textContent = "Эта страница была съедена"; +document.body.appendChild(header);</pre> + +<p>Теперь <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">установим расширение</a>, и перейдём на страницу <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>:</p> + +<p>{{EmbedYouTube("lxf2Tkg6U1M")}}</p> + +<div class="note"> +<p>Обратите внимание, несмотря на то, что в указанном видео, на странице <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> всё работает нормально, на текущий момент, для этого сайта, контентные скрипты заблокированы.</p> +</div> + +<h2 id="Программная_модификация_страницы">Программная модификация страницы</h2> + +<p>Что, если вы всё еще хотите "съедать" страницы, но лишь в тех случаях, когда пользователь попросил об этом? Давайте обновим этот пример таким образом, чтобы мы внедряли контентный скрипт, когда пользователь выбирает соответствующий пункт контентного меню.</p> + +<p>Для начала обновим "manifest.json":</p> + +<pre class="brush: json notranslate">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "permissions": [ + "activeTab", + "contextMenus" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>Мы удалили ключ <code>content_scripts</code> и добавили два новых:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions (разрешения)</a></code>: для внедрения скрипта, нам нужны разрешения для страниц, которые мы модифицируем. <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">Разрешение <code>activeTab</code></a> это способ получить доступ к текущей вкладки. Нам также нужно разрешение <code>contextMenus</code>, чтобы добавлять в контектсное меню новые элементы.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background (фоновый)</a></code>: мы используем этот ключ, для загрузки постоянного <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">"фонового скрипта"</a>, с именем "background.js", в котором мы настроим контекстное меню и внедрим контентный скрипт.</li> +</ul> + +<p>Давайте создадим этот файл. Создадим новый файл "background.js" в директории "modify-page" и поместим в него следующий код:</p> + +<pre class="brush: js notranslate">browser.contextMenus.create({ + id: "eat-page", + title: "Съесть эту страницу" +}); + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + browser.tabs.executeScript({ + file: "page-eater.js" + }); + } +}); +</pre> + +<p>В этом скрипте мы создаём <a href="/en-US/Add-ons/WebExtensions/API/ContextMenus/create">элемент контекстного меню</a>, передавая ему определённый идентификатор и заголовок (текст будет отображаться в элементе контекстного меню). Затем мы настраиваем обработчик событий таким образом, чтобы когда пользователь выбирает пункт контекстного меню, осуществлялась проверка, наш ли это элемент <code>eat-page</code>. Если это так - внедряем скрипт "page-eater.js" в текущую вкладку, используя <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code> API. Это API опционально принимает идентификатор вкладки, в качестве аргумента. Мы опустили его, это означает, что скрипт будет внедряться в текущую активную вкладку.</p> + +<p>На данном этапе расширение должно иметь следующий вид:</p> + +<pre class="line-numbers language-html notranslate"><code class="language-html">modify-page/ + background.js + manifest.json + page-eater.js</code></pre> + +<p>Теперь <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">перезагрузим расширение</a>, откроем страницу (на этот раз любую) активируем контекстное меню и выберем "Съесть эту страницу":</p> + +<p>{{EmbedYouTube("zX4Bcv8VctA")}}</p> + +<div class="note"> +<p>Обратите внимание, несмотря на то, что в указанном видео, на странице <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a> всё работает нормально, на текущий момент, для этого сайта, контентные скрипты заблокированы.</p> +</div> + +<h2 id="Обмен_сообщениями">Обмен сообщениями</h2> + +<p>Контентные и фоновые скрипты не могут на прямую взаимодействовать друг с другом. Не смотря на это они могут взаимодействовать с помощью обмена сообщениями. Для этого один конец создаёт обработчик сообщений, а другой - может посылать сообщения. В следующей таблице представлены API-интерфейсы, задействованные с каждой стороны:</p> + +<table class=" fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"></th> + <th scope="col">В контентном скрипте</th> + <th scope="col">В фоновом скрипте</th> + </tr> + <tr> + <th scope="row">Отправка сообщения</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#sendMessage()">browser.runtime.sendMessage()</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/sendMessage">browser.tabs.sendMessage()</a></code></td> + </tr> + <tr> + <th scope="row">Получение сообщения</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onMessage">browser.runtime.onMessage</a></code></td> + </tr> + </thead> +</table> + +<p>Давайте обновим наш пример, чтобы посмотреть, как послать сообщение из фонового скрипта.</p> + +<p>Изменим "background.js" :</p> + +<pre class="brush: js notranslate">browser.contextMenus.create({ + id: "eat-page", + title: "Съесть эту страницу" +}); + +function messageTab(tabs) { + browser.tabs.sendMessage(tabs[0].id, { + replacement: "Message from the extension!" + }); +} + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + browser.tabs.executeScript({ + file: "page-eater.js" + }); + + var querying = browser.tabs.query({ + active: true, + currentWindow: true + }); + querying.then(messageTab); + } +}); +</pre> + +<p>Теперь, после внедрения "page-eater.js", мы используем <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code>, чтобы получить текущую открытую вкладку и используем <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code>, для отправки сообщения контентному скрипту, загруженному на этой вкладке. Сообщение несёт полезную нагрузку <code>{replacement: "Message from the extension!"}</code>.</p> + +<p>Далее, обновим "page-eater.js":</p> + +<pre class="brush: js notranslate">function eatPage(request, sender, sendResponse) { + document.body.textContent = ""; + + var header = document.createElement('h1'); + header.textContent = request.replacement; + document.body.appendChild(header); +} + +browser.runtime.onMessage.addListener(eatPage); +</pre> + +<p>Теперь, вместо простого "поедания страницы", контентный скрипт ждёт сообщение, используя <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code>. Когда сообщение получено, контентный скрипт выполняет в точности такой же код, как и а примере ранее, за исключением того, что заменяющий текст берётся из <code>request.replacement</code>.</p> + +<p>Если мы хотим отправить сообщение наоборот, из контентного скрипта в фоновый, настройка будет обратной данному примеру, за исключением того, что мы будем использовать <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code> в контентном скрипте.</p> + +<div class="note"> +<p>Все эти примеры внедряют JavaScript; вы можете программно внедрять стилевые таблицы CSS используя функцию <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code>.</p> +</div> + +<h2 id="Узнать_больше">Узнать больше</h2> + +<ul> + <li>Руководство по <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">Content scripts</a></li> + <li>Ключ манифеста<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code></li> + <li>Ключ манифеста<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code></li> + <li>Примеры использования <code>content_scripts</code>: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">borderify</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/page-to-extension-messaging">page-to-extension-messaging</a></li> + </ul> + </li> + <li>Примеры использования <code>tabs.executeScript()</code>: + <ul> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-demo">context-menu-demo</a></li> + </ul> + </li> +</ul> diff --git a/files/ru/mozilla/add-ons/webextensions/перевод/index.html b/files/ru/mozilla/add-ons/webextensions/перевод/index.html new file mode 100644 index 0000000000..4ceb3eab28 --- /dev/null +++ b/files/ru/mozilla/add-ons/webextensions/перевод/index.html @@ -0,0 +1,218 @@ +--- +title: Отладка +slug: Mozilla/Add-ons/WebExtensions/Перевод +tags: + - Firefox + - Mozilla + - Отладка + - Пособие + - Предоставление Веб-страниц +translation_of: Mozilla/Add-ons/WebExtensions/Debugging +--- +<div>{{AddonSidebar}}</div> + +<div>This article explains how you can use the Firefox developer tools to debug extensions built with WebExtension APIs.</div> + +<p>An extension can consist of various different pieces — background scripts, popups, options pages, content scripts, sidebars — and you'll need to use a slightly different workflow to debug each piece. So each piece gets a top-level section in this article, and the intention is that these sections can be read in isolation. We'll begin by introducing the Add-on Debugger, which you'll use to debug most of the pieces of your extension.</p> + +<ul> +</ul> + +<h2 id="The_Add-on_Debugger">The Add-on Debugger</h2> + +<p>For most of this article we'll use the Add-on Debugger. To open the Add-on Debugger:</p> + +<ul> + <li>open Firefox</li> + <li>enter "about:debugging" in the URL bar</li> + <li>check the box labelled "Enable add-on debugging"</li> + <li>click the "Debug" button next to your extension</li> + <li>click "OK" in the warning dialog.</li> +</ul> + +<p>You'll then see a new window open. The main Firefox window will be switched into the foreground, so you'll have to click on the new window to bring it in front.</p> + +<p>{{EmbedYouTube("G2a65ewjfj0")}}</p> + +<p>This new window is sometimes called a "toolbox" and contains the debugging tools we'll use. It has a tabbed interface: the row of tabs along the top lets you switch between the different tools:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/16309/add-on-debugger.png" style="display: block; height: 472px; margin-left: auto; margin-right: auto; width: 922px;"></p> + +<p>In this article we'll use three debugging tools:</p> + +<ul> + <li><a href="/en-US/docs/Tools/Web_Console">The Console</a>: this displays messages logged by the extension as well as error messages logged by the browser as it runs the extension. It also provides a command line enabling you to execute JavaScript in the extension's context.</li> + <li><a href="/en-US/docs/Tools/Debugger">The Debugger</a>: this enables you to set breakpoints and watchpoints in your extension's JavaScript, and examine and modify its internal state.</li> + <li><a href="/en-US/docs/Tools/Page_Inspector">The Inspector</a>: this enables you to examine and modify the HTML and CSS used to build your extension's pages.</li> +</ul> + +<h2 id="Debugging_background_scripts">Debugging background scripts</h2> + +<div class="note"> +<p>The examples in this section use the "notify-link-clicks-l10n" example extension. If you'd like to play along, you can find this example in the <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository.</p> +</div> + +<p><a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">Background scripts</a> stay loaded for the lifetime of the extension. They're loaded inside an invisible "background page": by default this is an empty HTML document, but you can specify your own HTML content using the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">"background" key in "manifest.json"</a>.</p> + +<p>You can debug background scripts using the <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Add-on Debugger</a>.</p> + +<p>In the Add-on Debugger's Console you'll see logged output, including calls to <code><a href="/en-US/docs/Web/API/Console/log">console.log()</a></code> from your own background scripts and any errors the browser raises as it executes them. Note that at the moment, the console shows all errors raised by the browser, not just errors related to your extensions code.</p> + +<p>For example, the <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> example extension logs a message from its background script when it receives a message from one of its content scripts:</p> + +<p>{{EmbedYouTube("WDQsBU-rpN0")}}</p> + +<p>Using the Console's command line, you can access and modify the objects created by your background scripts.</p> + +<p>For example, here we call the <code>notify()</code> function defined in the extension's background script:</p> + +<p>{{EmbedYouTube("g-Qgf8Mc2wg")}}</p> + +<p>If you switch to the Debugger, you'll see all your extension's background scripts. You can set breakpoints, step through code, and do <a href="https://developer.mozilla.org/en-US/docs/Tools/Debugger">everything else you'd expect to be able to do in a debugger</a>.</p> + +<p>{{EmbedYouTube("MNeaz2jdmzY")}}</p> + +<p>If you press the Escape key while you're in the Debugger, the toolbox will be split, with the bottom half now occupied by the Console. While you're at a breakpoint, you can now modify the program's state using the console. See <a href="/en-US/docs/Tools/Web_Console/Split_console">Split console</a> for more on this.</p> + +<h2 id="Debugging_options_pages">Debugging options pages</h2> + +<p><a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Options_pages">Options pages</a> are HTML pages that the extension developer can supply, that contain options for the extension. They are typically displayed in an iframe in the Add-ons Manager (to see the Add-ons Manager, visit the "about:addons" page).</p> + +<p>To debug options pages:</p> + +<ul> + <li>open the <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Add-on Debugger</a> for your extension</li> + <li>open your extension's option page.</li> +</ul> + +<p>Any JavaScript sources it includes are then listed in the Debugger:</p> + +<p>{{EmbedYouTube("BUMG-M8tFF4")}}</p> + +<div class="note"> +<p>This video uses the <a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colourbeastify">favourite-colour</a> example extension.</p> +</div> + +<p>You'll also see any messages logged by your code in the Add-on Debugger's Console.</p> + +<p>You can also use the Add-on Debugger to debug the page's HTML and CSS. First, though, you need to point the tools at the iframe that hosts the options page. To do this: open the options page, click the icon highlighted in the screenshot below, and select the options page from the drop-down list:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p>Now switch to the Inspector tab, and you'll be able to examine and edit HTML and CSS for the page:</p> + +<p>{{EmbedYouTube("-2m3ubFAU94")}}</p> + +<h2 id="Debugging_popups">Debugging popups</h2> + +<p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Popups">Popups</a> are dialogs that are attached to browser actions or page actions. They are specified using an HTML document that can include CSS and JavaScript sources for styling and behavior. Whenever the popup is visible, you can use the <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Add-on Debugger</a> to debug its code.</p> + +<p>One problem with popups is that if a popup is open and you click outside the popup, the popup is closed and its code is unloaded. This obviously makes them impossible to debug. To suppress this behavior, select Disable Popup Auto-Hide from the Elipsis menu as shown below:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/16301/add-on-debugger.png" style="display: block; height: 612px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p>Now, when you open a popup it will stay open until you press Escape.</p> + +<div class="note"> +<p><strong>Note:</strong> This change applies to built-in browser popups, like the Elipsis menu (<code>...</code>), as well as extension popups.</p> + +<p>The setting does not persist across sessions. When you close the window, the setting reverts to auto-hide popups.</p> +Internally, this button just toggles the <code>ui.popup.disable_autohide</code> preference, which you can toggle manually using about:config.</div> + +<p>When the popup is open, its JavaScript sources will be listed in the Debugger. You can set breakpoints and modify the program's internal state:</p> + +<p>{{EmbedYouTube("hzwnR8qoz2I")}}</p> + +<div class="note"> +<p>This video uses the <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> example extension.</p> +</div> + +<p>You can also use the Add-on Debugger to debug the popup's HTML and CSS. First, though, you need to point the tools at the popup's document. To do this: open the popup, then click the icon highlighted in the screenshot below and select the popup's page from the drop-down list:<img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p>Now switch to the Inspector, and you'll be able to examine and edit the popup's HTML and CSS:</p> + +<p>{{EmbedYouTube("6lvdm7jaq7Y")}}</p> + +<h2 id="Debugging_content_scripts">Debugging content scripts</h2> + +<p>You can use the Add-on Debugger to debug background pages, options pages, and popups. However, you can't use it to debug content scripts. This is because, in <a href="/en-US/docs/Mozilla/Firefox/Multiprocess_Firefox">multiprocess Firefox</a>, content scripts run in a different process from the other parts of your extension. The browser console has similar limitations.</p> + +<p>To debug content scripts attached to a web page, use the normal web developer tools for that page:</p> + +<ul> + <li>either select "Toggle Tools" from the Web Developer submenu in the Firefox Menu (or Tools menu if you display the menu bar or are on Mac OS X)</li> + <li>or press the <kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>I</kbd> (<kbd>Command</kbd><kbd>Option</kbd><kbd>I</kbd> on OS X) keyboard shortcut.</li> +</ul> + +<p>{{EmbedYouTube("f46hMLELyaI")}}</p> + +<p>By default, the tools are shown attached to the bottom of browser tab, to reflect the fact that they are attached to this tab. You'll see any output from <code><a href="/en-US/docs/Web/API/Console/log">console.log()</a></code> statements in your content scripts. You will also see your content scripts listed in the Debugger, where you'll be able to set breakpoints, step through the code, and so on.</p> + +<p>{{EmbedYouTube("Hx3GU_fEPeo")}}</p> + +<div class="note"> +<p>This video uses the <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> example extension.</p> +</div> + +<div class="note"> +<p>If the developer tools tab was not already open when the content script was injected, sometimes the content script is not listed in the debugger panel. If you experience this, reloading the page with the developer tools tab open should fix the problem.</p> +</div> + +<h2 id="Debugging_sidebars">Debugging sidebars</h2> + +<p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">Sidebars</a> are HTML pages opened as a sidebar in the browser UI that the extension developer can supply.</p> + +<p>To debug sidebars:</p> + +<ul> + <li>open the <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Add-on Debugger</a> for your extension</li> + <li>open your extension's sidebar.</li> +</ul> + +<p>Any JavaScript sources it includes are then listed in the Debugger.</p> + +<p>You'll also see any messages logged by your code in the Add-on Debugger's Console.</p> + +<p>You can also use the Add-on Debugger to debug the page's HTML and CSS. First, though, you need to point the tools at the iframe that hosts the options page. To do this: open the sidebar, click the icon highlighted in the screenshot below, and select the sidebar from the drop-down list:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<h2 id="Debug_runtime_permission_requests">Debug runtime permission requests</h2> + +<p> </p> + +<p>Runtime permissions granted in your extension are persistent. Therefore, if you want to test cases where the permission has not been granted you will need to add a feature to programmatically remove the permission, use the <a class="external external-icon" href="https://github.com/rpl/dev-webext-permissions-manager" rel="noopener">Extensions Permission Manager,</a> or give your extension a new ID. For more information, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Test_permission_requests#Retest_runtime_permission_grants">Retest runtime permission grants</a> in <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Test_permission_requests">Test permission requests</a>.</p> + +<p> </p> + +<h2 id="Debugging_developer_tools_pages_panels">Debugging developer tools pages & panels</h2> + +<p><a href="/en-US/Add-ons/WebExtensions/Extending_the_developer_tools">Developer tools</a> are extended by loading a hidden HTML page when devtools are opened and <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.panels/create">developer tools panels</a> are HTML pages displayed as a developer tool in the browser UI that the extension developer can supply.</p> + +<p>To debug the developer tools page:</p> + +<ul> + <li>open the <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Add-on Debugger</a> for your extension</li> + <li>open the Web Developer Tools</li> +</ul> + +<p>To debug developer tools panels:</p> + +<ul> + <li>Follow the steps for the developer tools page above</li> + <li>Select your developer tools panel</li> +</ul> + +<p>Any JavaScript sources it includes are then listed in the Debugger.</p> + +<p>You'll also see any messages logged by your code in the Add-on Debugger's Console.</p> + +<p>You can also use the Add-on Debugger to debug the page's HTML and CSS. First, though, you need to point the tools at the iframe that hosts the options page. To do this: open the sidebar, click the icon highlighted in the screenshot below, and select the sidebar from the drop-down list:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<h2 id="Debugging_Browser_Restarts">Debugging Browser Restarts</h2> + +<p>If your extension is active in ways that might be affected by the browser restarting, such as a session being restored, then you may want to do extra testing to ensure your code works as expected in those conditions.</p> + +<p>See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Testing_persistent_and_restart_features">Testing persistent and restart features</a> for more details.</p> |