Questa pagina è stata tradotta dall'API Cloud Translation.

Tutorial: migrazione a Manifest V2

La versione 1 del file manifest è stata deprecata in Chrome 18 e il supporto verrà gradualmente eliminato in base alla pianificazione dell'assistenza per la versione 1. Le modifiche dalla versione 1 alla versione 2 rientrano in due categorie generiche: modifiche all'API e modifiche alla sicurezza.

Questo documento fornisce elenchi di controllo per la migrazione delle estensioni di Chrome dalla versione 1 alla versione 2 del file manifest, seguiti da riepiloghi più dettagliati sul significato di queste modifiche e sul motivo per cui sono state apportate.

Elenco di controllo delle modifiche all'API

Stai utilizzando la proprietà browser_actions o l'API chrome.browserActions?
Sostituisci browser_actions con la proprietà browser_action singola.
Sostituisci chrome.browserActions con chrome.browserAction.
Sostituisci la proprietà icons con default_icon.
Sostituisci la proprietà name con default_title.
Sostituisci la proprietà popup con default_popup (e ora deve essere una stringa).
Stai utilizzando la proprietà page_actions o l'API chrome.pageActions?
Sostituisci page_actions con page_action.
Sostituisci chrome.pageActions con chrome.pageAction.
Sostituisci la proprietà icons con default_icon.
Sostituisci la proprietà name con default_title.
Sostituisci la proprietà popup con default_popup (e ora deve essere una stringa).
Stai utilizzando la proprietà chrome.self?
Sostituisci con chrome.extension.
Stai utilizzando la proprietà Port.tab?
Sostituisci con Port.sender.
Utilizzi le API chrome.extension.getTabContentses() o chrome.extension.getExtensionTabs()?
Sostituisci con chrome.extension.getViews( { "type" : "tab" } ).
L'estensione utilizza una pagina in background?
Sostituisci la proprietà background_page con una proprietà background.
Aggiungi una proprietà scripts o page contenente il codice della pagina.
Aggiungi una proprietà persistent e impostala su false per convertire la tua pagina di sfondo in una pagina evento

Elenco di controllo delle modifiche di sicurezza

Utilizzi blocchi di script incorporati nelle pagine HTML?
Rimuovi il codice JS contenuto all'interno dei tag <script> e posizionalo in un file JS esterno.
Utilizzi gestori di eventi incorporati (come onclick e così via)?
Rimuovili dal codice HTML, spostali in un file JS esterno e utilizza invece addEventListener().
L'estensione inserisce script di contenuti nelle pagine web che devono accedere alle risorse (come immagini e script) contenute nel pacchetto dell'estensione?
Definisci la proprietà web_accessible_resources ed elenca le risorse (e, facoltativamente, un criterio di sicurezza del contenuto separato per queste risorse).
L'estensione incorpora pagine web esterne?
Definisci la proprietà sandbox.
Il tuo codice o la tua libreria utilizza eval(), il nuovo Function(), innerHTML, setTimeout() o altrimenti passa stringhe di codice JS valutate dinamicamente?
Utilizza JSON.parse() se analizziamo il codice JSON in un oggetto.
Utilizza una libreria compatibile con CSP, ad esempio AngularJS.
Crea una voce sandbox nel manifest ed esegui il codice interessato nella sandbox, utilizzando postMessage() per comunicare con la pagina con sandbox.
Stai caricando un codice esterno, ad esempio jQuery o Google Analytics?
Potresti scaricare la libreria e pacchettizzarla nell'estensione, quindi caricarla dal pacchetto locale.
Inserisci il dominio HTTPS che gestisce la risorsa nella lista consentita nella parte "content_security_policy" del file manifest.

Riepilogo delle modifiche all'API

La versione 2 del file manifest introduce alcune modifiche alle API di azione e di azione sulle pagine del browser e sostituisce alcune API precedenti con altre più recenti.

Modifiche alle azioni del browser

L'API delle azioni del browser introduce alcune modifiche ai nomi:

Le proprietà browser_actions e chrome.browserActions sono state sostituite con le rispettive controparti singolari browser_action e chrome.browserAction.
Nella precedente proprietà browser_actions, erano presenti icons, name e popup proprietà. Questi campi sono stati sostituiti con:
default_icon per l'icona del badge di azione del browser
default_name per il testo che compare nella descrizione comando quando passi il mouse sopra il badge.
default_popup per la pagina HTML che rappresenta l'interfaccia utente per l'azione del browser (che ora deve essere una stringa, non può essere un oggetto)

Modifiche alle azioni nelle pagine

Analogamente alle modifiche relative alle azioni del browser, anche l'API Page actions è cambiata:

Le proprietà page_actions e chrome.pageActions sono state sostituite dalle rispettive controparti singolari page_action e chrome.pageAction.
Nella precedente proprietà page_actions, erano presenti icons, name e popup proprietà. Questi campi sono stati sostituiti con:
default_icon per l'icona del badge di azione sulla pagina
default_name per il testo che compare nella descrizione comando quando passi il mouse sopra il badge.
default_popup per la pagina HTML che rappresenta l'interfaccia utente per l'azione pagina (che ora deve essere una stringa, non può essere un oggetto)

API rimosse e modificate

Alcune API di estensione sono state rimosse e sostituite con nuove controparti:

La proprietà background_page è stata sostituita da background.
La proprietà chrome.self è stata rimossa. Utilizza chrome.extension.
La proprietà Port.tab è stata sostituita con Port.sender.
Le API chrome.extension.getTabContentses() e chrome.extension.getExtensionTabs() sono state sostituite da chrome.extension.getViews( { "type" : "tab" } ).

Riepilogo delle modifiche alla sicurezza

Sono state apportate diverse modifiche relative alla sicurezza al passaggio dalla versione 1 del file manifest alla versione 2. Molte di queste modifiche derivano dall'adozione da parte di Chrome dei Criteri di sicurezza del contenuto; ti consigliamo di consultare ulteriori informazioni su questo criterio per comprenderne le implicazioni.

Script in linea e gestori di eventi non consentiti

Per via dell'uso dei criteri di sicurezza del contenuto, non è più possibile utilizzare i tag <script> incorporati nei contenuti HTML. Questi file devono essere spostati in file JS esterni. Inoltre, non sono supportati nemmeno i gestori di eventi incorporati. Ad esempio, supponiamo che l'estensione contenga il seguente codice:

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

Questo codice causerebbe un errore in fase di runtime. Per risolvere il problema, sposta i contenuti del tag <script> in file esterni e fai riferimento a questi contenuti con un attributo src='path_to_file.js'.

Analogamente, non vengono eseguiti i gestori di eventi incorporati, che sono una funzionalità comune a scopo di occorrenza e convenienza usata da molti sviluppatori web. Ad esempio, considera istanze comuni come:

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

Non funzionano nelle estensioni Manifest V2. Rimuovi i gestori di eventi incorporati, posizionali nel tuo file JS esterno e utilizza addEventListener() per registrare i gestori di eventi. Ad esempio, nel codice JS utilizza:

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

Si tratta di un modo molto più chiaro per separare il comportamento dell'estensione dal markup dell'interfaccia utente.

Incorporamento dei contenuti

Ci sono alcuni scenari in cui l'estensione potrebbe incorporare contenuti che possono essere utilizzati esternamente o provenienti da una fonte esterna.

Contenuti delle estensioni nelle pagine web: se l'estensione incorpora risorse (ad esempio immagini, script, stili CSS e così via) utilizzate in script di contenuti inseriti in pagine web, devi utilizzare la proprietà web_accessible_resources per inserire queste risorse nella lista consentita in modo che le pagine web esterne possano utilizzarle:

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

Incorporamento di contenuti esterni: i criteri di sicurezza del contenuto consentono di caricare dal tuo pacchetto solo script e oggetti locali; ciò impedisce a utenti malintenzionati esterni di introdurre codice sconosciuto nella tua estensione. Tuttavia, in alcuni casi vuoi caricare risorse pubblicate esternamente, ad esempio jQuery o codice di Google Analytics. Esistono due metodi per effettuare questa operazione:

Scaricare la libreria pertinente in locale (come jQuery) e pacchettizzarla con la tua estensione.
Puoi allentare il CSP in modo limitato inserendo le origini HTTPS nella sezione "content_security_policy" del tuo manifest. Per includere una libreria come Google Analytics, puoi adottare questo approccio:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Utilizzo della valutazione dinamica degli script

Forse una delle principali modifiche nel nuovo schema manifest v2 è che le estensioni non possono più usare tecniche di valutazione degli script dinamici come eval() o il nuovo Function(), né passare stringhe di codice JS a funzioni che faranno usare un eval(), come setTimeout(). Inoltre, è noto che alcune librerie JavaScript comunemente utilizzate, come Google Maps e alcune librerie di modelli, utilizzano alcune di queste tecniche.

Chrome fornisce una sandbox per le pagine da eseguire nella propria origine, a cui viene negato l'accesso a Chrome.* API Per utilizzare eval() e simili ai sensi dei nuovi criteri di sicurezza del contenuto:

Crea una voce sandbox nel file manifest.
Nella voce della sandbox, elenca le pagine che vuoi eseguire.
Utilizza la trasmissione dei messaggi tramite postMessage() per comunicare con la pagina con sandbox.

Per ulteriori dettagli su come eseguire questa operazione, consulta la documentazione relativa a Sandboxing Eval.

Per approfondire

Le modifiche alla versione 2 del file manifest sono progettate per guidare gli sviluppatori verso la creazione di app e estensioni più sicure e con un'architettura più solida. Per visualizzare un elenco completo delle modifiche dalla versione 1 del file manifest alla versione 2, consulta la documentazione relativa al file manifest. Per ulteriori informazioni sull'utilizzo della limitazione tramite sandbox per isolare il codice non sicuro, leggi l'articolo sulla valutazione del sandboxing. Puoi ottenere ulteriori informazioni sui criteri di sicurezza dei contenuti visitando il nostro tutorial relativo alle estensioni e un'ottima introduzione a HTML5Rocks.