Dodawanie treści PDF w środowisku AIR

Adobe AIR 1.0 i starsze wersje

Aplikacje działające w środowisku Adobe® AIR® mogą renderować nie tylko treść w formatach SWF i HTML, ale również treść w formacie PDF. Aplikacje AIR renderują treść PDF przy użyciu klasy HTMLLoader, mechanizmu WebKit oraz wtyczki Adobe® Reader® do przeglądarki. W aplikacji AIR treść PDF może być wyświetlana na całej wysokości i szerokości okna aplikacji lub jako fragment interfejsu. Wyświetlaniem plików PDF w aplikacji AIR zarządza wtyczka Adobe Reader zainstalowana w przeglądarce. Zmiany ustawień paska narzędzi programu Reader (np. jego położenie, zakotwiczenie i widoczność) są zachowywane i obowiązują przy kolejnym wyświetlaniu pliku PDF — zarówno w aplikacji AIR, jak i w przeglądarce.

Ważne: Aby móc renderować treść PDF w środowisku AIR, użytkownik musi mieć zainstalowany program Adobe Reader lub Adobe® Acrobat® w wersji 8.1 lub wyższej.

Wykrywanie możliwości dotyczących formatu PDF

Jeśli użytkownik nie ma zainstalowanego programu Adobe Reader lub Adobe Acrobat w wersji 8.1 lub wyższej, treść PDF nie będzie wyświetlana w aplikacji AIR. Aby wykryć, czy użytkownik może renderować treść PDF, należy sprawdzić wartość właściwości HTMLLoader.pdfCapability . Ta właściwość przyjmuje wartość równą jednej ze stałych klasy HTMLPDFCapability:

Stała

Opis

HTMLPDFCapability.STATUS_OK

Wykryto wymaganą wersję (8.1 lub wyższą) programu Adobe Reader i treść PDF może być ładowana do obiektu HTMLLoader.

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

Nie wykryto żadnej wersji programu Adobe Reader. Obiekt HTMLLoader nie może wyświetlać zawartości PDF.

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

Wykryto program Adobe Reader, ale jego wersja jest zbyt stara. Obiekt HTMLLoader nie może wyświetlać treści PDF.

HTMLPDFCapability.ERROR_PREFERRED_READER_TOO_OLD

Wykryto wymaganą wersję (8.1 lub wyższą) programu Adobe Reader, ale wersja programu Adobe Reader skonfigurowana do obsługi treści PDF jest starsza niż Reader 8.1. Obiekt HTMLLoader nie może wyświetlać treści PDF.

W systemie Windows, jeśli w systemie użytkownika jest już uruchomiony program Adobe Acrobat lub Adobe Reader w wersji 7.x lub wyższej, używana będzie uruchomiona wersja, nawet jeśli jest także zainstalowana nowsza wersja obsługująca ładowanie treści PDF. W tym przypadku, jeśli właściwość pdfCapability ma wartość HTMLPDFCapability.STATUS_OK , to przy próbie załadowania treści PDF w aplikacji AIR starsza wersja programu Acrobat lub Reader wyświetli alert (i nie zostanie wygenerowany wyjątek w aplikacji AIR). Jeśli taka sytuacja może wystąpić u użytkowników, wskazane jest przekazanie im instrukcji, aby zamykali program Acrobat na czas pracy z aplikacją. Taka instrukcja może być wyświetlana np. wówczas, gdy treść PDF nie zostanie załadowana w dopuszczalnym czasie.

W systemie Linux środowisko AIR wyszukuje program Adobe Reader w zmiennej środowiskowej PATH wyeksportowanej przez użytkownika (jeśli zawiera polecenie acroread) oraz w katalogu /opt/Adobe/Reader.

Poniższy kod sprawdza, czy użytkownik może wyświetlać treść PDF w aplikacji AIR. Jeśli użytkownik nie może wyświetlać treści PDF, kod wyświetla informacje o błędzie odpowiadającym obiektowi błędu HTMLPDFCapability:

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

Wczytywanie zawartości PDF

Można dodać treść PDF do aplikacji AIR, tworząc instancję klasy HTMLLoader, ustawiając jej wymiary i podając ścieżkę do pliku PDF.

W poniższym przykładzie plik PDF jest wczytywany z witryny zewnętrznej. W obiekcie URLRequest ścieżkę przykładową należy zastąpić ścieżką do dostępnego zewnętrznego pliku PDF.

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

Można również ładować treść z adresów URL plików oraz adresów URL charakterystycznych dla środowiska AIR, takich jak app oraz app-storage. Na przykład poniższy kod ładuje plik test.pdf z podkatalogu PDF katalogu aplikacji:

app:/js_api_reference.pdf

Więcej informacji na temat schematów adresów URL w środowisku AIR zawiera rozdział Schematy URI .

Wywoływanie skryptów w treści PDF

Istnieje możliwość użycia skryptów JavaScript do sterowania treścią PDF, tak jak w przypadku strony sieci Web w przeglądarce.

Rozszerzenia JavaScript programu Acrobat oferują m.in. następujące możliwości:

  • Sterowanie nawigacją i powiększeniem strony.

  • Przetwarzanie formularzy w dokumencie.

  • Sterowanie zdarzeniami multimedialnymi.

Kompletne, szczegółowe informacje na temat rozszerzeń JavaScript dla programu Adobe Acrobat są dostępne w serwisie Adobe Acrobat Developer Connection pod adresem http://www.adobe.com/devnet/acrobat/javascript.html .

Podstawy komunikacji HTML-PDF

Skrypt JavaScript na stronie HTML może wysłać komunikat do skryptu JavaScript w treści PDF, wywołując metodę postMessage() obiektu DOM reprezentującego treść PDF. Rozważmy na przykład następującą osadzoną treść PDF:

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

Poniższy kod JavaScript w zawierającej PDF treści HTML wysyła komunikat do kodu JavaScript w pliku PDF:

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

Plik PDF może zawierać kod JavaScript odbierający komunikat. Kod JavaScript można dodawać do plików PDF w różnych kontekstach, w szczególności w kontekście dokumentu, folderu, strony, pola i partii wsadowej. Tutaj omawiamy wyłącznie kontekst dokumentu, w którym zdefiniowane są skrypty wykonywane podczas otwierania dokumentu PDF.

Plik PDF może dodać właściwość messageHandler do obiektu hostContainer . Właściwość messageHandler jest obiektem definiującym funkcje obsługi reagujące na komunikaty. Na przykład w poniższym kodzie zdefiniowano funkcję obsługi komunikatów odbieranych przez plik PDF z jego kontenera (czyli z treści HTML, w której jest osadzony plik PDF):

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

Kod JavaScript na stronie HTML może wywołać metodę postMessage() obiektu PDF zawartego na stronie. Wywołanie tej metody powoduje wysłanie komunikatu ( "Hello from HTML" ) do kodu JavaScript na poziomie dokumentu w pliku 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>

Bardziej zaawansowany przykład oraz informacje na temat użycia programu Acrobat 8 w celu dodania kodu JavaScript do pliku PDF zawiera dokument Wywoływanie skryptów w treści PDF ze środowiska Adobe AIR .

Skrypty w kodzie ActionScript obsługujące zawartość PDF

Kod ActionScript (w treści SWF) nie może bezpośrednio komunikować się z kodem JavaScript w treści PDF. Jednak kod ActionScript może komunikować się z kodem JavaScript na stronie HTML załadowanej do obiektu HTMLLoader, który z kolei ładuje treść PDF, a ten kod JavaScript może już komunikować się z kodem JavaScript w załadowanym pliku PDF. Więcej informacji można znaleźć w rozdziale Programowanie w językach HTML i JavaScript w środowisku AIR .

Znane ograniczenia treści PDF w środowisku AIR

Treść PDF w środowisku Adobe AIR podlega następującym ograniczeniom:

  • Treść PDF nie jest wyświetlana w oknie (obiekcie NativeWindow), który jest przezroczysty (którego właściwość transparent jest ustawiona na true ).

  • Kolejność wyświetlania pliku PDF różni się od kolejności wyświetlania pozostałych obiektów wyświetlanych w aplikacji AIR. Mimo że treść PDF jest prawidłowo obcinana zgodnie z kolejnością wyświetlania treści HTML, zawsze będzie znajdować się nad treścią należącą do kolejności wyświetlania aplikacji AIR.

  • Jeśli pewne właściwości wizualne obiektu HTMLLoader, które zawierają dokument PDF, zostaną zmienione, dokument PDF stanie się niewidoczny. Te właściwości obejmują właściwości filters , alpha , rotation i scaling . Zmiana tych właściwości spowoduje wyrenderowanie pliku PDF, który będzie niewidoczny do momentu przywrócenia wartości właściwości. Treść PDF jest niewidoczna również w sytuacji, gdy zostaną zmienione wspomniane właściwości kontenerów obiektu wyświetlanego zawierającego obiekt HTMLLoader.

  • Treść PDF jest widoczna jedynie wtedy, gdy właściwość scaleMode obiektu Stage obiektu NativeWindow zawierającego treść PDF jest ustawiona na wartość StageScaleMode.NO_SCALE . W przypadku ustawienia na dowolną inną wartość zawartość PDF nie jest widoczna.

  • Klikanie łączy do treści w pliku PDF powoduje zmianę pozycji przewinięcia treści PDF. Klikanie łączy do treści poza plikiem PDF przekierowuje obiekt HTMLLoader zawierający plik PDF (nawet jeśli celem łącza jest nowe okno).

  • Procedury komentowania w plikach PDF nie działają w środowisku AIR.