JavaScript i AIR

AIR placerar innehåll i isolerade sandlådor enligt innehållets ursprung. Sandlådereglerna följer principen för samma ursprung som används i de flesta webbläsare, samt reglerna för sandlådor som används i Adobe Flash Player. AIR tillhandahåller dessutom en ny sandlåda av typen application som innehåller och skyddar programinnehåll. Mer information om vilka typer av sandlådor som du kan träffa på när du utvecklar AIR-program finns i Säkerhetssandlådor.

Det är bara HTML och JavaScript som körs i sandlådan application som kan få åtkomst till körningsmiljön och AIR-API:erna. Samtidigt är dynamisk utvärdering och körning av JavaScript, i dess olika former, starkt begränsad inom sandlådan application av säkerhetsskäl. Dessa begränsningar tillämpas oavsett om programmet läser in information direkt från en server eller inte. (Även filinnehåll, inklistrade strängar och direkta användarinmatningar kan vara otillförlitliga.)

Ursprunget till innehållet på en sida avgör vilken sandlåda som ska användas. Det är bara innehåll som läses in från programkatalogen (installationskatalogen som refereras av URL-schemat app: ) som placeras i sandlådan application. Innehåll som läses in från filsystemet placeras i sandlådan lokal-med-filsystem eller lokal-tillförlitlig, som också medger åtkomst och interaktion med innehåll i det lokala filsystemet, men inte fjärrinnehåll. Innehåll som läses in från nätverket placeras i en fjärrsandlåda som motsvarar ursprungsdomänen.

Om du vill tillåta programsidan att samverka fritt med innehåll i en fjärrsandlåda, kan du mappa sidan till samma domän som fjärrinnehållet. Om du till exempel skriver ett program som visar kartuppgifter från en Internettjänst, kan sidan i programmet som läser in och visar innehåll från tjänsten mappas till tjänstedomänen. Attributen för mappning av sidor till en fjärrsandlåda och domän är nya, och har lagts till i HTML-elementen bildruta och iframe.

Om du vill tillåta innehåll i sandlådor av annan typ än application att använda AIR-funktioner på ett säkert sätt, kan du ställa in en överordnad sandlådebrygga. Om du vill tillåta programinnehåll att säkert anropa metoder och få tillgång till egenskaper för innehåll i andra sandlådor, kan du ställa in en underordnad sandlådebrygga. Säkerhet innebär att fjärrinnehåll inte av misstag kan hämta referenser till objekt, egenskaper eller metoder som inte exponeras uttryckligen. Enbart enkla datatyper, funktioner och anonyma objekt kan skickas via bryggan. Du måste emellertid undvika att uttryckligen exponera eventuellt farliga funktioner. Om du till exempel exponerar ett gränssnitt som tillåter att fjärrinnehåll läser och skriver filer var som helst i användarens system, kanske du gör det möjligt för fjärrinnehållet att ställa till med skada.

Det går bara att använda funktionen eval() i sandlådan application en gång när en sida har lästs in. Vissa användningsområden tillåts inte så att JSON-formaterade data kan tolkas på ett säkert sätt, men alla utvärderingar som leder till körbara programsatser ger ett fel. I Kodrestriktioner för innehåll i olika sandlådor beskrivs hur funktionen eval() får användas.

I sandlådan application kan funktionskonstruktorer användas innan en sida har lästs in. När sidans alla load-händelsehanterare har slutförts kan nya funktioner inte skapas.

HTML-sidor i sandlådan application kan inte använda taggen script för att läsa in JavaScript-filer utanför programkatalogen. För att en sida i programmet ska kunna läsa in ett skript utanför programkatalogen, måste den mappas till en annan sandlåda än application.

AIR innehåller ett XMLHttpRequest-objekt (XHR) som program kan använda för att begära data. I följande exempel visas en enkel databegäran:

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

I motsats till en webbläsare tillåter AIR att innehåll som körs i sandlådan application begär data från valfri domän. Resultatet från en XHR som innehåller en JSON-sträng kan utvärderas till dataobjekt, såvida inte resultatet också innehåller körbar kod. Om det finns körbara programsatser i XHR-resultatet returneras ett fel och utvärderingsförsöket misslyckas.

Kodinjektioner från fjärrkällor förhindras genom att synkrona XHR:er returnerar ett tomt resultat om de görs innan en sida har laddats färdigt. Asynkrona XHR:er returneras alltid efter att sidan har laddats.

AIR blockerar som standard korsdomäns-XMLHttpRequests i andra sandlådor än application. Ett överordnat fönster i sandlådan application kan välja att tillåta korsdomänsförfrågningar i en underordnad bildruta som rymmer innehåll i en annan sandlåda än application genom att ställa in allowCrossDomainXHR, ett attribut som tillförs av AIR, på true i det innehållande bildrute- eller iframe-elementet:

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

Om du skickar en XMLHttpRequest till en fjärrserver från en bildruta eller iframe som rymmer programinnehåll som har mappats till en fjärrsandlåda, ska du se till att mappnings-URL:en inte maskar serveradressen som används i XHR. Ta en titt på följande iframe-definition, som mappar programinnehåll till en fjärrsandlåda för domänen example.com:

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

Eftersom attributet sandboxRoot mappar om rot-URL:en för adressen www.example.com, läses alla förfrågningar in från programkatalogen och inte från fjärrservern. Förfrågningar mappas om oavsett om de härleds från sidnavigering eller från en XMLHttpRequest.

Om du vill undvika att blockera dataförfrågningar till fjärrservern av misstag, ska du mappa sandboxRoot till en underkatalog hos fjärr-URL:en i stället för roten. Katalogen behöver inte finnas. Om du till exempel vill tillåta att förfrågningar till www.example.com läses in från fjärrservern i stället för programkatalogen, ändrar du föregående iframe till följande:

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

I det här fallet läses bara innehåll i underkatalogen air in lokalt.

Mer information om mappning av sandlådor finns i Bildrute- och iframe-element i HTML och HTML-säkerhet i Adobe AIR.

I AIR-program kan bara innehåll i fjärrsandlådor (innehåll som läses in från http- och https- källor) använda cookies (egenskapen document.cookie). Andra sätt att spara beständiga data finns i programmets sandlåda, bland annat via klasserna EncryptedLocalStore, SharedObject och FileStream.

API:et WebKit Clipboard drivs av följande händelser: copy, cut och paste. Händelseobjektet som skickas i dessa händelser ger åtkomst till Urklipp via egenskapen clipboardData. Använd följande metoder för objektet clipboardData när du vill läsa eller skriva urklippsdata:

JavaScript-kod som finns utanför sandlådan application kan bara få tillgång till Urklipp via dessa händelser. Innehåll i sandlådan application kan emellertid få tillgång till systemurklipp direkt via AIR-klassen Clipboard. Du kan till exempel använda följande programsats om du vill hämta textformatdata i Urklipp:

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

Giltiga MIME-typer för data är:

Mer information om hur du använder Urklipp finns i Kopiera och klistra in och i Using the Pasteboard from JavaScript (Apple Developer Center).

Att dra och släppa till och från HTML skapar följande DOM-händelser: dragstart, drag, dragend, dragenter, dragover, dragleave och drop. Händelseobjektet som skickas i dessa händelser ger åtkomst till data som dras via egenskapen dataTransfer. Egenskapen dataTransfer refererar till ett objekt som omfattar samma metoder som objektet clipboardData som associeras med en urklippshändelse. Du kan till exempel använda följande funktion om du vill hämta textformatdata från en drop-händelse:

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

Objektet dataTransfer har följande viktiga medlemmar:

Mer information om hur du tillför stöd för dra och släpp i ett AIR-program finns i Dra och släppa i AIR och i Using the Drag-and-Drop from JavaScript (Apple Developer Center).

I AIR gäller säkerhetsbegränsningar för hur egenskaperna innerHTML och outerHTML används för innehåll som körs i sandlådan application. Innan sidläsningshändelsen, och under körningen av alla inläsningshändelsehanterare, går det att använda egenskaperna innerHTML och outerHTML utan begränsningar. När sidan väl har lästs in kan du emellertid bara använda egenskapen innerHTML eller outerHTML för att lägga till statiskt innehåll i dokumentet. Alla programsatser i strängen som tilldelas innerHTML eller outerHTML som utvärderas till körbar kod ignoreras. Om du till exempel inkluderar ett händelseåterkopplingsattribut i en elementdefinition läggs händelseavlyssnaren inte till. Inbäddade <script>-taggar utvärderas inte heller. Du hittar mer information i HTML-säkerhet i Adobe AIR.

Användningen av metoderna write() och writeln() är inte begränsad i sandlådan application före sidans load-händelse. När sidan väl har lästs in och du anropar någon av dessa metoder kommer ingen sida att rensas och ingen ny att skapas. I en annan sandlåda än application, liksom i de flesta webbläsare, rensas den aktuella sidan och en ny, tom öppnas om du anropar document.write() eller writeln() efter att sidan har lästs in.

Ställ in egenskapen document.designMode på värdet on om du vill att alla element i dokumentet ska kunna redigeras. Det inbyggda redigeringsstödet omfattar textredigering, kopiera, klistra in samt dra och släpp. Att ställa in designMode på on motsvarar att ställa in egenskapen contentEditable för elementet body på true. Du kan använda egenskapen contentEditable för de flesta HTML-element om du vill definiera vilka avsnitt i ett dokument som ska kunna redigeras. Mer information finns i HTML-attributet contentEditable.

I taggen frameset eller body på den översta nivån för ett fönster (bland annat programmets huvudfönster) ska du inte använda händelsen unload för att svara på fönstret (eller programmet) som stängs. I stället använder du händelsen exiting för objektet NativeApplication (för att identifiera när programmet stängs). Du kan också använda händelsen closing för objektet NativeWindow (för att identifiera när ett fönster stängs). I följande JavaScript-skriptkod visas meddelandet ("Goodbye.") när användaren stänger programmet:

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

Skript kan emellertid lyckas svara på unload-händelsen som orsakas av navigering för en bildruta, iframe eller fönsterinnehåll på den översta nivån.

Window-objektet är fortfarande det globala objektet när det gäller JavaScript-körning. I sandlådan application tillför AIR nya egenskaper till JavaScript-objektet Window som ger tillgång till de inbyggda AIR-klasserna samt viktiga värdobjekt. Vissa metoder och egenskaper beter sig dessutom olika beroende på om de finns i sandlådan application eller inte.

Egenskapen Window.runtime

Med egenskapen runtime kan du instansiera och använda inbyggda körningsklasser från sandlådan application. Dessa klasser omfattar AIR- och Flash Player-API:er (men inte till exempel Flex-ramverket). Följande programsatser skapar ett AIR-filobjekt:

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

Filen AIRAliases.js, som finns i AIR SDK, innehåller aliasdefinitioner som gör att du kan korta av sådana referenser. När till exempel AIRAliases.js importeras till en sida, kan ett File-objekt skapas med följande programsats:

var preferencesFile = new air.File();

Egenskapen window.runtime definieras bara för innehåll i sandlådan application och bara för det överordnade dokumentet på en sida med bildrutor och iframes.

Se Använda filen AIRAliases.js.

Egenskapen Window.nativeWindow

Egenskapen nativeWindow innehåller en referens till det underliggande inbyggda fönsterobjektet. Med den här egenskapen kan du skripta fönsterfunktioner och -egenskaper som skärmplacering, storlek och synlighet, och hantera fönsterhändelser som att stänga, ändra storlek på och flytta. I följande programsats stängs fönstret:

window.nativeWindow.close();

Obs! De fönsterkontrollfunktioner som ingår i objektet NativeWindow överlappar funktionerna som finns i JavaScript-objektet Window. I sådana fall kan du välja den metod som passar bäst.

Egenskapen window.nativeWindow definieras bara för innehåll i sandlådan application och bara för det överordnade dokumentet på en sida med bildrutor och iframes.

Egenskapen Window.htmlLoader

Egenskapen htmlLoader innehåller en referens till AIR-objektet HTMLLoader som rymmer HTML-innehållet. Med den här egenskapen kan du skripta utseende och beteende i HTML-miljön. Du kan till exempel använda egenskapen htmlLoader.paintsDefaultBackground för att ta reda på om kontrollen målar en standardbakgrund i vitt:

window.htmlLoader.paintsDefaultBackground = false;

Obs! Själva HTMLLoader-objektet har en window-egenskap som refererar till JavaScript-objektet Window för HTML-innehållet som det rymmer. Du kan använda den här egenskapen när du vill få åtkomst till JavaScript-miljön via en referens till det innehållande HTMLLoader.

Egenskapen window.htmlLoader definieras bara för innehåll i sandlådan application och bara för det överordnade dokumentet på en sida med bildrutor och iframes.

Egenskaperna Window.parentSandboxBridge och Window.childSandboxBridge

Med egenskaperna parentSandboxBridge och childSandboxBridge kan du definiera ett gränssnitt mellan en överordnad och underordnad bildruta. Mer information finns i Korsskriptning av innehåll i olika säkerhetssandlådor.

Funktionerna Window.setTimeout() och Window.setInterval()

I AIR finns säkerhetsbegränsningar för hur funktionerna setTimeout() och setInterval() används i sandlådan application. Du kan inte definiera koden som ska köras som en sträng när setTimeout() eller setInterval() anropas. Du måste använda en funktionsreferens. Mer information finns i setTimeout() och setInterval().

Window.open(), funktion

När metoden open() anropas av kod som körs i en annan sandlåda än application, öppnas bara ett fönster vid ett anrop som kommer från användarens åtgärder (till exempel klick med musen eller tryck på en tangent). Fönsterrubriken inleds dessutom med programnamnet (så att fönstret inte öppnas av fjärrinnehållet från imiterande fönster som öppnas av programmet). Mer information finns i Begränsningar för anrop till JavaScript-metoden window.open().

Objektet NativeApplication tillhandahåller information om programmets läge, skickar flera viktiga händelser på programnivå och tillhandahåller användbara funktioner för styrning av programmets beteende. En enskild instans av objektet NativeApplication skapas automatiskt och kan nås via den klassdefinierade egenskapen NativeApplication.nativeApplication.

Om du vill få tillgång till objektet från JavaScript-koden kan du använda:

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

Om AIRAliases.js-skriptet har importerats, kan du i stället använda det kortare formatet:

var app = air.NativeApplication.nativeApplication;

Objektet NativeApplication kan bara nås från sandlådan application. Mer information om objektet NativeApplication finns i Arbeta med körtids- och operativsystemsinformation i AIR.

Det går inte att köra kod som definieras i ett JavaScript URL-schema (som i href="javascript:alert('Test')") i sandlådan application. Inget fel returneras.