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 al pianificazione del supporto della versione 1 di manifest. Le modifiche dalla versione 1 alla versione 2 rientrano in due categorie ampie: modifiche API e modifiche alla sicurezza.

Questo documento fornisce gli elenchi di controllo per eseguire la migrazione delle estensioni di Chrome dalla versione 1 del file manifest alla versione versione 2, seguita 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 singola proprietà browser_action.
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.
Stai usando l'chrome.extension.getTabContentses() o chrome.extension.getExtensionTabs() API?
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 pagina di sfondo in un evento pagina

Elenco di controllo per le modifiche alla sicurezza

Stai utilizzando blocchi di script incorporati nelle pagine HTML?
Rimuovi il codice JS contenuto nei tag <script> e posizionalo all'interno di un file JS esterno.
Utilizzi gestori di eventi in linea (come clic e così via)?
Rimuovile dal codice HTML, spostale in un file JS esterno e utilizza addEventListener() .
L'estensione inserisce script di contenuti nelle pagine web che devono accedere a risorse (come immagini e script) contenuti nel pacchetto dell'estensione?
Definisci la proprietà web_accessible_resources ed elenca le risorse (e, facoltativamente, un file criteri di sicurezza del contenuto separati per queste risorse).
L'estensione incorpora pagine web esterne?
Definisci la proprietà sandbox.
Il tuo codice o la tua libreria sta utilizzando eval(), i nuovi Function(), innerHTML, setTimeout() oppure altrimenti passare le stringhe di codice JS valutate dinamicamente?
Utilizza JSON.parse() se stai analizzando il codice JSON in un oggetto.
Utilizza una libreria compatibile con CSP, ad esempio AngularJS.
Crea una voce sandbox nel file manifest ed esegui il codice interessato nella sandbox utilizzando postMessage() per comunicare con la pagina con sandbox.
Stai caricando codice esterno, ad esempio jQuery o Google Analytics?
Potresti scaricare la libreria e pacchettizzarla nell'estensione, quindi caricarla dal pacchetto locale.
Aggiungi il dominio HTTPS alla lista consentita che pubblica la risorsa in "content_security_policy" parte del tuo del file manifest.

Riepilogo delle modifiche all'API

La versione 2 del file manifest introduce alcune modifiche alle API delle azioni del browser e delle azioni sulle pagine e sostituisce alcune API vecchie con quelle più recenti.

Modifiche alle azioni del browser

L'API browser actions introduce alcune modifiche alla denominazione:

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

Modifiche alle azioni sulle pagine

Analogamente alle modifiche per le azioni del browser, anche l'API page actions è stata modificata:

Le proprietà page_actions e chrome.pageActions sono state sostituite con il loro singolare page_action e chrome.pageAction.
Nella precedente proprietà page_actions, erano presenti proprietà icons, name e popup. Questi sono stati sostituiti con:
default_icon per l'icona del badge delle azioni sulla pagina
default_name per il testo che appare nella descrizione comando quando passi il mouse sopra il badge.
default_popup per la pagina HTML che rappresenta l'interfaccia utente per l'azione della pagina (che ora deve essere non è un oggetto)

API rimosse e modificate

Alcune API di estensioni 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() hanno è stato sostituito da chrome.extension.getViews( { "type" : "tab" } ).

Riepilogo delle modifiche alla sicurezza

Sono state apportate una serie di modifiche relative alla sicurezza che accompagnano il passaggio dalla versione manifest 1 alla la versione 2. Molte di queste modifiche derivano dall'adozione da parte di Chrome dei Criteri di sicurezza del contenuto. tu consulta maggiori informazioni su queste norme per comprenderne le implicazioni.

Script e gestori di eventi in linea non consentiti

A causa dell'utilizzo dei criteri di sicurezza del contenuto, non puoi più utilizzare tag <script> incorporati con i contenuti HTML. Questi elementi devono essere spostati in file JS esterni. Inoltre, i gestori di eventi in linea non sono supportati. Ad esempio, supponiamo che la tua estensione contenga il seguente codice:

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

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

Analogamente, i gestori di eventi in linea, che sono una caratteristica comune di occorrenza e convenienza usata da molti per gli sviluppatori web. Ad esempio, considera istanze comuni quali:

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

Non funzioneranno nelle estensioni Manifest V2. Rimuovi i gestori di eventi in linea e posizionali nella JS esterno e usa invece addEventListener() per registrare i gestori di eventi. Per esempio, nel codice JS, utilizza:

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

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

Incorporamento di contenuti

In alcuni casi l'estensione potrebbe incorporare contenuti utilizzabili esternamente o provengono da una sorgente esterna.

Contenuti delle estensioni nelle pagine web: Se l'estensione incorpora risorse (ad esempio immagini, script, stili CSS e così via) utilizzate nei contenuti script inseriti nelle 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"
  ],
...
}

Incorporare contenuti esterni: Il criterio di sicurezza del contenuto consente il caricamento dal pacchetto solo di script e oggetti locali, impedisce a utenti malintenzionati esterni di introdurre codice sconosciuto nella tua estensione. Tuttavia, ci sono volte in cui vuoi caricare risorse pubblicate esternamente, come jQuery o codice di Google Analytics. Puoi utilizzare due metodi:

Scarica la libreria pertinente in locale (ad esempio jQuery) e pacchettizzala con l'estensione.
Puoi allentare il CSP in modo limitato inserendo le origini HTTPS nella lista consentita nel "content_security_policy" del file manifest. Per includere una libreria come Google Analytics, questo è l'approccio da adottare:
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Utilizzo della valutazione degli script dinamici

Forse una delle principali modifiche al nuovo schema manifest v2 è che le estensioni utilizzare tecniche di valutazione degli script dinamici come eval() o il nuovo Function(), oppure passare stringhe di codice JS alle funzioni che causeranno l'utilizzo di un valore eval(), come setTimeout(). Inoltre, alcuni Le librerie JavaScript di uso comune, come Google Maps e alcune librerie di modelli, sono note di utilizzare alcune di queste tecniche.

Chrome mette a disposizione una sandbox per l'esecuzione delle pagine all'origine, a cui viene negato l'accesso a Chrome.* API Per utilizzare eval() e simili nel nuovo criterio di sicurezza del contenuto:

Crea una voce sandbox nel file manifest.
Nella voce della sandbox, elenca le pagine da eseguire nella sandbox.
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 sulla valutazione della sandbox.

Per approfondire

Le modifiche nella versione 2 del file manifest sono state concepite per guidare gli sviluppatori verso uno sviluppo più sicuro estensioni e app con un'architettura solida. Per visualizzare un elenco completo delle modifiche rispetto alla versione 1 del file manifest alla versione 2, consulta la documentazione relativa al file manifest. Per ulteriori informazioni sull'utilizzo della sandbox per isolare il codice non sicuro, leggi l'articolo sulla valutazione della sandbox. Puoi scoprire di più sui contenuti Sicurezza, visitando il nostro tutorial relativo alle estensioni e un'introduzione utile a HTML5Rocks.