Definieren browserähnlicher Benutzeroberflächen für HTML-Inhalt

Adobe AIR 1.0 und höher

JavaScript bietet mehrere APIs zur Steuerung des Fensters, in dem der HTML-Inhalt angezeigt wird. In AIR können diese APIs durch die Implementierung einer benutzerdefinierten HTMLHost-Klasse außer Kraft gesetzt werden.

Erweitern der HTMLHost-Klasse

Wenn Ihre Anwendung beispielsweise mehrere HTMLLoader-Objekte in einer Benutzeroberfläche mit Registerkarten darstellt, sollten durch die von den geladenen HTML-Seiten vorgenommenen Titeländerungen nicht der Titel des Hauptfensters sondern die Bezeichnung der Registerkarte geändert werden. In ähnlicher Weise könnte der Code auf einen Aufruf von window.moveTo() reagieren und die Position des HTMLLoader-Objekts im übergeordneten Anzeigeobjektcontainer ändern, das HTMLLoader-Objekt enthaltende Fenster verschieben, nichts unternehmen oder etwas vollkommen anders ausführen.

Mit der AIR-HTMLHost-Klasse werden die folgenden JavaScript-Eigenschaften und -Methoden gesteuert:

  • window.status

  • window.document.title

  • window.location

  • window.blur()

  • window.close()

  • window.focus()

  • window.moveBy()

  • window.moveTo()

  • window.open()

  • window.resizeBy()

  • window.resizeTo()

Wenn Sie ein HTMLLoader-Objekt mithilfe von new HTMLLoader() erstellen, sind die genannten JavaScript-Eigenschaften und -Methoden nicht aktiviert. Die HTMLHost-Klasse bietet eine browserähnliche Standardimplementierung dieser JavaScript-APIs. Außerdem können Sie die HTMLHost-Klasse erweitern, um das Verhalten anzupassen. Um ein HTMLHost-Objekt zu erstellen, das das Standardverhalten unterstützt, müssen Sie im HTMLHost-Konstruktor den defaultBehaviors-Parameter auf „true“ festlegen:

var defaultHost:HTMLHost = new HTMLHost(true);

Wenn Sie in AIR ein HTML-Fenster mithilfe der createRootWindow()-Methode der HTMLLoader-Klasse erstellen, wird automatisch eine HTMLHost-Instanz, die das Standardverhalten unterstützt, zugewiesen. Sie können das Verhalten des Host-Objekts ändern, indem Sie der htmlHost-Eigenschaft von „HTMLLoader“ eine andere HTMLHost-Implementierung zuweisen, oder Sie können die Funktionen durch Zuweisen von null vollständig deaktivieren.

Hinweis: Dem ersten für eine HTML-basierte AIR-Anwendung erstellten Fenster und jedem Fenster, das durch die Standardimplementierung der JavaScript-Methode window.open() erstellt wird, wird von AIR ein HTMLHost-Standardobjekt zugewiesen.

Beispiel: Erweitern der HTMLHost-Klasse

Das folgende Beispiel zeigt, wie Sie die Wirkungsweise eines HTMLLoader-Objekts auf die Benutzeroberfläche durch das Erweitern der HTMLHost-Klasse anpassen können:

Flex-Beispiel:

  1. Erstellen Sie eine Klasse, die die HTMLHost-Klasse erweitert (eine Unterklasse).

  2. Setzen Sie Methoden der neuen Klasse außer Kraft, um Änderungen der Einstellungen in Bezug auf die Benutzeroberfläche zu verarbeiten. Beispielsweise definiert die CustomHost-Klasse Verhalten bei Aufrufen von window.open() und Änderungen an window.document.title. Durch Aufrufe von window.open() wird die HTML-Seite in einem neuen Fenster geöffnet und durch Änderungen an window.document.title (einschließlich der Festlegung des <title>-Elements einer HTML-Seite) wird der Titel dieses Fensters festgelegt.

    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. Erstellen Sie ein Objekt der neuen Klasse im Code, der „HTMLLoader“ enthält (nicht im Code der neuen Unterklasse von „HTMLHost“). Weisen Sie das neue Objekt der htmlHost-Eigenschaft von „HTMLLoaders“ zu. Im folgenden Flex-Code wird die im vorherigen Schritt definierte CustomHost-Klasse verwendet:

    <?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>

Um den hier beschriebenen Code zu prüfen, schließen Sie eine HTML-Datei mit dem folgenden Inhalt in das Anwendungsverzeichnis ein:

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

Flash Professional-Beispiel:

  1. Erstellen Sie eine Flash-Datei für AIR. Legen Sie die Dokumentklasse „CustomHostExample“ fest und speichern Sie die Datei dann unter „CustomHostExample.fla“.

  2. Erstellen Sie eine ActionScript-Datei namens „CustomHost.as“, die eine Klasse enthält, die die HTMLHost-Klasse erweitert (eine Unterklasse). Diese Klasse setzt gewisse Methoden der neuen Klasse außer Kraft, um Änderungen der Einstellungen in Bezug auf die Benutzeroberfläche zu verarbeiten. Beispielsweise definiert die CustomHost-Klasse Verhalten bei Aufrufen von window.open() und Änderungen an window.document.title. Durch Aufrufe der window.open()-Methode wird die HTML-Seite in einem neuen Fenster geöffnet und durch Änderungen an der window.document.title-Eigenschaft (einschließlich der Festlegung des <title>-Elements einer HTML-Seite) wird der Titel dieses Fensters festgelegt.

    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. Erstellen Sie eine weitere ActionScript-Datei namens „CustomHostExample.as“, die die Dokumentklasse der Anwendung enthält. Diese Klasse erstellt ein HTMLLoader-Objekt und legt für die host-Eigenschaft eine Instanz der im vorherigen Schritt definierten CustomHost-Klasse fest:

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

    Um den hier beschriebenen Code zu prüfen, schließen Sie eine HTML-Datei mit dem folgenden Inhalt in das Anwendungsverzeichnis ein:

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

Verarbeiten von Änderungen an der window.location-Eigenschaft

Setzen Sie die locationChange()-Methode außer Kraft, um Änderungen an der URL der HTML-Seite zu verarbeiten. Die locationChange()-Methode wird aufgerufen, wenn der Wert von window.location durch JavaScript in einer Seite geändert wird. Im folgenden Beispiel wird einfach die angeforderte URL geladen:

override public function updateLocation(locationURL:String):void 
{ 
    htmlLoader.load(new URLRequest(locationURL)); 
}
Hinweis: Mit der htmlLoader-Eigenschaft des HTMLHost-Objekts können Sie auf das aktuelle HTMLLoader-Objekt verweisen.

Verarbeiten von JavaScript-Aufrufen von „window.moveBy()“, „window.moveTo()“, „window.resizeTo()“, „window.resizeBy()“

Setzen Sie die set windowRect()-Methode außer Kraft, um Änderungen an den Begrenzungen des HTML-Inhalts zu verarbeiten. Die set windowRect()-Methode wird aufgerufen, wenn window.moveBy(), window.moveTo(), window.resizeTo() oder window.resizeBy() durch das JavaScript einer Seite aufgerufen wird. Im folgenden Beispiel werden einfach die Begrenzungen des Desktop-Fensters aktualisiert:

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

Verarbeiten von JavaScript-Aufrufen von „window.open()“

Setzen Sie die createWindow()-Methode außer Kraft, um Aufrufe von window.open() durch JavaScript zu verarbeiten. Implementierungen der createWindow()-Methode sorgen für das Erstellen und Zurückgeben eines neuen HTMLLoader-Objekts. „HTMLLoader“ wird in der Regel in einem neuen Fenster angezeigt, aber es ist nicht erforderlich, ein neues Fenster zu erstellen.

Das folgende Beispiel illustriert, wie die createWindow()-Funktion mithilfe von HTMLLoader.createRootWindow() implementiert wird, um sowohl das Fenster als auch das HTMLLoader-Objekt zu erstellen. Alternativ können Sie auch separat ein NativeWindow-Objekt erstellen und „HTMLLoader“ zur Fensterbühne hinzufügen.

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; 
}
Hinweis: In diesem Beispiel wird die benutzerdefinierte HTMLHost-Implementierung jedem neuen Fenster, das mit window.open() erstellt wird, zugewiesen. Alternativ können Sie auch eine andere Implementierung verwenden oder die htmlHost-Eigenschaft für neue Fenster auf „null“ setzen.

Das Objekt, das als Parameter an die createWindow()-Methode übergeben wird, ist ein HTMLWindowCreateOptions-Objekt. Die HTMLWindowCreateOptions-Klasse enthält Eigenschaften, die die im features-Parameterstring im Aufruf von window.open() festgelegten Werte melden:

HTMLWindowCreateOptions-Eigenschaft

Entsprechende Einstellung im Funktionsstring im JavaScript-Aufruf von „window.open()“

fullscreen

fullscreen

height

height

locationBarVisible

location

menuBarVisible

menubar

resizeable

resizable

scrollBarsVisible

scrollbars

statusBarVisible

status

toolBarVisible

toolbar

width

width

x

left oder screenX

y

top oder screenY

Von der HTMLLoader-Klasse werden nicht alle Funktionen implementiert, die im Funktionsstring angegeben werden können. Die Anwendung muss bei Bedarf Bildlaufleisten, Adressleisten, Menüleisten, Statusleisten und Symbolleisten bieten.

Die anderen Argumente der window.open()-Methode von JavaScript werden vom System verarbeitet. Mit einer createWindow()-Implementierung sollte kein Inhalt in das HTMLLoader-Objekt geladen oder der Fenstertitel festgelegt werden.

Verarbeiten von JavaScript-Aufrufen von „window.close()“

Setzen Sie die windowClose()-Methode außer Kraft, um Aufrufe der window.close()-Methode durch JavaScript zu verarbeiten. Im folgenden Beispiel wird das Desktop-Fenster geschlossen, wenn die window.close()-Methode aufgerufen wird:

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

Bei JavaScript-Aufrufen von window.close() muss das enthaltende Fenster nicht geschlossen werden. Im folgenden Beispiel wird gezeigt, wie Sie „HTMLLoader“ aus der Anzeigeliste entfernen und das Fenster (das weiteren Inhalt enthalten kann) offen lassen:

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

Verarbeiten von Änderungen an der window.status-Eigenschaft

Setzen Sie die updateStatus()-Methode außer Kraft, um Änderungen am Wert von window.status durch JavaScript zu verarbeiten. In diesem Beispiel wird der Statuswert ermittelt:

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

Der angeforderte Status wird als String an die updateStatus()-Methode übergeben.

Das HTMLLoader-Objekt bietet keine Statusleiste.

Verarbeiten von Änderungen an der window.document.title-Eigenschaft

Setzen Sie die updateTitle()-Methode außer Kraft, um Änderungen am Wert von window.document.title durch JavaScript zu verarbeiten. Im folgenden Beispiel wird der Fenstertitel geändert und der String "Sample" wird an den Titel angehängt:

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

Wenn document.title auf einer HTML-Seite festgelegt ist, wird der angeforderte Titel als String an die updateTitle()-Methode übergeben.

Durch Änderungen an document.title muss nicht unbedingt auch der Titel des Fensters geändert werden, in dem das HTMLLoader-Objekt enthalten ist. Sie können beispielsweise ein anderes Element der Benutzeroberfläche, wie etwa ein Textfeld, ändern.

Verarbeiten von JavaScript-Aufrufen von „window.blur()“ und „window.focus()“

Setzen Sie die windowBlur()- und windowFocus()-Methoden außer Kraft, um Aufrufe der window.blur()- und window.focus()-Methoden durch JavaScript zu verarbeiten (siehe folgendes Beispiel):

override public function windowBlur():void 
{ 
    htmlLoader.alpha = 0.5; 
} 
override public function windowFocus():void 
{ 
    htmlLoader.alpha = 1.0; 
    NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow); 
}
Hinweis: AIR bietet keine API zum Deaktivieren eines Fensters oder einer Anwendung.

Erstellen von Fenstern mit HTML-Inhalt und Bildlauf

Die HTMLLoader-Klasse enthält die statische Methode HTMLLoader.createRootWindow(). Diese Methode ermöglicht es, ein neues Fenster (durch ein NativeWindow-Objekt dargestellt) zu öffnen, das ein HTMLLoader-Objekt enthält. Außerdem können Sie einige Benutzeroberflächeneinstellungen für das Fenster festlegen. Mithilfe von vier Parametern der Methode können Sie die Benutzerschnittstelle definieren:

Parameter

Beschreibung

visible

Ein boolescher Wert, der angibt, ob das Fenster zunächst sichtbar (true) oder nicht sichtbar (false) ist.

windowInitOptions

Ein NativeWindowInitOptions-Objekt. Mit der NativeWindowInitOptions-Klasse werden Initialisierungsoptionen für ein NativeWindow-Objekt definiert, u. a.: ob das Fenster minimiert oder maximiert oder ob seine Größe geändert werden kann, ob das Fenster über System-Fensterdesign oder benutzerdefiniertes Fensterdesign verfügt, ob das Fenster transparent ist oder nicht (bei Fenstern, die kein System-Fensterdesign bieten) und der Fenstertyp.

scrollBarsVisible

Ob Bildlaufleisten vorhanden sind (true) oder nicht (false).

bounds

Ein Rectangle-Objekt, das die Position und Größe des neuen Fensters definiert.

Im folgenden Beispiel wird mithilfe der HTMLLoader.createRootWindow()-Methode ein Fenster mit HTMLLoader-Inhalt und Bildlaufleisten erstellt:

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();
Hinweis: Fenster, die durch Aufrufen von createRootWindow() direkt in JavaScript erstellt werden, bleiben unabhängig vom öffnenden HTML-Fenster. Beispielsweise lautet der Wert der Fenstereigenschaften opener und parent von JavaScript null. Wenn Sie createRootWindow() jedoch indirekt aufrufen, indem Sie die createWindow()-Methode von „HTMLHost“ außer Kraft setzen, um createRootWindow() aufzurufen, verweisen opener und parent auf das öffnende HTML-Fenster.