Aggiunta di contenuto PDF in AIR

Adobe AIR 1.0 e versioni successive

Le applicazioni eseguite in Adobe® AIR® possono eseguire il rendering non soltanto del contenuto SWF e HTML, ma anche del contenuto PDF. Le applicazioni AIR eseguono il rendering del contenuto PDF usando la classe HTMLLoader, il motore WebKit e il plug-in per browser Adobe® Reader®. In un'applicazione AIR, il contenuto PDF può estendersi per tutta l'altezza e la larghezza dell'applicazione o, in alternativa, può rappresentare una porzione dell'interfaccia. Il plug-in per browser Adobe Reader controlla la visualizzazione dei file PDF in un'applicazione AIR, pertanto le modifiche apportate all'interfaccia delle barre degli strumenti di Reader (relative, ad esempio, a posizione, ancoraggio e visibilità) persistono nelle visualizzazioni successive dei file PDF, sia nelle applicazioni AIR che nel browser.

Importante: per eseguire il rendering del contenuto PDF in AIR, l'utente deve avere installato Adobe Reader o Adobe® Acrobat® versione 8.1 o superiore.

Rilevamento della funzionalità PDF

Se l'utente non dispone di una versione di Adobe Reader o Adobe Acrobat 8.1 o superiore, il contenuto PDF non verrà visualizzato in un'applicazione AIR. Per verificare se un utente sia o meno in grado di eseguire il rendering del contenuto PDF, per prima cosa controllate la proprietà HTMLLoader.pdfCapability. Questa proprietà è impostata su una delle seguenti costanti della classe HTMLPDFCapability:

Costante

Descrizione

HTMLPDFCapability.STATUS_OK

È stata rilevata una versione adeguata (8.1 o superiore) di Adobe Reader e il contenuto PDF può essere caricato in un oggetto HTMLLoader.

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

Non è stata rilevata nessuna versione di Adobe Reader. Un oggetto HTMLLoader non è in grado di visualizzare il contenuto PDF.

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

È stato rilevato Adobe Reader, ma la versione non è sufficientemente aggiornata. Un oggetto HTMLLoader non è in grado di visualizzare il contenuto PDF.

HTMLPDFCapability.ERROR_PREFERRED_READER_TOO_OLD

È stata rilevata una versione adeguata (8.1 o successiva) di Adobe Reader, tuttavia la versione di Adobe Reader che è configurata per la gestione del contenuto PDF è antecedente a Reader 8.1. Un oggetto HTMLLoader non è in grado di visualizzare il contenuto PDF.

In Windows, se nel sistema dell'utente è in esecuzione Adobe Acrobat o Adobe Reader versione 7.x o superiore, verrà usata questa versione anche se è installata una versione successiva che supporta il caricamento del contenuto PDF. In questo caso, se il valore della proprietà pdfCapability è HTMLPDFCapability.STATUS_OK, quando un'applicazione AIR tenta di caricare il contenuto PDF, la versione precedente di Acrobat o di Reader visualizza un avviso (ma non vengono generate eccezioni nell'applicazione AIR). Se è possibile che si verifichi questa situazione per gli utenti finali, informateli della necessità di chiudere Acrobat mentre è in esecuzione la vostra applicazione. Queste istruzioni dovrebbero essere visualizzate quando il caricamento del contenuto PDF non viene completato entro un determinato periodo di tempo.

In Linux, AIR cerca Adobe Reader nella proprietà PATH esportata dall'utente (se contiene il comando acroread) e nella directory /opt/Adobe/Reader.

Il codice seguente rileva se un utente può visualizzare contenuto PDF in un'applicazione AIR. Se l'utente non può visualizzare PDF, il codice tiene traccia del codice di errore che corrisponde all'oggetto errore HTMLPDFCapability:

if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK)  
{ 
    trace("PDF content can be displayed"); 
} 
else  
{ 
    trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability); 
} 

Caricamento di contenuto PDF

È possibile aggiungere un PDF a un'applicazione AIR creando un'istanza HTMLLoader, impostandone le dimensioni e caricando il percorso di un PDF.

L'esempio seguente carica un PDF da un sito esterno. Specificate per URLRequest il percorso di un PDF esterno disponibile.

var request:URLRequest = new URLRequest("http://www.example.com/test.pdf"); 
pdf = new HTMLLoader(); 
pdf.height = 800; 
pdf.width = 600; 
pdf.load(request); 
container.addChild(pdf);

Potete inoltre caricare il contenuto da URL di file e schermi URL specifici di AIR, quali app e app-storage. Ad esempio, il seguente codice carica il file test.pdf presente nella sottodirectory dei PDF nella directory dell'applicazione:

app:/js_api_reference.pdf

Per ulteriori informazioni sugli schemi URL di AIR, vedete Schemi URI.

Uso di script nel contenuto PDF

Potete usare JavaScript per controllare il contenuto PDF esattamente come fareste in una pagina Web nel browser.

Le estensioni JavaScript in Acrobat forniscono le funzioni seguenti, tra le altre:

  • Controllo della navigazione e dell'ingrandimento della pagina

  • Elaborazione dei form all'interno del documento

  • Controllo degli eventi multimediali

I dettagli completi sulle estensioni JavaScript per Adobe Acrobat sono disponibili presso il Centro per sviluppatori Adobe Acrobat, all'indirizzo http://www.adobe.com/devnet/acrobat/javascript.html.

Nozioni di base sulla comunicazione HTML-PDF

Il codice JavaScript in una pagina HTML può inviare un messaggio al codice JavaScript nel contenuto PDF richiamando il metodo postMessage() dell'oggetto DOM che rappresenta il contenuto PDF. Analizzate, ad esempio, il seguente contenuto PDF incorporato:

<object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/>

Il seguente codice JavaScript nel contenuto HTML che lo contiene invia un messaggio al codice JavaScript nel file PDF:

pdfObject = document.getElementById("PDFObj"); 
pdfObject.postMessage(["testMsg", "hello"]);

Il file PDF può includere codice JavaScript per ricevere questo messaggio. Potete aggiungere codice JavaScript ai file PDF in alcuni contesti, tra i quali i contesti a livello di documento, cartella, pagina, campo e batch. In questa sede tratteremo soltanto il contesto a livello di documento, che definisce gli script che vengono valutati all'apertura del documento PDF.

Un file PDF può aggiungere una proprietà messageHandler all'oggetto hostContainer. La proprietà messageHandler è un oggetto che definisce le funzioni di gestore per rispondere ai messaggi. Ad esempio, il seguente codice definisce la funzione di gestione dei messaggi che il file PDF riceve dal contenitore host (in pratica il contenuto HTML che incorpora il file PDF):

this.hostContainer.messageHandler = {onMessage: myOnMessage}; 
 
function myOnMessage(aMessage) 
{ 
    if(aMessage[0] == "testMsg") 
    { 
        app.alert("Test message: " + aMessage[1]); 
    } 
    else 
    { 
        app.alert("Error"); 
    } 
}

Il codice JavaScript nella pagina HTML può richiamare il metodo postMessage() dell'oggetto PDF contenuto nella pagina. Richiamando questo metodo, viene inviato un messaggio ("Hello from HTML") al codice JavaScript del livello documento nel file PDF:

<html> 
    <head> 
    <title>PDF Test</title> 
    <script> 
        function init() 
        { 
            pdfObject = document.getElementById("PDFObj"); 
            try { 
                 pdfObject.postMessage(["alert", "Hello from HTML"]); 
            } 
            catch (e) 
            { 
                alert( "Error: \n name = " + e.name + "\n message = " + e.message ); 
            } 
        } 
    </script> 
    </head> 
    <body onload='init()'> 
        <object 
            id="PDFObj" 
            data="test.pdf" 
            type="application/pdf" 
            width="100%" height="100%"/> 
    </body> 
</html>

Per un esempio più dettagliato e per ulteriori informazioni sull'uso di Acrobat 8 per aggiungere codice JavaScript a un file PDF, vedete Cross-scripting PDF content in Adobe AIR (Scambio di script per il contenuto PDF in Adobe AIR).

Script di ActionScript nel contenuto PDF

Il codice ActionScript (nel contenuto SWF) non comunica direttamente con il codice JavaScript nel contenuto PDF. Tuttavia il codice ActionScript può comunicare con il codice JavaScript nella pagina HTML caricata in un oggetto HTMLLoader che carica il contenuto PDF, pertanto quel codice JavaScript può comunicare con il codice JavaScript nel file PDF. Per ulteriori informazioni, consultate Programmazione di HTML e JavaScript in AIR.

Limiti noti per il contenuto PDF in AIR

Il contenuto PDF in Adobe AIR presenta i seguenti limiti:

  • Il contenuto PDF non viene visualizzato in una finestra (un oggetto NativeWindow) che sia trasparente (la cui proprietà transparent è impostata su true).

  • L'ordine di visualizzazione di un file PDF è diverso rispetto ad altri oggetti visualizzati in un'applicazione AIR. Sebbene il contenuto PDF venga ritagliato correttamente in base all'ordine di visualizzazione HTML, resterà sempre in primo piano nell'ordine di visualizzazione del contenuto nell'applicazione AIR.

  • Se determinate proprietà visive di un oggetto HTMLLoader che contiene un documento PDF vengono modificate, il documento PDF diventa invisibile. Tali proprietà comprendono: filters, alpha, rotatione scaling. La modifica di queste proprietà rende invisibile il contenuto PDF, finché non saranno ripristinate. Lo stesso vale per la modifica di queste proprietà per i contenitori dell'oggetto Display che contengono l'oggetto HTMLLoader.

  • Il contenuto PDF è visibile solo quando la proprietà scaleMode dell'oggetto Stage dell'oggetto NativeWindow che include il contenuto PDF è impostata su StageScaleMode.NO_SCALE. Quando è impostata su qualsiasi altro valore, il contenuto PDF non è visibile.

  • Facendo clic sui collegamenti al contenuto all'interno del file PDF verrà aggiornata la posizione di scorrimento del contenuto PDF. Facendo clic sui collegamenti al contenuto all'esterno del file PDF verrà reindirizzato l'oggetto HTMLLoader che contiene il PDF (anche se la destinazione di un collegamento è una nuova finestra).

  • I flussi di lavoro dei commenti PDF non funzionano in AIR.