JavaScript in AIR

AIR plaatst inhoud in geïsoleerde sandboxen afhankelijk van de oorsprong van de inhoud. De sandboxregels zijn consistent met het zelfde-oorsprongbeleid dat wordt geïmplementeerd door de meeste webbrowsers. Ze zijn ook consistent met de regels voor sandboxen die worden geïmplementeerd door Adobe Flash Player. Verder biedt AIR het nieuwe sandboxtype toepassing , waarmee toepassingsinhoud kan worden opgeslagen en beveiligd. Zie Beveiligingssandboxen voor meer informatie over de types sandboxen die u tegen kunt komen tijdens het ontwikkelen van AIR-toepassingen.

Toegang tot de runtimeomgeving en de AIR API's is alleen beschikbaar voor HTML en JavaScript die worden uitgevoerd binnen de toepassingssandbox. Tegelijkertijd wordt dynamische evaluatie en uitvoering van de verschillende vormen van JavaScript uit veiligheidsoverwegingen voor een groot deel beperkt binnen de toepassingssandbox. Deze beperkingen gelden altijd, ongeacht of de toepassing rechtstreeks informatie van een server laadt. (Zelfs bestandsinhoud, geplakte tekenreeksen en gegevens die rechtstreeks door de gebruiker worden ingevoerd, kunnen onbetrouwbaar zijn.)

De oorsprong van de inhoud in een pagina bepaalt de sandbox waaraan deze wordt toegewezen. Alleen inhoud die is geladen vanuit de toepassingsmap (de installatiemap waarnaar wordt verwezen door het URL-schema app: ) wordt in de toepassingssandbox geplaatst. Inhoud die wordt geladen vanaf het bestandssysteem wordt geplaatst in het Lokaal-met-bestandssysteem of de sandbox Lokaal-vertrouwd , waarmee u toegang en interactie krijgt met inhoud op het lokale bestandssysteem, maar niet met de inhoud op afstand. Inhoud die wordt geladen vanaf het netwerk, wordt in een externe sandbox geplaatst die correspondeert met het brondomein.

Als een toepassingspagina toestemming moet hebben om desgewenst te interageren met inhoud in een externe sandbox, kan die pagina worden toegewezen aan hetzelfde domein als de externe inhoud. Als u bijvoorbeeld een toepassing schrijft waarin kaartgegevens uit een internetservice worden weergegeven, kan de pagina van deze toepassing waarin inhoud van de service wordt geladen en weergegeven, worden toegewezen aan het servicedomein. De kenmerken voor het toewijzen van pagina's aan externe sandboxen en domeinen zijn nieuwe kenmerken die worden toegevoegd aan de frame- en iframe-elementen in HTML.

Als u inhoud in een niet-toepassingssandbox wilt toestaan om veilig AIR-functies te gebruiken, kunt u een bovenliggende sandboxbridge instellen. Als u toepassingsinhoud wilt toestaan om veilig methoden en toegangseigenschappen van inhoud in andere sandboxen te benaderen, kunt u een onderliggende sandboxbridge instellen. Veilig betekent hier dat externe inhoud niet per ongeluk verwijzingen kan ophalen naar objecten, eigenschappen of methoden die niet expliciet beschikbaar zijn gemaakt. Alleen eenvoudige gegevenstypen, functies en anonieme objecten kunnen via de bridge worden doorgegeven. U moet echter nog steeds voorkomen dat potentieel gevaarlijke functies expliciet beschikbaar worden gemaakt. Als u bijvoorbeeld een interface beschikbaar hebt gemaakt waarmee externe inhoud bestanden op iedere willekeurige locatie in het systeem van een gebruiker kan lezen en schrijven, biedt u externe inhoud mogelijk kans om uw gebruikers grote schade te berokkenen.

Het gebruik van de functie eval() is beperkt binnen de toepassingssandbox als een pagina eenmaal is geladen. Sommige vormen van gebruik zijn toegestaan, zodat gegevens met JSON-indeling veilig kunnen worden geparseerd. Een evaluatie die uitvoerbare instructies als gevolg heeft, resulteert echter altijd in een fout. Codebeperkingen voor de inhoud van verschillende sandboxen beschrijft het toegestane gebruik van de functie eval() .

In de toepassingssandbox kunnen functieconstructors worden gebruikt voordat een pagina geheel is geladen. Nadat alle handlers voor de paginagebeurtenis load zijn voltooid, kunnen geen nieuwe functies meer worden gemaakt.

HTML-pagina's in de toepassingssandbox kunnen geen script tags gebruiken om JavaScript-bestanden te laden van buiten de toepassingsmap. Als een pagina in uw toepassing een script van buiten de toepassingsmap moet laden, moet die pagina worden toegewezen aan een niet-toepassingssandbox.

AIR is voorzien van een XHR-object (XMLHttpRequest), waarmee toepassingen gegevens kunnen aanvragen. In het volgende voorbeeld ziet u een eenvoudige gegevensaanvraag:

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

In tegenstelling tot een browser is het bij AIR mogelijk dat inhoud die wordt uitgevoerd in de toepassingssandbox, gegevens uit elk willekeurig domein aanvraagt. Het resultaat van een XHR die een JSON-tekenreeks bevat, kan worden geëvalueerd in gegevensobjecten, behalve als het resultaat ook uitvoerbare code bevat. Als het XHR-resultaat ook uitvoerbare instructies bevat, treedt er een fout op en mislukt de evaluatiepoging.

Om te voorkomen dat code uit externe bronnen per ongeluk wordt ingebracht, retourneren synchrone XHR's een leeg resultaat als ze zijn gemaakt voordat een pagina geheel is geladen. Asynchrone XHR's worden altijd geretourneerd nadat een pagina is geladen.

AIR blokkeert standaard domeinoverschrijdende XMLHttpRequests in niet-toepassingssandboxen. Een bovenliggend venster in de toepassingssandbox kan ervoor kiezen domeinoverschrijdende aanvragen in een onderliggend frame dat inhoud in een niet-toepassingssandbox bevat, toe te staan door het kenmerk allowCrossDomainXHR , dat wordt toegevoegd door AIR, in te stellen op true in het omvattende frame- of iframe-element:

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

Als u een XMLHttpRequest naar een externe server stuurt vanuit een frame of iframe dat toepassingsinhoud bevat die is toegewezen aan een externe sandbox, moet u ervoor zorgen dat de toewijzende URL het serveradres dat in de XHR wordt gebruikt, niet maskeert. Bekijk bijvoorbeeld de volgende iframe-definitie, die toepassingsinhoud toewijst in een externe sandbox voor het domein example.com:

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

Omdat het kenmerk sandboxRoot de basis-URL van het adres www.example.com opnieuw toewijst, worden alle aanvragen geladen vanuit de toepassingsmap en niet vanaf de externe server. Aanvragen worden altijd opnieuw toegewezen, ongeacht of ze afkomstig zijn van paginanavigatie of een XMLHttpRequest.

Om te voorkomen dat gegevensaanvragen naar de externe server per ongeluk worden geblokkeerd, wijst u sandboxRoot toe aan een submap van de externe URL en niet aan de hoofdmap. Die map hoeft niet echt te bestaan. Als u bijvoorbeeld wilt toestaan dat aanvragen naar www.example.com gegevens laden vanaf de externe server en niet uit de toepassingsmap, verandert u het vorige iframe-element in de volgende:

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

In dit geval wordt alleen de inhoud van de submap air lokaal geladen.

Zie Frame- en iframe-elementen in HTML en HTML-beveiliging in Adobe AIR voor meer informatie over sandboxtoewijzing.

In AIR-toepassingen kan alleen inhoud in externe sandboxen (inhoud die is geladen vanaf bronnen van het type http: en https:) gebruikmaken van cookies (de eigenschap document.cookie ). In de toepassingssandbox, zijn andere opslagmethoden beschikbaar voor het opslaan van persistente gegevens, zoals de klassen EncryptedLocalStore, SharedObject en FileStream.

De WebKit-API voor Clipboard wordt aangestuurd door de volgende gebeurtenissen: copy , cut en paste . Het gebeurtenisobject dat bij deze gebeurtenissen wordt doorgegeven, geeft via de eigenschap clipboardData toegang tot het klembord. Gebruik de volgende methoden van het object clipboardData om klembordgegevens te lezen of te schrijven:

JavaScript-code buiten de toepassingssandbox kan alleen via deze gebeurtenissen toegang krijgen tot het klembord. Inhoud in de toepassingssandbox kan echter rechtstreeks toegang krijgen tot het systeemklembord via de AIR-klasse Clipboard. U kunt bijvoorbeeld de volgende opdracht gebruiken om gegevens over tekstopmaak op het klembord te krijgen:

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

De volgende MIME-typen zijn geldig voor gegevens:

Zie Kopiëren en plakken en Using the Pasteboard from JavaScript (Het klembord voor plakken in JavaScript gebruiken) in het Apple Developer Center voor meer informatie over het gebruik van het klembord.

Het slepen en neerzetten in en uit HTML produceert de volgende DOM-gebeurtenissen: dragstart , drag , dragend , dragenter , dragover , dragleave en drop . Het gebeurtenisobject dat bij deze gebeurtenissen wordt doorgegeven, geeft via de eigenschap dataTransfer toegang tot de gesleepte gegevens. De eigenschap dataTransfer verwijst naar een object dat dezelfde methoden biedt als het clipboardData -object dat is gekoppeld aan een gebeurtenis van het type clipboard. U kunt bijvoorbeeld de volgende functie gebruiken om tekstopmaakgegevens van de gebeurtenis drop te krijgen:

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

Het dataTransfer -object heeft de volgende belangrijke leden:

Zie Slepen en neerzetten in AIR en Slepen en neerzetten gebruiken JavaScript (Apple Developer Center) voor meer informatie over het toevoegen van ondersteuning voor slepen en neerzetten aan een AIR-toepassing.

AIR stelt beveiligingsbeperkingen in voor het gebruik van de eigenschappen innerHTML en outerHTML voor het uitvoeren van inhoud in de toepassingssandbox. Voordat de paginagebeurtenis load optreedt en terwijl eventuele gebeurtenishandlers voor load worden uitgevoerd, gelden er geen beperkingen voor het gebruik van de eigenschappen innerHTML en outerHTML . Als de pagina echter is geladen, kunt u de eigenschap innerHTML of outerHTML alleen gebruiken om statische inhoud toe te voegen aan het document. Eventuele opdrachten die zich bevinden in de tekenreeks die is toegewezen aan innerHTML of outerHTML en die worden geëvalueerd naar uitvoerbare code, worden genegeerd. Als u bijvoorbeeld een kenmerk om een gebeurtenis terug te roepen (callback) opneemt in een elementdefinitie, wordt de gebeurtenislistener niet toegevoegd. Op dezelfde manier worden ingesloten tags van het type <script> niet geëvalueerd. Zie HTML-beveiliging in Adobe AIR voor meer informatie.

Het gebruik van de methoden write() en writeln() is niet beperkt in de toepassingssandbox vóór de paginagebeurtenis load . Als de pagina echter is geladen, wordt bij het oproepen van een van deze methoden de pagina niet gewist en wordt er ook geen nieuwe pagina gemaakt. In een niet-toepassingssandbox wordt, net zoals bij de meeste webbrowsers, door het oproepen van document.write() of writeln() nadat een pagina geheel is geladen, de huidige pagina gewist en wordt een nieuwe lege pagina geopend.

Hiermee stelt u de eigenschap document.designMode in op de waarde on als u alle elementen in het document bewerkbaar wilt maken. Met de ingebouwde editor kunt u tekst bewerken, kopiëren, plakken, slepen en neerzetten. Het instellen van designMode op on is equivalent met het instellen van de eigenschap contentEditable van het element body op true . U kunt de eigenschap contentEditable voor de meeste HTML-elementen gebruiken om te definiëren welke secties van een document kunnen worden bewerkt. Zie Het HTML-kenmerk contentEditable voor meer informatie.

In de tag frameset of body van het bovenste niveau van een venster (inclusief het hoofdvenster van de toepassing), mag u de gebeurtenis unload niet gebruiken om te reageren op het venster dat of de toepassing die wordt gesloten. In plaats daarvan gebruikt u de gebeurtenis exiting van het NativeApplication-object (om te bepalen wanneer een toepassing wordt gesloten). U kunt ook de gebeurtenis closing van het NativeApplication-object gebruiken (om te bepalen wanneer een toepassing wordt gesloten). De volgende JavaScript-code geeft bijvoorbeeld het bericht "Goodbye" weer wanneer de gebruiker de toepassing sluit:

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

Scripts kunnen echter wel succesvol reageren op de gebeurtenis unload die wordt veroorzaakt door navigatie van een frame, iframe of vensterinhoud van het bovenste niveau.

Het Window-object blijft het globale object binnen de JavaScript-uitvoeringscontext. In de toepassingssandbox voegt AIR nieuwe eigenschappen toe aan het JavaScript-object Window ten einde toegang te geven tot de ingebouwde AIR-klassen en belangrijke hostobjecten. Verder vertonen bepaalde methoden en eigenschappen binnen de toepassingssandbox ander gedrag dan daarbuiten.

De eigenschap Window.runtime

De eigenschap runtime stelt u in staat om de ingebouwde runtimeklassen te instantiëren en te gebruiken vanuit de toepassingssandbox. Deze klassen omvatten de AIR- en Flash Player-API's (maar bijvoorbeeld niet het Flex-framework). Met de volgende opdracht maakt u bijvoorbeeld een AIR-bestandsobject:

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

Het bestand AIRAliases.js , dat zich bevindt in de AIR SDK, bevat aliasdefinities waarmee u dergelijke verwijzingen kunt verkorten. Als AIRAliases.js bijvoorbeeld in een pagina wordt geïmporteerd, kan een File-object worden gemaakt met de volgende opdracht:

var preferencesFile = new air.File();

De eigenschap window.runtime is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes.

Zie Het bestand AIRAliases.js gebruiken .

De eigenschap Window.nativeWindow

De eigenschap nativeWindow biedt een verwijzing naar het onderliggende native Window-object. Met deze eigenschap kunt u vensterfuncties en eigenschappen zoals schermpositie, grootte en zichtbaarheid in een script opnemen. Ook kunt u venstergebeurtenissen zoals sluiten, grootte wijzigen en verplaatsen hiermee verwerken. Met de volgende opdracht sluit u bijvoorbeeld het venster:

window.nativeWindow.close();

Opmerking: De functies voor vensterbesturing die worden geboden door het NativeWindow-object, overlappen de functies die worden geboden door het JavaScript-object Window. In dergelijke gevallen kunt u de methode gebruiken die u het handigst vindt.

De eigenschap window.nativeWindow is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes.

De eigenschap Window.htmlLoader

De eigenschap htmlLoader biedt een referentie voor het AIR-object HTMLLoader dat de HTML-inhoud bevat. Met deze eigenschap kunt u het uiterlijk en het gedrag van de HTML-omgeving in een script opnemen. U kunt bijvoorbeeld de eigenschap htmlLoader.paintsDefaultBackground gebruiken om te bepalen of het besturingselement een standaard witte achtergrond gebruikt:

window.htmlLoader.paintsDefaultBackground = false;

Opmerking: Het HTMLLoader-object zelf heeft een eigenschap window die verwijst naar het JavaScript-object Window van de HTML-inhoud die het bevat. U kunt deze eigenschap gebruiken om toegang te krijgen tot de JavaScript-omgeving via een verwijzing naar de bevattende HTMLLoader.

De eigenschap window.htmlLoader is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes.

De eigenschappen Window.parentSandboxBridge en Window.childSandboxBridge

Met de eigenschappen parentSandboxBridge en childSandboxBridge kunt u een interface definiëren tussen een bovenliggend en een onderliggend frame. Zie Cross-scripting van inhoud in verschillende beveiligingssandboxen voor meer informatie.

De functies Window.setTimeout() en Window.setInterval()

AIR past beveiligingsbeperkingen toe op het gebruik van de functies setTimeout() en setInterval() binnen de toepassingssandbox. U kunt de code die moet worden uitgevoerd, niet definiëren als tekenreeks bij het oproepen van setTimeout() of setInterval() . U moet hiervoor een functieverwijzing gebruiken. Zie setTimeout() en setInterval() voor meer informatie.

De functie Window.open()

Wanneer de methode open() wordt opgeroepen door code die wordt uitgevoerd in een niet-toepassingssandbox, wordt er als gevolg van gebruikersinteractie (bijvoorbeeld een muisklik of het indrukken van een toets) alleen een venster geopend. Verder staat de toepassingstitel vóór de venstertitel (om te verhinderen dat vensters die worden geopend door externe inhoud, zich voordoen als vensters die worden geopend door de toepassing). Zie Beperkingen betreffende het oproepen van de JavaScript-methode window.open() voor meer informatie.

Het NativeApplication-object biedt informatie over de toepassingsstatus, verzendt verschillende belangrijke gebeurtenissen op toepassingsniveau en biedt nuttige functies voor het beheer van het gedrag van de toepassing. Er wordt automatisch één instantie van het NativeApplication-object gemaakt. Deze kan worden benaderd via de door de klasse gedefinieerde eigenschap NativeApplication.nativeApplication .

Om vanuit JavaScript-code toegang te krijgen tot het object, kunt u het volgende gebruiken:

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

Als het script AIRAliases.js is geïmporteerd, kunt u ook de kortere vorm gebruiken:

var app = air.NativeApplication.nativeApplication;

U kunt het NativeApplication-object alleen benaderen vanuit de toepassingssandbox. Zie Werken met AIR-runtime- en besturingssysteeminformatie voor meer informatie over het NativeApplication-object.

Uitvoering van code die is gedefinieerd in een JavaScript URL-schema (zoals in href="javascript:alert('Test')" ), wordt geblokkeerd binnen de toepassingssandbox. Er treedt geen fout op.