JavaScript in AIR

AIR platziert Inhalte je nach Herkunft in separaten Sandboxen. Die Sandbox-Regeln entsprechen sowohl den Herkunftskriterien der meisten Webbrowser als auch den Sandbox-Regeln von Adobe Flash Player. Zusätzlich stellt AIR einen neuen Anwendungs-Sandboxtyp zur Verfügung, der die Anwendungsinhalte enthält und schützt. Weitere Informationen zu den Sandboxtypen, die Ihnen bei der Entwicklung von AIR-Anwendungen begegnen können, finden Sie unter Sicherheits-Sandboxen.

Auf die Laufzeitumgebung und die AIR-APIs kann nur von HTML und JavaScript zugegriffen werden, das innerhalb der Anwendungs-Sandbox ausgeführt wird. Gleichzeitig wird die dynamische Auswertung und Ausführung von JavaScript in seinen verschiedenen Ausformungen aus Sicherheitsgründen in weiten Teilen auf die Anwendungs-Sandboxen beschränkt. Diese Einschränkungen gelten unabhängig davon, ob Ihre Anwendung Informationen tatsächlich direkt von einem Server lädt. (Selbst Dateiinhalte, analysierte Strings und direkte Benutzereingaben sind nicht immer vertrauenswürdig.)

In welcher Sandbox eine Seite abgelegt wird, wird von dem Ursprung ihrer Inhalte bestimmt. Lediglich Inhalte, die aus dem Anwendungsverzeichnis (dem Installationsverzeichnis, auf das das URL-Schema app: verweist) geladen werden, werden in der Anwendungs-Sandbox platziert. Inhalte, die aus dem Dateisystem geladen werden, werden in der local-with-filesystem-Sandbox oder der local-trusted-Sandbox abgelegt, die den Zugriff auf und die Interaktion mit Inhalten des lokalen Dateisystems, jedoch nicht mit Remote-Inhalten zulassen. Vom Netzwerk geladene Inhalte werden in einer Remote-Sandbox platziert, die der Ursprungsdomäne der Inhalte entspricht.

Soll eine Anwendungsseite ungehindert mit Inhalten in einer Remote-Sandbox interagieren, kann die Seite derselben Domäne wie die Remote-Inhalte zugeordnet werden. Wenn Sie zum Beispiel eine Anwendung erstellen, die Kartendaten von einem Internet-Dienst anzeigt, können Sie die Seite der Anwendung, welche die Inhalte des Dienstes lädt und anzeigt, der Domäne dieses Dienstes zuordnen. Die Attribute für die Zuordnung von Seiten zu Remote-Sandboxen und -Domänen sind neue Attribute, die zu den frame- und iframe-HTML-Elementen hinzugefügt wurden.

Um sicherzustellen, dass Inhalte in einer anwendungsfremden Sandbox risikolos die AIR-Funktionen verwenden können, können Sie eine übergeordnete Sandbox-Brücke einrichten. Untergeordnete Sandbox-Brücken können eingerichtet werden, um zu gewährleisten, dass Anwendungsinhalte sicher Methoden aufrufen und auf Eigenschaften zugreifen können, die zu Inhalten anderer Sandboxen gehören. Sicherheit bedeutet hier, dass die Remote-Inhalte nicht versehentlich Verweise auf Objekte, Eigenschaften oder Methoden erhalten können, die nicht explizit bereitgestellt wurden. Es können nur einfache Datentypen, Funktionen und anonyme Objekte über diese Brücke übergeben werden. Sie müssen jedoch weiterhin dafür Sorge tragen, dass möglicherweise gefährliche Funktionen nicht explizit bereitgestellt werden. Sollten Sie zum Beispiel eine Schnittstelle bereitstellen, die es Remote-Inhalten ermöglichte, Dateien auf dem gesamten System eines Benutzers zu lesen und zu speichern, geben Sie den Remote-Inhalten damit die Chance, Ihren Benutzern erheblichen Schaden zuzufügen.

Sobald der Ladevorgang für eine Seite abgeschlossen ist, bleibt die Verwendung der Funktion eval() auf die Anwendungs-Sandbox beschränkt. Einige Verwendungsmöglichkeiten sind gestattet, damit JSON-formatierte Daten sicher analysiert werden können; Auswertungen, die zu ausführbaren Anweisungen führen, verursachen jedoch eine Fehlermeldung. Unter Codebeschränkungen für Inhalt in unterschiedlichen Sandboxen wird beschrieben, welche Verwendungsmöglichkeiten für die Funktion eval() gestattet sind.

Function-Konstruktoren können in den Anwendungs-Sandboxen verwendet werden, bevor der Ladevorgang der Seite abgeschlossen ist. Wenn alle load-Ereignisprozeduren abgeschlossen sind, können keine neuen Funktionen erstellt werden.

HTML-Seiten in der Anwendungs-Sandbox können den script-Tag nicht für das Laden von JavaScript-Dateien verwenden, die sich außerhalb des Anwendungsverzeichnisses befinden. Soll eine Seite in Ihrer Anwendung ein Skript laden, das sich nicht im Anwendungsverzeichnis befindet, muss die Seite einer anwendungsfremden Sandbox zugeordnet werden.

AIR stellt ein XMLHttpRequest-Objekt (XHR-Objekt) zur Verfügung, mit dem Anwendungen Daten anfordern können. Das folgende Beispiel zeigt eine einfache Datenanforderung:

xmlhttp = new XMLHttpRequest(); 
xmlhttp.open("GET", "http:/www.example.com/file.data", true); 
xmlhttp.onreadystatechange = function() { 
    if (xmlhttp.readyState == 4) { 
        //do something with data... 
    } 
} 
xmlhttp.send(null); 

Im Gegensatz zu Browsern lässt AIR Inhalte, die in der Anwendungs-Sandbox ausgeführt werden, Daten von beliebigen Domänen anfordern. Das Ergebnis eines XHR, das einen JSON-String enthält, kann in Datenobjekte ausgewertet werden, sofern das Ergebnis keinen ausführbaren Code umfasst. Befinden sich im XHR-Ergebnis ausführbare Anweisungen, wird ein Fehler ausgegeben und der Auswertungsversuch schlägt fehl.

Um zu verhindern, das versehentlich Code aus Remote-Quellen eingefügt wird, geben synchrone XHRs ein leeres Ergebnis zurück, wenn die Anforderungen durchgeführt wurden, bevor der Ladevorgang der Seite abgeschlossen wurde. Asynchrone XHRs geben das Ergebnis immer nach dem Laden der Seite zurück.

Domänenübergreifende XMLHttpRequests in anwendungsfremden Sandboxen werden von AIR standardmäßig blockiert. Übergeordnete Fenster in der Anwendungs-Sandbox können wählen, ob domänenübergreifende Anforderungen in einem untergeordnetem Frame, der Inhalte in einer anwendungsfremden Sandbox enthält, zugelassen werden. Hierfür wird allowCrossDomainXHR, ein von AIR hinzugefügtes Attribut im Container-frame oder -iframe-Element auf true gesetzt:

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    allowCrossDomainXHR="true" 
</iframe>

Wenn Sie von einem Frame oder iFrame, der einer Remote-Sandbox zugeordnete Anwendungsinhalte umfasst, eine XMLHttpRequest-Anforderung an einen Remote-Server auslösen, müssen Sie sicherstellen, dass die Zuordnungs-URL nicht die in der XHR verwendete Serveradresse maskiert. Das folgende Beispiel zeigt eine iframe-Definition, mit der Anwendungsinhalte einer Remote-Sandbox für die Domäne „example.com“ zugeordnet werden:

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    documentRoot="app:/sandbox/" 
    sandboxRoot="http://www.example.com/" 
    allowCrossDomainXHR="true" 
</iframe>

Da das Attribut sandboxRoot die Stamm-URL der Adresse www.example.com neu zuordnet, werden alle Anforderungen aus dem Anwendungsverzeichnis und nicht vom Remote-Server geladen. Anforderungen werden unabhängig davon, ob sie aus einer Seitennavigation oder einer XMLHttpRequest-Anforderung hervorgehen, neu zugeordnet.

Um zu vermeiden, dass Datenanforderungen an den Remote-Server versehentlich blockiert werden, ordnen Sie sandboxRoot nicht der Stamm-URL sondern einem Unterverzeichnis der Remote-URL zu. Dieses Verzeichnis muss nicht tatsächlich vorhanden sein. Um Anforderungen an „www.example.com“ für das Laden vom Remote-Server anstelle des Anwendungsverzeichnisses zu gestatten, ändern Sie den iFrame wie folgt:

<iframe id="mashup" 
    src="http://www.example.com/map.html" 
    documentRoot="app:/sandbox/" 
    sandboxRoot="http://www.example.com/air/" 
    allowCrossDomainXHR="true" 
</iframe>

In diesem Fall werden lediglich Inhalte im Unterverzeichnis air lokal geladen.

Weitere Informationen zur Sandboxen-Zuordnung finden Sie unter HTML-frame- und iframe-Elemente und HTML-Sicherheit in Adobe AIR.

In AIR-Anwendungen können nur Inhalte in Remote-Sandboxen (aus http:- und https:-Quellen geladene Inhalte) Cookies verwenden (die Eigenschaft document.cookie). In der Anwendungs-Sandbox stehen andere Mittel zum Speichern bleibender Daten zur Verfügung, darunter die EncryptedLocalStore-, SharedObject- und FileStream-Klassen.

Die Clipboard-API von Webkit wird durch die folgenden Ereignisse gesteuert: copy, cut und paste. Das in diesen Ereignissen übergebene event-Objekt bietet mithilfe der Eigenschaft clipboardData Zugriff auf die Zwischenablage. Verwenden Sie die folgenden Methoden des Objekts clipboardData, um Daten aus der Zwischenablage zu lesen oder in diese zu schreiben:

JavaScript-Code außerhalb der Anwendungs-Sandbox kann nur durch diese Ereignisse auf die Zwischenablage zugreifen. Die Inhalte in der Anwendungs-Sandbox können jedoch mithilfe der Clipboard-Klasse von AIR direkt auf die Zwischenablage des Systems zugreifen. Verwenden Sie zum Beispiel die folgende Anweisung, um Textformatdaten in die Zwischenablage zu kopieren:

var clipping = air.Clipboard.generalClipboard.getData("text/plain", 
                                air.ClipboardTransferMode.ORIGINAL_ONLY);

Folgende MIME-Typen sind für die Daten gültig:

Weitere Informationen zur Verwendung der Zwischenablage finden Sie unter Kopieren und Einfügen und Using the Pasteboard from JavaScript (Apple Developer Center).

Durch Drag & Drop in und aus HTML werden folgende DOM-Ereignisse verursacht: dragstart, drag, dragend, dragenter, dragover, dragleave und drop. Das in diesen Ereignissen übergebene event-Objekt bietet mithilfe der Eigenschaft dataTransfer Zugriff auf die gezogenen Daten. Die Eigenschaft dataTransfer verweist auf ein Objekt, das dieselben Methoden bereitstellt wie das mit einem Clipboard-Ereignis verknüpfte Objekt clipboardData. Sie können zum Beispiel folgende Funktion verwenden, um Textformatdaten aus einem drop-Ereignis zu erhalten.

function onDrop(dragEvent){ 
    return dragEvent.dataTransfer.getData("text/plain",  
            air.ClipboardTransferMode.ORIGINAL_ONLY); 
}

Das Objekt dataTransfer verfügt über folgende wichtige Mitglieder:

Weitere Information zur Unterstützung für das Drag & Drop in AIR-Anwendungen finden Sie unter Ziehen und Ablegen in AIR und Using the Drag-and-Drop from JavaScript (Apple Developer Center).

AIR platziert Sicherheitseinschränkungen für die Verwendung der Eigenschaften innerHTML und outerHTML für Inhalte, die in der Anwendung ausgeführt werden. Vor dem Seitenladeereignis und während der Ausführung von Ladeereignisprozeduren können die Eigenschaften innerHTML und outerHTML uneingeschränkt verwendet werden. Sobald das Laden der Seite abgeschlossen ist, können die Eigenschaften innerHTML oder outerHTML jedoch nur noch verwendet werden, um statische Inhalte zum Dokument hinzuzufügen. Anweisungen in dem innerHTML oder outerHTML zugewiesenem String, die einen ausführbaren Code ergeben, werden ignoriert. Wenn Sie beispielsweise ein Attribut für den Ereignisrückruf in eine Elementdefinition aufnehmen, wird der Ereignis-Listener nicht hinzugefügt. Eingebettete <script>-Tags werden ebenfalls nicht ausgewertet. Weitere Informationen finden Sie unter HTML-Sicherheit in Adobe AIR.

Die Verwendung der Methoden write() und writeln() ist in der Anwendungs-Sandbox vor dem Ereignis load der Seite nicht beschränkt. Nachdem die Seite geladen wurde, wird durch den Aufruf dieser Methoden die Seite jedoch weder gelöscht noch wird eine neue Seite erstellt. In einer anwendungsfremden Sandbox wird durch den Aufruf von document.write() oder writeln() nach dem Laden einer Seite die aktuelle Seite wie in anderen Webbrowsern auch gelöscht und es wird eine neue, leere Seite geöffnet.

Setzen Sie die Eigenschaft document.designMode auf den Wert on, um alle Elemente im Dokument editierbar zu machen. Die integrierte Editorunterstützung umfasst die Bearbeitung, das Kopieren und Einfügen und Drag & Drop von Text. Die Einstellung von designMode auf on hat die gleichen Auswirkungen wie die Einstellung des Elements body der Eigenschaft contentEditable auf true. Sie können die Eigenschaft contentEditable auf die meisten HTML-Elemente anwenden, um festzulegen, welche Abschnitte eines Dokuments editierbar sein sollen. Weitere Informationen finden Sie unter HTML-Attribut contentEditable.

Verwenden Sie das Ereignis unload nicht im obersten frameset- oder body-Tag eines Fensters (einschließlich des Hauptfensters der Anwendung), um auf das Schließen des Fensters (oder der Anwendung) zu reagieren. Setzen Sie statt dessen das Ereignis exiting des Objekts NativeApplication ein, um festzustellen, wann eine Anwendung geschlossen wird, oder das Ereignis closing des Objekts NativeWindow, um festzustellen, wann ein Fenster geschlossen wird. Mit dem folgenden JavaScript-Code wird zum Beispiel eine Meldung ("Goodbye.") eingeblendet, wenn der Benutzer die Anwendung schließt:

var app = air.NativeApplication.nativeApplication; 
app.addEventListener(air.Event.EXITING, closeHandler); 
function closeHandler(event) 
{ 
    alert("Goodbye."); 
}

Skripts können jedoch erfolgreich auf ein unload-Ereignis reagieren, das durch die Navigation von Frame-, iFrame- oder Fensterinhalten der obersten Ebene ausgelöst wird.

Das Window-Objekt bleibt das globale Objekt im JavaScript-Ausführungskontext. In der Anwendungs-Sandbox fügt AIR neue Eigenschaften zum JavaScript-Window-Objekt hinzu, um Zugriff auf die integrierten Klassen von AIR sowie wichtige Host-Objekte zu gewähren. Einige Methoden und Eigenschaften verhalten sich außerdem unterschiedlich, je nachdem ob sie sich in der Anwendungs-Sandbox befinden oder nicht.

Window.runtime-Eigenschaft

Die Eigenschaft runtime gibt Ihnen die Möglichkeit, die integrierten runtime-Klassen aus der Anwendungs-Sandbox heraus zu instanziieren und zu verwenden. Zu diesen Klassen gehören die AIR- und Flash Player-APIs (jedoch zum Beispiel nicht das Flex-Framework). Mit der folgenden Anweisung wird beispielsweise ein AIR-File-Objekt erstellt:

var preferencesFile = new window.runtime.flash.filesystem.File();

Die Datei AIRAliases.js, die mit der AIR-SDK bereitgestellt wird, enthält alle Aliasdefinitionen, mit denen Sie solche Verweise kürzen können. Wird die Datei AIRAliases.js zum Beispiel in eine Seite importiert, kann das File-Objekt mit der folgenden Anweisung erstellt werden.

var preferencesFile = new air.File();

Die Eigenschaft window.runtime wird nur für Inhalte in der Anwendungs-Sandbox definiert und dies nur für das übergeordnete Dokument einer Seite mit Frames oder iFrames.

Weitere Informationen finden Sie unter Verwenden der AIRAliases.js-Datei.

Window.nativeWindow-Eigenschaft

Die Eigenschaft nativeWindow stellt einen Verweis auf das darunterliegende native Window-Objekt zur Verfügung. Mit dieser Eigenschaft können Sie Window-Funktionen und -Eigenschaften wie die Fensterposition, das Fensterformat und die Sichtbarkeit skripten und Window-Ereignisse wie Schließen, Größenveränderungen und Verschieben verarbeiten. Mit der folgenden Anweisung wird das Fenster zum Beispiel geschlossen:

window.nativeWindow.close();

Hinweis: Die vom NativeWindow-Objekt bereitgestellten Funktionen zur Fenstersteuerung überschneiden sich mit den Funktionen des Window-Objekts von JavaScript. In solchen Fällen können Sie die Methode verwenden, die Ihnen am besten liegt.

Die Eigenschaft window.nativeWindow wird nur für Inhalte in der Anwendungs-Sandbox definiert und dies nur für das übergeordnete Dokument einer Seite mit Frames oder iFrames.

Window.htmlLoader-Eigenschaft

Die Eigenschaft htmlLoader bietet einen Verweis auf das HTMLLoader-Objekt von AIR, das die HTML-Inhalte enthält. Mit dieser Eigenschaft können Sie das Aussehen und das Verhalten der HTML-Umgebung skripten. So können Sie die Eigenschaft htmlLoader.paintsDefaultBackground zum Beispiel verwenden, um festzulegen, ob durch die Steuerung ein standardmäßiger weißer Hintergrund erstellt wird:

window.htmlLoader.paintsDefaultBackground = false;

Hinweis: Das HTMLLoader-Objekt selbst verfügt über eine window-Eigenschaft, die auf das Window-Objekt von JavaScript der in ihm enthaltenen HTML-Inhalte verweist. Mit dieser Eigenschaft können Sie über einen Verweis auf das Container-HTMLLoader-Objekt auf die JavaScript-Umgebung zugreifen.

Die Eigenschaft window.htmlLoader wird nur für Inhalte in der Anwendungs-Sandbox definiert und dies nur für das übergeordnete Dokument einer Seite mit Frames oder iFrames.

Window.parentSandboxBridge- und Window.childSandboxBridge-Eigenschaften

Mit den Eigenschaften parentSandboxBridge und childSandboxBridge können Sie eine Schnittstelle zwischen einem übergeordneten und einem untergeordneten Frame erstellen. Weitere Informationen finden Sie unter Cross-Scripting von Inhalten in unterschiedlichen Sicherheits-Sandboxen.

Window.setTimeout()- und Window.setInterval()-Funktionen

AIR gibt Sicherheitseinschränkungen für die Verwendung der Funktionen von setTimeout() und setInterval() in der Anwendungs-Sandbox vor. Wenn Sie setTimeout() oder setInterval() aufrufen, können Sie den auszuführenden Code nicht als String definieren. Statt dessen müssen Sie eine Funktionsreferenz verwenden. Weitere Informationen finden Sie unter setTimeout() und setInterval().

Window.open()-Funktion

Wenn die Methode open() von einem Code, der in einer anwendungsfremden Sandbox ausgeführt wird, aufgerufen wird, öffnet die Methode nur ein Fenster, wenn dieser Aufruf durch eine Benutzeraktion (wie einen Mausklick oder eine Tastatureingabe ausgelöst wurde. Außerdem wird vor dem Fenstertitel der Anwendungstitel angezeigt (um zu verhindern, dass Fenster, die durch Remote-Inhalte geöffnet werden, von der Anwendung geöffnete Fenster imitieren). Weitere Informationen finden Sie unter Beschränkungen beim Aufrufen der JavaScript-window.open()-Methode.

Das Objekt NativeApplication hält Informationen zum Anwendungsstatus bereit, löst verschiedene wichtige Ereignisse auf Anwendungsebene aus und bietet nützliche Funktionen für die Steuerung des Anwendungsverhaltens. Eine einzelne Instanz des Objekts NativeApplication wird automatisch erstellt. Über die klassendefinierte Eigenschaft NativeApplication.nativeApplication kann darauf zugegriffen werden.

Mit dem folgenden JavaScript-Code können Sie zum Beispiel auf das Objekt zugreifen:

var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Wurde das Skript AIRAliases.js importiert, können Sie die kürzere Form verwenden:

var app = air.NativeApplication.nativeApplication;

Auf das NativeApplication-Objekt kann nur innerhalb der Anwendungs-Sandbox zugegriffen werden. Weitere Informationen zum NativeApplication-Objekt finden Sie unter Arbeiten mit AIR-Laufzeit- und Betriebssysteminformationen.

Die Ausführung von in einem JavaScript- URL-Schema definierten Code (z. B. href="javascript:alert('Test')") wird innerhalb der Anwendungs-Sandbox blockiert. Es wird kein Fehler ausgegeben.