Эта страница переведена с помощью Cloud Translation API.

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

Манифест версии 1 устарел в Chrome 18, и поддержка будет прекращена в соответствии с графиком поддержки манифеста версии 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() или иным образом передает строки кода JS, которые оцениваются динамически?
Используйте JSON.parse() , если вы анализируете код JSON в объект.
Используйте CSP-совместимую библиотеку, например AngularJS .
Создайте запись в песочнице в своем манифесте и запустите затронутый код в песочнице, используя postMessage() для связи со страницей в песочнице.
Загружаете ли вы внешний код, например jQuery или Google Analytics?
Рассмотрите возможность загрузки библиотеки и упаковки ее в свое расширение, а затем загрузки ее из локального пакета.
Добавьте в белый список домен HTTPS, который обслуживает ресурс, в части «content_security_policy» вашего манифеста.

Сводка изменений API

Манифест версии 2 вносит несколько изменений в 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 Политики безопасности контента ; вам следует больше узнать об этой политике, чтобы понять ее последствия.

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

Из-за использования Политики безопасности контента вы больше не можете использовать теги <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. Есть два способа сделать это:

Загрузите соответствующую библиотеку локально (например, jQuery) и упакуйте ее с вашим расширением.
Вы можете ограничить 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() , или передавать строки кода JS функциям, которые вызывают вызов eval() используется, например, setTimeout() . Кроме того, известно, что некоторые широко используемые библиотеки JavaScript, такие как Google Maps и некоторые библиотеки шаблонов, используют некоторые из этих методов.

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

Создайте запись песочницы в файле манифеста.
В записи песочницы перечислите страницы, которые вы хотите запустить в песочнице.
Используйте передачу сообщений через postMessage() для связи со страницей в песочнице.

Дополнительные сведения о том, как это сделать, см. в документации по тестированию песочницы .

Дальнейшее чтение

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