Учебное пособие: переход на манифест версии 2

В Chrome 18 поддержка версии манифеста 1 была прекращена, и её постепенное прекращение будет осуществляться в соответствии с графиком поддержки версии манифеста 1. Изменения от версии 1 к версии 2 делятся на две основные категории: изменения API и изменения в области безопасности.

В этом документе представлены контрольные списки для миграции ваших расширений Chrome с версии манифеста 1 на версию 2, а также более подробное описание того, что означают эти изменения и почему они были внесены.

Контрольный список изменений API

  • Вы используете свойство browser_actions или API chrome.browserActions ?

  • Замените browser_actions на свойство browser_action в единственном числе.

  • Замените chrome.browserActions на chrome.browserAction .

  • Замените свойство icons на default_icon .

  • Замените свойство name на default_title .

  • Замените свойство popup на default_popup (теперь оно должно быть строкой).

  • Вы используете свойство page_actions или API chrome.pageActions ?

  • Замените page_actions на page_action .

  • Замените chrome.pageActions на chrome.pageAction .

  • Замените свойство icons на default_icon .

  • Замените свойство name на default_title .

  • Замените свойство popup на default_popup (теперь оно должно быть строкой).

  • Вы используете свойство chrome.self ?

  • Замените на chrome.extension .

  • Вы используете свойство Port.tab ?

  • Замените на Port.sender .

  • Вы используете API chrome.extension.getTabContentses() или chrome.extension.getExtensionTabs() ?

  • Замените на chrome.extension.getViews( { "type" : "tab" } ) .

  • Использует ли ваше расширение фоновую страницу?

  • Замените свойство background_page на свойство background .

  • Добавьте свойство scripts или page , содержащее код страницы.

  • Добавьте свойство persistent и установите его значение в false , чтобы преобразовать фоновую страницу в страницу события.

Контрольный список изменений в системе безопасности

  • Используете ли вы встроенные блоки скриптов на HTML-страницах?

  • Удалите JS-код, заключенный в теги <script> , и поместите его во внешний JS-файл.

  • Используете ли вы встроенные обработчики событий (например, onclick и т. д.)?

  • Удалите их из HTML-кода, переместите во внешний JS-файл и используйте вместо них addEventListener() .

  • Внедряет ли ваше расширение скрипты контента в веб-страницы, которым необходим доступ к ресурсам (таким как изображения и скрипты), содержащимся в пакете расширения?

  • Определите свойство web_accessible_resources и перечислите ресурсы (а также, при необходимости, отдельную политику безопасности контента для этих ресурсов).

  • Ваше расширение встраивает внешние веб-страницы?

  • Определите свойство "песочница" .

  • Использует ли ваш код или библиотека функции eval() , new Function() , innerHTML , setTimeout() или иные способы передачи строк кода JavaScript, которые динамически вычисляются?

  • Используйте JSON.parse() если вы преобразуете JSON-код в объект.

  • Используйте библиотеку, поддерживающую CSP, например, AngularJS .

  • Создайте запись в песочнице в вашем манифесте и запустите соответствующий код в песочнице, используя postMessage() для связи с изолированной страницей.

  • Вы загружаете внешний код, например, jQuery или Google Analytics?

  • Рекомендуется загрузить библиотеку, упаковать её в ваше расширение, а затем загрузить из локального пакета.

  • Добавьте в список разрешенных доменов HTTPS, который обслуживает ресурс, указанный в разделе "content_security_policy" вашего манифеста.

Краткое описание изменений API

Вторая версия манифеста вносит ряд изменений в API для действий в браузере и на странице, а также заменяет некоторые старые API на новые.

Изменения в действиях браузера

В API действий браузера внесены некоторые изменения в названия:

  • Свойства browser_actions и chrome.browserActions заменены на их аналоги в единственном числе: browser_action и chrome.browserAction .

  • В старом свойстве browser_actions находились свойства icons , name и popup . Теперь они заменены следующими:

  • default_icon для значка действия браузера

  • default_name имя текста, который отображается во всплывающей подсказке при наведении курсора на значок.

  • default_popup указывает HTML-страницу, представляющую пользовательский интерфейс для действия в браузере (и теперь это должна быть строка, а не объект).

Изменения в действиях страницы

Аналогично изменениям в работе с действиями браузера, API для действий на страницах также претерпел изменения:

  • Свойства page_actions и chrome.pageActions заменены на их аналоги в единственном числе: page_action и chrome.pageAction .

  • В старом свойстве page_actions находились свойства icons , name и popup . Теперь они заменены следующими:

  • default_icon для значка действия страницы

  • default_name имя текста, который отображается во всплывающей подсказке при наведении курсора на значок.

  • default_popup указывает HTML-страницу, представляющую пользовательский интерфейс для действия на странице (и теперь это должна быть строка, а не объект).

Удалены и изменены API.

Некоторые API-интерфейсы расширений были удалены и заменены новыми аналогами:

  • Свойство background_page было заменено на background .
  • Свойство chrome.self удалено, используйте chrome.extension .
  • Свойство Port.tab заменено на Port.sender .
  • API-функции chrome.extension.getTabContentses() и chrome.extension.getExtensionTabs() были заменены на chrome.extension.getViews( { "type" : "tab" } ) .

Краткое описание изменений в системе безопасности

Переход от версии манифеста 1 к версии 2 сопровождается рядом изменений, связанных с безопасностью. Многие из этих изменений обусловлены внедрением Chrome политики безопасности контента (Content Security Policy ); вам следует подробнее ознакомиться с этой политикой, чтобы понять ее последствия.

Встроенные скрипты и обработчики событий запрещены.

В связи с использованием политики безопасности контента (Content Security Policy) вы больше не можете использовать теги <script> , встроенные в HTML-контент. Их необходимо переместить во внешние JS-файлы. Кроме того, встроенные обработчики событий также не поддерживаются. Например, предположим, что в вашем расширении был следующий код:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

Этот код вызовет ошибку во время выполнения. Чтобы это исправить, переместите содержимое тега <script> во внешние файлы и укажите на них ссылку с помощью атрибута src='path_to_file.js' .

Аналогично, встроенные обработчики событий, которые являются распространенным и удобным инструментом, используемым многими веб-разработчиками, не будут выполняться. Например, рассмотрим такие распространенные случаи, как:

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

Эти функции не будут работать в расширениях манифеста V2. Удалите встроенные обработчики событий, поместите их во внешний JS-файл и используйте addEventListener() для регистрации обработчиков событий для них. Например, в вашем JS-коде используйте:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

Это гораздо более удобный способ отделить поведение вашего расширения от разметки его пользовательского интерфейса.

Встраивание контента

В некоторых случаях ваше расширение может содержать контент, предназначенный для внешнего использования или поступающий из внешнего источника.

Содержимое расширения на веб-страницах: Если ваше расширение встраивает ресурсы (например, изображения, скрипты, стили CSS и т. д.), которые используются в скриптах содержимого, внедряемых в веб-страницы, вам необходимо использовать свойство web_accessible_resources , чтобы добавить эти ресурсы в список разрешенных, чтобы внешние веб-страницы могли их использовать:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Встраивание внешнего контента: Политика безопасности контента разрешает загрузку из вашего пакета только локальных скриптов и объектов, что предотвращает внедрение неизвестного кода в ваше расширение внешними злоумышленниками. Однако иногда возникает необходимость загрузки внешних ресурсов, таких как код jQuery или Google Analytics. Для этого есть два способа:

  1. Загрузите необходимую библиотеку локально (например, jQuery) и упакуйте её вместе с вашим расширением.

  2. Вы можете частично ослабить ограничения CSP, добавив HTTPS-источники в список разрешенных в разделе "content_security_policy" вашего манифеста. Для подключения такой библиотеки, как Google Analytics, следует использовать следующий подход:

    {
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}

Использование динамической оценки скриптов

Пожалуй, одно из самых значительных изменений в новой схеме манифеста v2 заключается в том, что расширения больше не могут использовать методы динамической оценки скриптов, такие как eval() или new Function() , или передавать строки кода JavaScript в функции, которые вызовут использование eval() , например, setTimeout() . Кроме того, известно, что некоторые широко используемые библиотеки JavaScript, такие как Google Maps и некоторые библиотеки шаблонов, используют некоторые из этих методов.

Chrome предоставляет песочницу для страниц, позволяющую им работать в собственном исходном коде, при этом доступ к API chrome.* для них закрыт. Для использования eval() и подобных им в соответствии с новой политикой безопасности контента:

  1. Создайте запись в песочнице в файле манифеста.
  2. В поле "Песочница" укажите страницы, которые вы хотите запустить в этой песочнице.
  3. Для связи с изолированной страницей используйте передачу сообщений через postMessage() .

Более подробную информацию о том, как это сделать, см. в документации по оценке в изолированной среде .

Дополнительная информация

Изменения во второй версии манифеста призваны помочь разработчикам создавать более безопасные и надёжно спроектированные расширения и приложения. Полный список изменений от первой до второй версии манифеста см. в документации к файлу манифеста . Для получения дополнительной информации об использовании песочницы для изоляции небезопасного кода прочитайте статью о песочнице eval . Вы можете узнать больше о политике безопасности контента (Content Security Policy), посетив наш учебник по расширениям и ознакомившись с полезным руководством на HTML5Rocks .