Definiowanie interfejsów użytkownika w stylu przeglądarki dla treści HTML

Adobe AIR 1.0 i wersje późniejsze

Język JavaScript udostępnia kilka interfejsów API przeznaczonych do kontrolowania okna, w którym wyświetlana jest treść HTML. W środowisku AIR te elementy interfejsu API mogą być przesłonięte przez niestandardową implementację klasy HTMLHost.

Informacje o rozszerzaniu klasy HTMLHost

Na przykład: jeśli aplikacja prezentuje wiele obiektów HTMLLoader w interfejsie z kartami, wówczas programista może chcieć, aby zmiany tytułów na ładowanych stronach HTML powodowały zmiany etykiet kart, a nie tytułu głównego okna. I podobnie — kod może reagować na wywołanie metody window.moveTo() poprzez przeniesienie obiektu HTMLLoader do kontenera nadrzędnego obiektu wyświetlanego; poprzez przeniesienie okna, które zawiera obiekt HTMLLoader; poprzez niewykonanie żadnej operacji lub poprzez wykonanie zupełnie innej operacji.

Klasa AIR HTMLHost kontroluje następujące właściwości i metody JavaScript:

  • window.status

  • window.document.title

  • window.location

  • window.blur()

  • window.close()

  • window.focus()

  • window.moveBy()

  • window.moveTo()

  • window.open()

  • window.resizeBy()

  • window.resizeTo()

Utworzenie obiektu HTMLLoader za pomocą metody new HTMLLoader() nie powoduje aktywacji właściwości i metod JavaScript z listy. Klasa HTMLHost udostępnia domyślną implementację tych interfejsów API JavaScript w stylu przeglądarki. Możliwe jest również rozszerzenie klasy HTMLHost w celu dostosowania zachowania. W celu utworzenia obiektu HTMLHost obsługującego zachowanie domyślne należy ustawić dla parametru defaultBehaviors wartość true w konstruktorze HTMLHost:

var defaultHost:HTMLHost = new HTMLHost(true);

Po utworzeniu okna HTML w środowisku AIR za pomocą metody createRootWindow() klasy HTMLLoader następuje automatyczne przypisanie instancji HTMLHost obsługującej domyślne zachowania. Zachowanie obiektu hosta można zmienić poprzez przypisanie innej implementacji HTMLHost do właściwości htmlHost obiektu HTMLLoader lub przypisanie wartości null w celu wyłączenia tych funkcji.

Uwaga: Środowisko AIR przypisuje domyślny obiekt HTMLHost do początkowego okna tworzonego dla aplikacji AIR opartej na HTML oraz do dowolnych okien utworzonych przez domyślną implementację metody window.open() JavaScript.

Przykład: rozszerzanie klasy HTMLHost

Poniższy przykład prezentuje sposób dostosowania wpływu, jaki obiekt HTMLLoader wywiera na interfejs użytkownika, poprzez rozszerzenie klasy HTMLHost:

Przykład w środowisku Flex:

  1. Utwórz klasę, która będzie rozszerzać klasę HTMLHost (podklasa).

  2. Przesłoń metody nowej klasy w celu obsługi zmian w ustawieniach związanych z interfejsem użytkownika. Na przykład: klasa CustomHost definiuje zachowania wywołanej metody window.open() i zmiany właściwości window.document.title. Wywołania metody window.open() powodują otwieranie strony HTML w nowym oknie, a zmiany właściwości window.document.title (łącznie z ustawieniem elementu <title> strony HTML) powodują ustawienie tytułu tego okna.

    package 
{ 
    import flash.html.*; 
    import flash.display.StageScaleMode; 
    import flash.display.NativeWindow; 
    import flash.display.NativeWindowInitOptions; 
 
    public class CustomHost extends HTMLHost 
    { 
        import flash.html.*; 
        override public function 
            createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader 
        { 
            var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
            var bounds:Rectangle = new Rectangle(windowCreateOptions.x, 
                                            windowCreateOptions.y, 
                                            windowCreateOptions.width, 
                                            windowCreateOptions.height); 
            var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                        windowCreateOptions.scrollBarsVisible, bounds); 
            htmlControl.htmlHost = new HTMLHostImplementation(); 
            if(windowCreateOptions.fullscreen){ 
                htmlControl.stage.displayState = 
                    StageDisplayState.FULL_SCREEN_INTERACTIVE; 
            } 
            return htmlControl; 
        } 
        override public function updateTitle(title:String):void 
        { 
            htmlLoader.stage.nativeWindow.title = title; 
        } 
    } 
}

  3. W kodzie, który zawiera obiekt HTMLLoader (nie kod nowej podklasy klasy HTMLHost), utwórz obiekt nowej klasy. Przypisz nowy obiekt do właściwości htmlHost obiektu HTMLLoader. Poniższy kod Flex korzysta z klasy CustomHost zdefiniowanej w poprzednim kroku:

    <?xml version="1.0" encoding="utf-8"?> 
<mx:WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="vertical" 
    applicationComplete="init()"> 
    <mx:Script> 
        <![CDATA[ 
            import flash.html.HTMLLoader; 
            import CustomHost; 
            private function init():void 
            { 
                var html:HTMLLoader = new HTMLLoader(); 
                html.width = container.width; 
                html.height = container.height; 
                var urlReq:URLRequest = new URLRequest("Test.html"); 
                html.htmlHost = new CustomHost(); 
                html.load(urlReq); 
                container.addChild(html); 
            } 
        ]]> 
    </mx:Script> 
    <mx:UIComponent id="container" width="100%" height="100%"/> 
</mx:WindowedApplication>

W celu przetestowania tego kodu należy dołączyć do katalogu aplikacji plik HTML o następującej treści:

<html> 
    <head> 
        <title>Test</title> 
    </head> 
    <script> 
        function openWindow() 
        { 
            window.runtime.trace("in"); 
            document.title = "foo" 
            window.open('Test.html'); 
            window.runtime.trace("out"); 
        } 
    </script> 
    <body> 
        <a href="#" onclick="openWindow()">window.open('Test.html')</a> 
    </body> 
</html>

Przykład dla programu Flash Professional:

  1. Utwórz plik Flash dla środowiska AIR. Ustaw klasę document tego pliku jako CustomHostExample, a następnie zapisz plik pod nazwą CustomHostExample.fla.

  2. Utwórz plik ActionScript o nazwie CustomHost.as, który zawiera klasę rozszerzającą klasę HTMLHost (podklasa). Ta klasa przesłania niektóre metody nowej klasy w celu obsługi zmian w ustawieniach powiązanych z interfejsem użytkownika. Na przykład: klasa CustomHost definiuje zachowania wywołanej metody window.open() i zmiany właściwości window.document.title. Wywołania metody window.open() powodują otwieranie strony HTML w nowym oknie, a zmiany właściwości window.document.title (łącznie z ustawieniem elementu <title> strony HTML) powodują ustawienie tytułu tego okna.

    package 
{ 
    import flash.display.StageScaleMode; 
    import flash.display.NativeWindow; 
    import flash.display.NativeWindowInitOptions; 
    import flash.events.Event; 
    import flash.events.NativeWindowBoundsEvent; 
    import flash.geom.Rectangle; 
    import flash.html.HTMLLoader; 
    import flash.html.HTMLHost; 
    import flash.html.HTMLWindowCreateOptions; 
    import flash.text.TextField; 
 
    public class CustomHost extends HTMLHost 
    { 
        public var statusField:TextField; 
         
        public function CustomHost(defaultBehaviors:Boolean=true) 
        { 
            super(defaultBehaviors); 
        } 
        override public function windowClose():void 
        { 
            htmlLoader.stage.nativeWindow.close(); 
        } 
        override public function createWindow( 
                                windowCreateOptions:HTMLWindowCreateOptions ):HTMLLoader 
        { 
            var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
            var bounds:Rectangle = new Rectangle(windowCreateOptions.x, 
                                            windowCreateOptions.y, 
                                            windowCreateOptions.width, 
                                            windowCreateOptions.height); 
            var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                        windowCreateOptions.scrollBarsVisible, bounds); 
            htmlControl.htmlHost = new HTMLHostImplementation(); 
            if(windowCreateOptions.fullscreen){ 
                htmlControl.stage.displayState = 
                    StageDisplayState.FULL_SCREEN_INTERACTIVE; 
            } 
            return htmlControl; 
        } 
        override public function updateLocation(locationURL:String):void 
        { 
            trace(locationURL); 
        } 
        override public function set windowRect(value:Rectangle):void 
        { 
            htmlLoader.stage.nativeWindow.bounds = value; 
        } 
        override public function updateStatus(status:String):void 
        { 
            statusField.text = status; 
            trace(status); 
        } 
        override public function updateTitle(title:String):void 
        { 
            htmlLoader.stage.nativeWindow.title = title + "- Example Application"; 
        } 
        override public function windowBlur():void 
        { 
            htmlLoader.alpha = 0.5; 
        } 
        override public function windowFocus():void 
        { 
            htmlLoader.alpha = 1; 
        } 
    } 
}

  3. Utwórz inny plik ActionScript o nazwie CustomHostExample.as, który będzie zawierał klasę document dla aplikacji. Ta klasa tworzy obiekt HTMLLoader i ustawia jego właściwość host na instancję klasy CustomHost zdefiniowaną w poprzednim kroku:

    package 
{ 
    import flash.display.Sprite; 
    import flash.html.HTMLLoader; 
    import flash.net.URLRequest; 
    import flash.text.TextField; 
 
    public class CustomHostExample extends Sprite 
    { 
        function CustomHostExample():void 
        { 
            var html:HTMLLoader = new HTMLLoader(); 
            html.width = 550; 
            html.height = 380; 
            var host:CustomHost = new CustomHost(); 
            html.htmlHost = host; 
             
            var urlReq:URLRequest = new URLRequest("Test.html"); 
            html.load(urlReq); 
             
            addChild(html); 
             
            var statusTxt:TextField = new TextField(); 
            statusTxt.y = 380; 
            statusTxt.height = 20; 
            statusTxt.width = 550; 
            statusTxt.background = true; 
            statusTxt.backgroundColor = 0xEEEEEEEE; 
            addChild(statusTxt); 
             
            host.statusField = statusTxt; 
        } 
    } 
}

    W celu przetestowania tego kodu należy dołączyć do katalogu aplikacji plik HTML o następującej treści:

    <html> 
     <head> 
     <title>Test</title> 
     <script> 
     function openWindow() 
     { 
     document.title = "Test" 
     window.open('Test.html'); 
     } 
     </script> 
     </head> 
     <body bgColor="#EEEEEE"> 
     <a href="#" onclick="window.open('Test.html')">window.open('Test.html')</a> 
     <br/><a href="#" onclick="window.document.location='http://www.adobe.com'"> 
     window.document.location = 'http://www.adobe.com'</a> 
     <br/><a href="#" onclick="window.moveBy(6, 12)">moveBy(6, 12)</a> 
     <br/><a href="#" onclick="window.close()">window.close()</a> 
     <br/><a href="#" onclick="window.blur()">window.blur()</a> 
     <br/><a href="#" onclick="window.focus()">window.focus()</a> 
     <br/><a href="#" onclick="window.status = new Date().toString()">window.status=new Date().toString()</a> 
     </body> 
</html>

Obsługa zmian właściwości window.location

W celu obsługiwania zmian adresu URL strony HTML należy przesłonić metodę locationChange(). Metoda locationChange() jest wywoływana, gdy kod JavaScript na stronie zmieni wartość window.location. Poniższy przykład ładuje żądany adres URL:

override public function updateLocation(locationURL:String):void 
{ 
    htmlLoader.load(new URLRequest(locationURL)); 
}
Uwaga: Za pomocą właściwości htmlLoader obiektu HTMLHost można tworzyć odwołania do bieżącego obiektu HTMLLoader.

Obsługa wywołań JavaScript do funkcji window.moveBy(), window.moveTo(), window.resizeTo(), window.resizeBy()

W celu obsługiwania zmian krawędzi treści HTML należy przesłonić metodę set windowRect(). Metoda set windowRect() jest wywoływana, gdy kod JavaScript na stronie wywoła metodę window.moveBy(), window.moveTo(), window.resizeTo() lub metodę window.resizeBy(). Poniższy przykład aktualizuje krawędzie okna na pulpicie:

override public function set windowRect(value:Rectangle):void 
{ 
    htmlLoader.stage.nativeWindow.bounds = value; 
}

Obsługa wywołań JavaScript do funkcji window.open()

W celu obsługiwania wywołań metody window.open() z kodu JavaScript należy przesłonić metodę createWindow(). Implementacje metody createWindow() są odpowiedzialne za tworzenie i zwracanie nowego obiektu HTMLLoader. Zwykle obiekt HTMLLoader jest wyświetlany w nowym oknie, ale tworzenie okna nie jest wymagane.

Poniższy przykład ilustruje sposób implementacji funkcji createWindow() za pomocą metody HTMLLoader.createRootWindow() w celu utworzenia okna i obiektu HTMLLoader. Można również osobno utworzyć obiekt NativeWindow i dodać obiekt HTMLLoader do stołu montażowego okna.

override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{ 
    var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
    var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y,  
                                windowCreateOptions.width, windowCreateOptions.height); 
    var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                    windowCreateOptions.scrollBarsVisible, bounds); 
    htmlControl.htmlHost = new HTMLHostImplementation(); 
    if(windowCreateOptions.fullscreen){ 
        htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; 
    } 
    return htmlControl; 
}
Uwaga: Ten przykład przypisuje niestandardową implementację HTMLHost do dowolnych nowych okien utworzonych za pomocą metody window.open(). W razie potrzeby można również użyć innej implementacji lub ustawić dla właściwości htmlHost wartość null dla nowych okien.

Obiekt przekazany jako parametr do metody createWindow() jest obiektem HTMLWindowCreateOptions. Klasa HTMLWindowCreateOptions zawiera właściwości, które zgłaszają wartości ustawione w ciągu znaków parametru features w wywołaniu metody window.open():

Właściwość klasy HTMLWindowCreateOptions

Odpowiadające ustawienie w ciągu znaków funkcji w wywołaniu metody window.open() z kodu JavaScript

fullscreen

fullscreen

height

height

locationBarVisible

location

menuBarVisible

menubar

resizeable

resizable

scrollBarsVisible

scrollbars

statusBarVisible

status

toolBarVisible

toolbar

width

width

x

left lub screenX

y

top lub screenY

Klasa HTMLLoader nie implementuje wszystkich funkcji, które mogą być określone w ciągu znaków tej funkcji. W razie potrzeby aplikacja musi udostępniać paski przewijania, paski lokalizacji, paski menu, paski stanu oraz paski narzędzi.

Inne argumenty metody window.open() JavaScript są obsługiwane przez system. Implementacja metody createWindow() nie powinna ładować treści w obiekcie HTMLLoader ani ustawiać tytułu okna.

Obsługa wywołań JavaScript do funkcji window.close()

W celu obsługiwania wywołań metody window.close() z kodu JavaScript należy przesłonić metodę windowClose(). Poniższy przykład zamyka okno pulpitu po wywołaniu metody window.close():

override public function windowClose():void 
{ 
    htmlLoader.stage.nativeWindow.close(); 
}

Wywołania metody window.close() z kodu JavaScript nie muszą zamykać okna zawierającego. Można na przykład usunąć obiekt HTMLLoader z listy wyświetlania, pozostawiając okno otwarte (okno może zawierać inną treść), jak w poniższym kodzie:

override public function windowClose():void 
{ 
    htmlLoader.parent.removeChild(htmlLoader); 
}

Obsługa zmian właściwości window.status

W celu obsługiwania zmian JavaScript dotyczących wartości window.status należy przesłonić metodę updateStatus(). W poniższym przykładzie polecenie trace dotyczy wartości stanu:

override public function updateStatus(status:String):void 
{ 
    trace(status); 
}

Żądany stan jest przekazywany jako ciąg znaków do metody updateStatus().

Obiekt HTMLLoader nie udostępnia paska stanu.

Obsługa zmian właściwości window.document.title

W celu obsługiwania zmian JavaScript dotyczących wartości window.document.title należy przesłonić metodę updateTitle(). Poniższy przykład zmienia tytuł okna i dołącza do tytułu ciąg znaków „Sample”:

override public function updateTitle(title:String):void 
{ 
    htmlLoader.stage.nativeWindow.title = title + " - Sample"; 
}

Jeśli właściwość document.title jest ustawiona na stronie HTML, wówczas żądany tytuł jest przekazywany jako ciąg znaków do metody updateTitle().

Zmiany właściwości document.title nie muszą powodować zmiany tytułu okna zawierającego obiekt HTMLLoader. Można na przykład zmienić inny element interfejsu, taki jak pole tekstowe.

Obsługa wywołań JavaScript do funkcji window.blur() i window.focus()

W celu obsługi wywołań metod window.blur() i window.focus() w kodzie JavaScript należy przesłonić metody windowBlur() i windowFocus(), co przedstawiono w poniższym przykładzie:

override public function windowBlur():void 
{ 
    htmlLoader.alpha = 0.5; 
} 
override public function windowFocus():void 
{ 
    htmlLoader.alpha = 1.0; 
    NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow); 
}
Uwaga: Środowisko AIR nie udostępnia interfejsu API przeznaczonego do dezaktywowania okna lub aplikacji.

Tworzenie okien z przewijaną treścią HTML

Klasa HTMLLoader zawiera statyczną metodę HTMLLoader.createRootWindow(), która umożliwia otwarcie nowego okna (reprezentowanego przez obiekt NativeWindow), które zawiera obiekt HTMLLoader oraz definiuje niektóre ustawienia interfejsu użytkownika dla okna. Metoda przyjmuje cztery parametry, które umożliwiają zdefiniowanie interfejsu użytkownika:

Parametr

Opis

visible

Wartość logiczna, która określa, czy okno jest początkowo widoczne (true) czy niewidoczne (false).

windowInitOptions

Obiekt NativeWindowInitOptions. Klasa NativeWindowInitOptions definiuje opcje inicjowania dla obiektu NativeWindow, łącznie z następującymi ustawieniami: określa, czy możliwe jest maksymalizowanie, minimalizowanie i zmiana wielkości okna; określa, czy okno ma karnację systemową czy niestandardową; określa, czy okno jest przezroczyste czy nieprzezroczyste (dla okien bez karnacji systemowej); określa również typ okna.

scrollBarsVisible

Określa, czy paski przewijania są dostępne (true) czy niedostępne (false).

bounds

Obiekt Rectangle definiujący pozycję i wielkość nowego okna.

Na przykład: poniższy kod korzysta z metody HTMLLoader.createRootWindow() w celu utworzenia okna z treścią HTMLLoader, która korzysta z pasków przewijania:

var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
var bounds:Rectangle = new Rectangle(10, 10, 600, 400); 
var html2:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, true, bounds); 
var urlReq2:URLRequest = new URLRequest("http://www.example.com"); 
html2.load(urlReq2); 
html2.stage.nativeWindow.activate();
Uwaga: Okna utworzone poprzez bezpośrednie wywołanie metody createRootWindow() w kodzie JavaScript pozostają niezależne od otwieranych okien HTML. Na przykład właściwości JavaScript opener i parent Window mają wartość null. Jeśli jednak metoda createRootWindow() zostanie wywołana bezpośrednio poprzez przesłonięcie metody createWindow() HTMLHost wywołaniem metody createRootWindow(), wówczas właściwości opener i parent będą odwoływały się do otwieranego okna HTML.