Ajout d’un contenu PDF dans AIR

Adobe AIR 1.0 et les versions ultérieures

Les applications qui s’exécutent sous Adobe® AIR® peuvent non seulement créer un contenu SWF ou HTML, mais également un contenu PDF. Les applications AIR créent un contenu PDF à l’aide de la classe HTMLLoader, du moteur WebKit et du module d’extension du navigateur Adobe® Reader®. Dans une application AIR, le contenu PDF peut s’étendre sur toute la hauteur et toute la largeur de votre application ou bien sur une partie de l’interface. Les contrôles du module d’extension du navigateur Adobe Reader affichent les fichiers PDF dans une application AIR. Les modifications apportées à l’interface de la barre d’outils de Reader (les contrôles de position, d’ancrage et de visibilité, par exemple) sont réactivées lors de l’affichage ultérieur de fichiers PDF dans les applications AIR et le navigateur.

Important : pour afficher un contenu PDF dans AIR, l’utilisateur doit avoir installé Adobe Reader ou Adobe® Acrobat® version 8.1 (ou une version ultérieure).

Détection des capacités PDF

Si l’utilisateur ne dispose pas d’Adobe Reader ou d’Adobe Acrobat 8.1 ou ultérieur, le contenu PDF ne s’affiche pas dans une application AIR. Pour vous rendre compte si un utilisateur est en mesure de produire un contenu PDF, il faut d’abord vérifier la propriété HTMLLoader.pdfCapability. Elle est définie sur l’une des constantes suivantes de la classe HTMLPDFCapability :

Constante

Description

HTMLPDFCapability.STATUS_OK

Une version appropriée (8.1 ou plus récente) d’Adobe Reader a été décelée et le contenu PDF peut être chargé dans un objet HTMLLoader.

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

Aucune version d’Adobe Reader n’a été décelée. Un objet HTMLLoader n’est pas en mesure d’afficher le contenu PDF.

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

Adobe Reader a bien été décelé, mais la version est périmée. Un objet HTMLLoader n’est pas en mesure d’afficher le contenu PDF.

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

Une version appropriée (8.1 ou plus récente) d’Adobe Reader a été détectée mais celle qui est configurée pour traiter le contenu PDF est plus ancienne que Reader 8.1. Un objet HTMLLoader n’est pas en mesure d’afficher le contenu PDF.

Sous Windows, si Adobe Acrobat ou Adobe Reader version 7.x (ou une version ultérieure) s’exécute sur le système de l’utilisateur, c’est cette version-là qui est utilisée, même si une version plus récente qui prend en charge les contenus PDF est installée. Dans ce cas, si la valeur de la propriété pdfCapability est HTMLPDFCapability.STATUS_OK, lorsqu’une application AIR tente de charger un contenu PDF, la version la plus ancienne d’Acrobat ou de Reader affiche un message d’avertissement et aucune exception n’est renvoyée dans l’application AIR. Si cette situation est susceptible de se produire chez vos utilisateurs finaux, pensez à leur fournir des instructions pour qu’ils quittent Acrobat tandis qu’ils exécutent leur application. Vous pourriez afficher ces instructions si le contenu PDF ne se charge pas dans un délai raisonnable.

Sous Linux, AIR recherche Adobe Reader dans le chemin exporté par l’utilisateur (s’il contient la commande acroread) et dans le répertoire /opt/Adobe/Reader.

Le code suivant détecte si un utilisateur est en mesure d’afficher les contenus PDF dans une application AIR. Si tel n’est pas le cas, le code recherche le code d’erreur correspondant à l’objet d’erreur HTMLPDFCapability :

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

Chargement du contenu PDF

Vous pouvez ajouter un PDF à une application AIR en créant une occurrence de HTMLLoader, en paramétrant ses dimensions et en chargeant le chemin d’un PDF.

L’exemple suivant charge un PDF à partir d’un site externe. Remplacez l’URLRequest par le chemin qui mène à un PDF externe disponible.

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);

Vous pouvez également charger du contenu depuis des modèles d’URL file et des modèles d’URL spécifiques à AIR, comme app et app-storage. Par exemple, le code suivant charge le fichier test.pdf dans le sous-répertoire du PDF contenu dans le répertoire de l’application :

app:/js_api_reference.pdf

Pour plus d’informations sur les modèles d'URL d'AIR, voir Modèles d’URI.

Programmation du contenu PDF

Vous pouvez utiliser JavaScript pour contrôler le contenu PDF de la même façon que vous le feriez dans une page Web du navigateur.

Les extensions JavaScript incorporées dans Acrobat fournissent les fonctions suivantes, entre autres :

  • Contrôle de la navigation et de l’agrandissement de la page

  • Traitement des formulaires au sein du document

  • Contrôle des événements multimédia

Des détails complets sur les extensions de JavaScript pour Adobe Acrobat se trouvent sur le site Adobe Acrobat Developer Connection à l’adresse http://www.adobe.com/devnet/acrobat/javascript.html.

Principes de communication HTML-PDF

JavaScript dans une page HTML peut envoyer un message à JavaScript dans un contenu PDF par un appel à la méthode postMessage() de l’objet DOM représentant le contenu PDF. Par exemple, examinez le contenu PDF intégré ci-dessous :

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

Le code JavaScript suivant dans le contenu HTML envoie un message au JavaScript du fichier PDF :

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

Le fichier PDF peut contenir JavaScript pour recevoir ce message. Vous pouvez ajouter du code JavaScript aux fichiers PDF dans certains contextes au niveau du document, du dossier, de la page, du champ ou du lot. Nous n’aborderons ici que le contexte au niveau du document, celui qui définit les scripts qui sont évalués lorsque le document PDF s’ouvre.

Un fichier PDF peut ajouter une propriété messageHandler à l’objet hostContainer. La propriété messageHandler est un objet qui définit les fonctions du gestionnaire pour répondre aux messages. Par exemple, le code ci-dessous définit la fonction appelée à répondre aux messages provenant du fichier PDF du conteneur hôte. Celui-ci constitue le contenu HTML qui a intégré le fichier PDF :

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

Le code JavaScript de la page HTML peut appeler la méthode postMessage() de l’objet PDF contenu dans la page. L’appel de cette méthode envoie un message "Hello from HTML" au JavaScript, au niveau du document, dans le fichier 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>

Pour consulter un exemple plus complexe, ainsi que des informations sur l’utilisation d’Acrobat 8 pour ajouter du code JavaScript à un fichier PDF, voir Programmation croisée du contenu PDF dans Adobe AIR.

Programmation du contenu PDF depuis ActionScript

Le code ActionScript (dans un contenu SWF) ne peut pas communiquer directement avec JavaScript dans un contenu PDF. Toutefois, ActionScript peut communiquer avec le JavaScript de la page HTML chargée dans un objet HTMLLoader qui charge le contenu PDF. Ce code JavaScript peut communiquer avec le JavaScript dans le fichier PDF chargé. Pour plus d’informations, voir Programmation HTML et JavaScript dans AIR.

Limites connues pour du contenu PDF dans AIR

Le contenu PDF dans Adobe AIR a les limites suivantes :

  • Le contenu PDF ne peut pas s’afficher dans une fenêtre (un objet NativeWindow) qui est transparente et où la propriété transparent est définie sur true.

  • L’ordre d’affichage d’un fichier PDF s’effectue différemment que les autres objets à afficher dans une application AIR. Bien que le contenu PDF se découpe correctement en respectant l’ordre d’affichage HTML, il s’installera toujours par-dessus le contenu dans l’ordre d’affichage de l’application AIR.

  • Si certaines propriétés visuelles de l’objet HTMLLoader contenant un document PDF sont modifiées, le document PDF devient invisible. Ces propriétés comprennent filters, alpha, rotation et scaling. Si vous modifiez ces propriétés, le contenu PDF devient invisible jusqu’à ce que vous les réinitialisez. Le contenu PDF est également invisible si vous modifiez ces propriétés dans les conteneurs d’objets d’affichage qui contiennent l’objet HTMLLoader.

  • Le contenu du PDF n’est visible que lorsque la propriété scaleMode de l’objet Stage de l’objet NativeWindow renfermant le contenu PDF est définie sur StageScaleMode.NO_SCALE. Lorsqu’elle est définie sur une autre valeur, le contenu PDF n’est pas visible.

  • Un clic sur des liens pointant vers le contenu au sein du fichier PDF met à jour la position de défilement du contenu PDF. Un clic sur des liens pointant vers le contenu hors d’un fichier PDF réoriente l’objet HTMLLoader qui contient le PDF, même si la cible d’un lien est une nouvelle fenêtre.

  • Les flux de commentaires PDF ne fonctionnent pas dans AIR.