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

Samouczek: przenoszenie do platformy Manifest V2

Manifest w wersji 1 został wycofany w Chrome 18, a obsługa tej wersji zostanie wycofana stopniowo zgodnie z harmonogramem obsługi wersji 1 manifestu. Zmiany z wersji 1 na wersję 2 można podzielić na 2 kategorie: zmiany w interfejsie API i zmiany w zabezpieczeniach.

Ten dokument zawiera listy kontrolne migracji rozszerzeń Chrome z wersji pliku manifestu 1 na wersję 2. Następnie znajdziesz w nim bardziej szczegółowe podsumowania zmian i ich uzasadnienia.

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 w jej pojedynczej formie.
Zawartość komórki chrome.browserActions zastąpiono tekstem chrome.browserAction.
Zamień właściwość icons na default_icon.
Zamień właściwość name na default_title.
Zastąp właściwość popup wartością default_popup (musi być to teraz ciąg znaków).
Czy używasz właściwości page_actions czy interfejsu API chrome.pageActions?
Zawartość komórki page_actions zastąp komórką page_action.
Zawartość komórki chrome.pageActions zastąp komórką chrome.pageAction.
Zamień właściwość icons na default_icon.
Zamień właściwość name na default_title.
Zastąp właściwość popup wartością default_popup (musi być to teraz ciąg znaków).
Czy używasz właściwości chrome.self?
Zastąp chrome.extension.
Czy używasz właściwości Port.tab?
Zastąp Port.sender.
Czy korzystasz z interfejsów API chrome.extension.getTabContentses() lub chrome.extension.getExtensionTabs()?
Zastąp chrome.extension.getViews( { "type" : "tab" } ).
Czy Twoje 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.
Aby przekształcić stronę z tłem w stronę zdarzenia, dodaj usługę persistent i ustaw ją na false.

Lista kontrolna zmian zabezpieczeń

Czy na stronach HTML używasz bloków skryptu wbudowanego?
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 zamiast nich użyj addEventListener().
Czy Twoje rozszerzenie wstrzykuje skrypty dotyczące zawartości na strony internetowe, które muszą mieć dostęp do zasobów (np. obrazów i skryptów) zawartych w pakiecie rozszerzenia?
Zdefiniuj właściwość web_accessible_resources i wymień zasoby (oraz opcjonalnie osobne zasady bezpieczeństwa treści dla tych zasobów).
Czy Twoje rozszerzenie umieszcza w witrynie strony internetowe z zewnątrz?
Zdefiniuj właściwość sandbox.
Czy Twój kod lub biblioteka używa funkcji eval(), new Function(), innerHTML, setTimeout() lub przekazuje w inny sposób ciągi kodu JS, które są oceniane dynamicznie?
Użyj funkcji JSON.parse(), jeśli chcesz przeanalizować kod JSON i przekształcić go w obiekt.
Użyj biblioteki zgodnej z CSP, np. AngularJS.
Utwórz w pliku manifestu wpis dotyczący piaskownicy i uruchom odpowiedni kod w piaskownicy, używając do komunikacji z taką stroną wartościpostMessage().
Czy wczytujesz kod zewnętrzny, np. jQuery lub Google Analytics?
Możesz pobrać bibliotekę i zapakować ją w rozszerzeniu, a potem załadować z lokalnego pakietu.
Umieść domenę HTTPS, która udostępnia zasób, na liście dozwolonych w części „content_security_policy” w pliku manifestu.

Podsumowanie zmian w interfejsie API

Manifest w wersji 2 wprowadza kilka zmian w interfejsach API akcji w przeglądarce i akcji na stronie oraz zastępuje kilka starszych interfejsów API nowszymi.

Zmiany w działaniach przeglądarki

Interfejs API czynności w przeglądarce wprowadza pewne zmiany nazw:

Właściwości browser_actions i chrome.browserActions zostały zastąpione ich odpowiednikami w rodzaju żeńskim browser_action i chrome.browserAction.
W ramach starej usługi browser_actions istniały usługi icons, name i popup. Zostały one zastąpione przez:
default_icon dla plakietki ikony czynności w przeglądarce
default_name – tekst, który wyświetla się w etykietce po najechaniu kursorem na plakietkę.
default_popup dla strony HTML, która reprezentuje interfejs działania w przeglądarce (musi to być teraz ciąg znaków, a nie obiekt);

Zmiany w działaniach na stronach

Podobnie jak w przypadku działań w przeglądarce, interfejs API działań na stronie również uległ zmianie:

Właściwości page_actions i chrome.pageActions zostały zastąpione ich odpowiednikami w rodzaju mianownika page_action i chrome.pageAction.
W ramach starej usługi page_actions istniały usługi icons, name i popup. Te elementy zostały zastąpione przez:
default_icon dla ikony plakietki czynności na stronie
default_name – tekst, który wyświetla się w etykietce po najechaniu kursorem na plakietkę.
default_popup dla strony HTML, która reprezentuje interfejs działania strony (musi to być teraz ciąg znaków, nie obiekt);

Usuwane i zmieniane interfejsy API

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

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

Podsumowanie zmian dotyczących zabezpieczeń

Przejście z wersji 1 na wersję 2 pliku manifestu wiąże się z kilkoma zmianami dotyczącymi zabezpieczeń. Wiele z tych zmian wynika z wdrożenia w Chrome Zasad bezpieczeństwa treści. Aby dowiedzieć się więcej o tych zasadach, zapoznaj się z nimi.

Zabronione skrypty i moduły obsługi zdarzeń

Ze względu na stosowanie standardu Content Security Policy nie możesz już używać tagów <script> wstawianych w treści HTML. Należy je przenieść do zewnętrznych plików JS. Ponadto nie są obsługiwane też wbudowane moduły obsługi zdarzeń. Załóżmy na przykład, że w Twoim rozszerzeniu znajduje się ten kod:

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

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

Podobnie nie będą się wykonywać wbudowane moduły obsługi zdarzeń, które są powszechnie używaną i wygodną funkcją dla wielu programistów stron internetowych. Oto kilka przykładów:

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

Nie będą one działać w rozszerzeniach na platformie Manifest V2. Usuń moduły obsługi zdarzeń w źródle, umieść je w zewnętrznym pliku JS i zamiast tego użyj funkcji addEventListener(). Na przykład w kodzie JS użyj:

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

To znacznie czystszy sposób oddzielania działania rozszerzenia od jego znaczników interfejsu użytkownika.

Umieszczenie treści

W niektórych przypadkach rozszerzenie może zawierać treści, które mogą być używane zewnętrznie lub pochodzą z zewnętrznego źródła.

Treści rozszerzenia w witrynach internetowych: jeśli rozszerzenie umieszcza w witrynach internetowych zasoby (np. obrazy, skrypty, style CSS), które są używane w skryptach treści, musisz użyć właściwości web_accessible_resources, aby dodać te zasoby do listy dozwolonych, aby mogły z nich korzystać zewnętrzne strony internetowe:

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

Wstawianie treści zewnętrznych: zasady Content Security Policy zezwalają na wczytywanie tylko lokalnych skryptów i obiektów z Twojego pakietu, co uniemożliwia zewnętrznym atakującym wprowadzanie nieznanego kodu do Twojego rozszerzenia. Czasami jednak zdarza się, że chcesz wczytać zasoby obsługiwane zewnętrznie, takie jak jQuery czy kod Google Analytics. Można to zrobić na dwa sposoby:

Pobierz odpowiednią bibliotekę lokalnie (np. jQuery) i zapakuj ją z rozszerzeniem.
Możesz ograniczyć zakres działania CSP, dodając do listy dozwolonych źródeł HTTPS w sekcji „content_security_policy” w pliku manifestu. Aby uwzględnić bibliotekę, taką jak Google Analytics:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Korzystanie z dynamicznej oceny skryptu

Jedną z największych zmian w nowym schemacie pliku manifestu v2 jest to, że rozszerzenia nie mogą już używać dynamicznych technik oceny skryptu, takich jak eval() czy nowa Function(), ani przekazywać ciągów kodu JS do funkcji, które powodują użycie eval(), takich jak setTimeout(). Co więcej, niektóre powszechnie używane biblioteki JavaScript, takie jak Mapy Google i niektóre biblioteki szablonów, korzystają z tych technik.

Chrome udostępnia piaskownicę, w której strony mogą działać w ramach własnego źródła, co uniemożliwia im dostęp do chrome.* interfejsów API, Aby móc korzystać z usług eval() i podobnych w ramach nowych zasad bezpieczeństwa treści:

Utwórz w pliku manifestu wpis dotyczący piaskownicy.
W pliku z sandboxem podaj listę stron, które mają być uruchamiane w sandboxu.
Aby komunikować się ze stroną w piaskownicy, używaj przekazywania wiadomości za pomocą postMessage().

Więcej informacji na ten temat znajdziesz w dokumentacji dotyczącej oceny sandboxa.

Więcej informacji

Zmiany w pliku manifestu w wersji 2 mają na celu ułatwienie deweloperom tworzenia bezpieczniejszych i solidniej zaprojektowanych rozszerzeń i aplikacji. Pełną listę zmian między wersją 1 a 2 pliku manifestu znajdziesz w dokumentacji dotyczącej pliku manifestu. Więcej informacji o używaniu piaskownicy do izolowania niebezpiecznego kodu znajdziesz w artykule Ocena piaskownicy. Więcej informacji o zasadach bezpieczeństwa treści znajdziesz w naszym samouczku dotyczącym rozszerzeń oraz w dobrym wprowadzeniu na stronie HTML5Rocks.