Ta strona została przetłumaczona przez Cloud Translation API.

Samouczek: przenoszenie do platformy Manifest V2

Wersja 1 pliku manifestu została wycofana w Chrome 18. Obsługa zostanie wyłączona zgodnie z wyświetl harmonogram pomocy dla wersji 1. Zmiany z wersji 1 na wersję 2 należą do dwóch kategorie: zmiany w interfejsach API i zmiany w zabezpieczeniach.

Ten dokument zawiera listy kontrolne umożliwiające przeniesienie rozszerzeń do Chrome z wersji pliku manifestu do wersji 1 wersji 2 oraz bardziej szczegółowych opisów tych zmian i ich przyczyn.

Lista kontrolna zmian w interfejsie API

Czy używasz właściwości browser_actions czy interfejsu API chrome.browserActions?
Zastąp browser_actions właściwością browser_action liczbą pojedynczej.
Zamień chrome.browserActions na chrome.browserAction.
Zastąp właściwość icons właściwością default_icon.
Zastąp właściwość name właściwością default_title.
Zastąp właściwość popup właściwością default_popup (która teraz musi być ciągiem znaków).
Czy używasz właściwości page_actions czy interfejsu API chrome.pageActions?
Zamień page_actions na page_action.
Zamień chrome.pageActions na chrome.pageAction.
Zastąp właściwość icons właściwością default_icon.
Zastąp właściwość name właściwością default_title.
Zastąp właściwość popup właściwością default_popup (która teraz musi być ciągiem znaków).
Czy używasz właściwości chrome.self?
Zamień na element chrome.extension.
Czy używasz właściwości Port.tab?
Zamień na element Port.sender.
Czy używasz: chrome.extension.getTabContentses() czy chrome.extension.getExtensionTabs() interfejsów API?
Zamień na element chrome.extension.getViews( { "type" : "tab" } ).
Czy rozszerzenie korzysta ze strony w tle?
Zastąp właściwość background_page właściwością background.
Dodaj właściwość scripts lub page, która zawiera kod strony.
Dodaj właściwość persistent i ustaw jej wartość na false, aby przekształcić stronę tła w zdarzenie strona

Lista kontrolna zmian zabezpieczeń

Czy używasz bloków wbudowanych skryptów na stronach HTML?
Usuń kod JS zawarty w tagach <script> i umieść go w zewnętrznym pliku JS.
Czy używasz wbudowanych modułów obsługi zdarzeń (np. onclick)?
Usuń je z kodu HTML, przenieś do zewnętrznego pliku JS i użyj rozszerzenia addEventListener() .
Czy rozszerzenie wprowadza skrypty treści do stron internetowych, które potrzebują dostępu do zasobów (takich jak (obrazy i skrypty) zawarte w pakiecie rozszerzenia?
Zdefiniuj właściwość web_accessible_resources i wyświetl listę zasobów (oraz opcjonalnie osobne zasady Content Security Policy dla tych zasobów).
Czy Twoje rozszerzenie zawiera zewnętrzne strony internetowe?
Określ właściwość sandbox.
Czy Twój kod lub biblioteka używa eval(), nowej Function(), innerHTML, setTimeout() lub jeśli nie przekazujesz ciągów kodu JS, które są oceniane dynamicznie?
Użyj JSON.parse(), jeśli analizujesz kod JSON do postaci obiektu.
Użyj biblioteki współpracującej z CSP, na przykład AngularJS.
Utwórz w pliku manifestu wpis w trybie piaskownicy i uruchom w niej kod, którego dotyczy problem, za pomocą polecenia postMessage() komunikuje się ze stroną w piaskownicy.
Czy wczytujesz kod zewnętrzny, np. jQuery lub Google Analytics?
Spróbuj pobrać bibliotekę i spakować ją do rozszerzenia, a potem wczytać z pakietu lokalnym.
Umieść na liście dozwolonych domenę HTTPS, która udostępnia zasób na potrzeby zasady „content_security_policy” części pliku manifestu.

Podsumowanie zmian w interfejsie API

Wersja 2 pliku manifestu wprowadza kilka zmian w interfejsach API działań przeglądarki i działań na stronie oraz zastępuje kilka starych interfejsów API do nowszych.

Zmiany w działaniach przeglądarki

W interfejsie API działań przeglądarki wprowadza pewne zmiany w nazwach:

Właściwości browser_actions i chrome.browserActions zostały zastąpione liczby pojedyncze browser_action i chrome.browserAction.
W starej usłudze browser_actions znajdowały się usługi icons, name i popup. Zastąpiliśmy je następującymi fragmentami:
default_icon – ikona plakietki działania w przeglądarce
default_name w przypadku tekstu, który pojawia się w etykietce po najechaniu kursorem na plakietkę.
default_popup dla strony HTML, która reprezentuje interfejs użytkownika dla działania przeglądarki (która musi teraz być ciągiem, nie może być obiektem);

Zmiany dotyczące działań na stronach

Podobnie jak w przypadku działań w przeglądarce, zmienił się też interfejs API działań na stronie:

Właściwości page_actions i chrome.pageActions zostały zastąpione liczbą pojedynczą odpowiedniki page_action i chrome.pageAction.
W starej usłudze page_actions znajdowały się usługi icons, name i popup. Te zostały zastąpione przez:
default_icon – ikona plakietki działania na stronie
default_name w przypadku tekstu, który pojawia się w etykietce po najechaniu kursorem na plakietkę.
default_popup dla strony HTML, która reprezentuje interfejs użytkownika dla działania strony (która musi być teraz jest ciągiem znaków, nie może to być obiekt).

Usunięte i zmienione interfejsy API

Usunęliśmy kilka interfejsów API rozszerzeń i zastąpiliśmy je nowymi odpowiednikami:

Właściwość background_page została zastąpiona przez właściwość background.
Właściwość chrome.self została usunięta. Użyj chrome.extension.
Właściwość Port.tab została zastąpiona właściwością Port.sender.
Interfejsy API chrome.extension.getTabContentses() oraz chrome.extension.getExtensionTabs() zostały została zastąpiona przez chrome.extension.getViews( { "type" : "tab" } ).

Podsumowanie zmian w zabezpieczeniach

Przejście z wersji 1 pliku manifestu do wersji 1 wiąże się z szeregiem zmian związanych z bezpieczeństwem. wersji 2. Wiele z tych zmian ma związek z wprowadzeniem w Chrome Content Security Policy. Ty powinni zapoznać się z dodatkowymi zasadami, aby poznać ich konsekwencje.

Wbudowane skrypty i moduły obsługi zdarzeń są niedozwolone

Ze względu na zastosowanie Content Security Policy nie możesz już używać wbudowanych tagów <script> z treścią HTML. Należy je przenieść do zewnętrznych plików JS. Dodatkowo wbudowane moduły obsługi zdarzeń również nie są obsługiwane. Załóżmy na przykład, że rozszerzenie zawiera taki kod:

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

Ten kod spowoduje błąd w czasie działania. Aby rozwiązać ten problem, przenieś zawartość tagu <script> do plików zewnętrznych i odwoływać się do nich za pomocą atrybutu src='path_to_file.js'.

Analogicznie są to wbudowane moduły obsługi zdarzeń, które są powszechnie wykorzystywaną i wygodną funkcją. Programiści stron internetowych nie będą wykonywane. Przeanalizujmy typowe przypadki, takie jak:

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

Nie będą działać z rozszerzeniami manifestu w wersji 2. Usuń wbudowane moduły obsługi zdarzeń i umieść je w sekcji zewnętrznego pliku JS i zarejestruj dla nich moduły obsługi zdarzeń za pomocą addEventListener(). Dla: na przykład w kodzie JS użyj:

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

To znacznie wyraźniejszy sposób na oddzielenie działania rozszerzenia od jego znaczników interfejsu.

Umieszczanie treści

W niektórych sytuacjach rozszerzenie może zawierać treści do użytku zewnętrznego lub ze źródła zewnętrznego.

Zawartość rozszerzeń na stronach internetowych: Jeśli rozszerzenie zawiera zasoby (obrazy, skrypty, style CSS itp.), które są używane w treści skryptów wstrzykiwanych na stronach internetowych musisz używać właściwości web_accessible_resources aby dodać do listy dozwolonych te zasoby, aby mogły z nich korzystać zewnętrzne strony internetowe:

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

Umieszczanie treści zewnętrznych: Content Security Policy umożliwia ładowanie z pakietu tylko lokalnych skryptów i obiektów, które uniemożliwia osobom z zewnątrz wprowadzenie nieznanego kodu do Twojego rozszerzenia. Istnieją jednak gdy chcesz wczytać zasoby obsługiwane z zewnątrz, takie jak jQuery lub kod Google Analytics. Można to zrobić na dwa sposoby:

Pobierz odpowiednią bibliotekę lokalnie (na przykład jQuery) i spakuj ją z rozszerzeniem.
Możesz złagodzić CSP w ograniczony sposób, dodając źródła HTTPS do listy dozwolonych w "content_security_policy" pliku manifestu. Aby dodać bibliotekę, np. Google Analytics, w taki sposób:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Użycie dynamicznej oceny skryptów

Być może jedną z największych zmian w nowym schemacie manifestu w wersji 2 jest to, że rozszerzenia nie mogą już użyj technik dynamicznej oceny skryptów, takich jak eval() lub nowy element Function(), albo przekazuj ciągi znaków JS do funkcji, które spowodują użycie interfejsu eval(), np. setTimeout(). Ponadto niektóre najczęściej używane biblioteki JavaScript, takie jak Mapy Google i niektóre biblioteki szablonów, niektóre z nich.

Chrome udostępnia piaskownicę, w której strony działają we własnym źródle, które nie mają dostępu do Chrome*. API. Aby korzystać z eval() i podobnych usług zgodnie z nową polityką Content Security Policy:

Utwórz w pliku manifestu wpis piaskownicy.
We wpisie piaskownicy wymień strony, które chcesz uruchomić w tej piaskownicy.
Do komunikacji ze stroną w trybie piaskownicy używaj wiadomości przekazywanych przez postMessage().

Szczegółowe informacje na ten temat znajdziesz w dokumentacji dotyczącej oceniania piaskownicy.

Więcej informacji

Zmiany w pliku manifestu w wersji 2 mają na celu pomóc deweloperom w tworzeniu o niezawodnej architekturze rozszerzeń i aplikacji. Aby zobaczyć pełną listę zmian wprowadzonych w pliku manifestu w wersji 1 do wersji 2 znajdziesz w dokumentacji pliku manifestu. Więcej informacji o korzystaniu z trybu piaskownicy aby odizolować niebezpieczny kod, przeczytaj artykuł na temat oceniania piaskownicy. Więcej informacji o funkcji Treść Polityki bezpieczeństwa Google, zapoznając się z samouczkiem dotyczącym rozszerzeń oraz dobrym wprowadzeniem HTML5Rocks.