AIR'de JavaScript

AIR içeriği kaynağına bağlı olarak, ayrı sanal alanlara yerleştirir. Sanal alan kuralları, Adobe Flash Player tarafından uygulanan sanal alan kurallarının yanı sıra, çoğu web tarayıcısı tarafından uygulanan aynı kaynak ilkesiyle tutarlıdır. Ayrıca AIR, uygulama içeriğini dahil etmek ve korumak için yeni bir uygulama sanal alan türü sağlar. AIR uygulamalarını geliştirirken karşılaşabileceğiniz sanal alan türleriyle ilgili daha fazla bilgi için, bkz. Güvenlik sanal alanları.

Çalışma zamanı ortamına ve AIR API'lerine erişim yalnızca uygulama sanal alanının içinden HTML ve JavaScript'in çalıştırılmasıyla mümkündür. Ancak aynı zamanda çeşitli biçimlerdeki dinamik JavaScript değerlendirmesi ve çalışması, güvenlik nedenleriyle büyük ölçüde uygulama sanal alanıyla sınırlıdır. Bu kısıtlamalar, uygulamanız doğrudan bir sunucudan bilgi yüklese de yüklemese de geçerlidir. (Hatta dosya içeriği, yapıştırılan dizeler ve doğrudan kullanıcı girişi güvenilmez olabilir.)

Bir sayfadaki içeriğin kaynağı, gönderildiği sanal alanı belirler. Yalnızca uygulama dizininden yüklenen içerik (app: URL şeması tarafından başvurulan yükleme dizini) uygulama sanal alanına yerleştirilir. Dosya sisteminden yüklenen içerik local-with-filesystem veya local-trusted sanal alanına yerleştirilir, böylece yerel dosya sistemindeki içeriğe erişimine ve bu içerikle etkileşimine izin verilir, ancak uzak içeriğe erişimine izin verilmez. Ağdan yüklenen içerik, kaynak etki alanına karşılık gelen uzak bir sanal alana yerleştirilir.

Bir uygulama sayfasının uzak sanal alandaki içerikle serbestçe etkileşmesini sağlamak için, sayfa, uzak içerikle aynı etki alanına eşlenebilir. Örneğin bir Internet hizmetinden eşleme verileri görüntüleyen bir uygulama yazarsanız, uygulamanızın hizmetten içerik yükleyen ve görüntüleyen sayfası hizmet etki alanına eşlenebilir. Sayfaları uzak sanal alana ve etki alanına eşleme nitelikleri, kare ve iframe HTML öğelerine eklenen yeni niteliklerdir.

Uygulama dışı bir sanal alandaki içeriğin AIR özelliklerini güvenli bir şekilde kullanmasını sağlamak için, üst sanal alan köprüsü kurabilirsiniz. Uygulama içeriğinin yöntemleri güvenli bir şekilde çağırmasını ve diğer sanal alanlardaki içeriğin özelliklerine erişmesini sağlamak için, alt sanal alan köprüsü kurabilirsiniz. Güvenli burada uzak içeriğin açık olmayan nesnelere, özelliklere veya yöntemlere yanlışlıkla başvuru alamaması anlamına gelir. Yalnızca basit veri türleri, işlevler ve adsız nesneler köprüden geçirilebilir. Ancak yine de tehlikeli olabilecek işlevleri açmaktan kaçınmalısınız. Örneğin, bir kullanıcının sisteminde bulunan dosyaları okumayı ve dosyalara yazmayı sağlayan bir arabirimi açtıysanız, uzak içeriğe, kullanıcılarınıza önemli zararlar verebileceği bir yöntem sağlıyor olabilirsiniz.

Sayfa, yükleme işlemini bitirdiğinde, eval() işlevinin kullanımı uygulama sanal alanıyla sınırlanır. Bazı kullanımlara izin verilir ve böylece JSON biçimli veriler güvenli bir şekilde ayrıştırılabilir, ancak çalıştırılabilir bir ifadeyle sonuçlanan herhangi bir değerlendirme hatayla sonuçlanır. Farklı sanal alanlardaki içerik için kod kısıtlamaları, eval() işlevinin izin verilen kullanımlarını açıklar.

Uygulama sanal alanında, bir sayfa yükleme işlemini bitirmeden önce işlev yapıcıları kullanılabilir. Tüm sayfa load olayı işleyicileri bittikten sonra, yeni işlevler oluşturulamaz.

Uygulama sanal alanındaki HTML sayfaları, JavaScript dosyalarını uygulama dizininin dışından yüklemek için script etiketini kullanamaz. Uygulamanızdaki bir sayfaya uygulama dizininin dışından bir komut dosyası yüklenmesi için,, sayfa uygulama dışı bir sanal alana eşlenmelidir.

AIR, uygulamaların veri istekleri gerçekleştirebilmek için kullanabileceği bir XMLHttpRequest (XHR) nesnesi sağlar. Aşağıdaki örnek basit bir veri isteğini gösterir:

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

Bir tarayıcıya karşılık AIR, uygulama sanal alanında çalışan içeriğin herhangi bir etki alanından veri isteğinde bulunmasına olanak tanır. Bir JSON dizesi içeren XHR'nin sonucu, sonuç çalıştırılabilir kod içermediği sürece veri nesneleri olarak değerlendirilebilir. XHR sonucunda çalıştırılabilir ifadeler mevcutsa, bir hata verilir ve değerlendirme denemesi başarısız olur.

Uzak kaynaklardaki kodun yanlışlıkla dahil edilmesini engellemek için bu işlem sayfa, yükleme işlemini bitirmeden önce yapılırsa senkronize XHR'ler boş bir sonuç döndürür. Senkronize olmayan XHR'ler her zaman bir sayfa yüklendikten sonra geri döner.

Varsayılan olarak AIR, uygulama dışı sanal alanlardaki etki alanları arası XMLHttpRequest öğelerini engeller. Uygulama sanal alanındaki bir üst pencere, uygulama dışı sanal alanda içeriğe sahip olan bir alt karedeki etki alanları arası isteklere, AIR tarafından eklenen bir nitelik olan allowCrossDomainXHR öğesini içeriğe sahip olan kare veya iframe öğesini true olarak ayarlayarak izin vermeyi seçebilir:

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

Bir XMLHttpRequest öğesini uzak sanal alana eşlenmiş uygulama içeriğine sahip olan frame veya iframe'den uzak bir sunucuya gönderirseniz, eşleme URL'sinin XHR'de kullanılan sunucu adresini maskelemediğinden emin olun. Örneğin example.com etki alanı için uygulama içeriğini uzak bir sanal alana eşleyen aşağıdaki iframe tanımını göz önünde bulundurun:

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

sandboxRoot niteliği www.example.com adresinin kök URL'sini yeniden eşlediği için, tüm istekler uzak sunucudan değil, uygulama dizininden yüklenir. Sayfa gezinmesinden veya XMLHttpRequest öğesinden türetilen istekler yeniden eşlenir.

Uzak sunucunuza yapılan veri isteklerini yanlışlıkla engellemeyi önlemek için, sandboxRoot öğesini köke değil, uzak URL'nin alt dizinine eşleyin. Dizinin mevcut olması gerekmez. Örneğin, uygulama dizini yerine uzak sunucudan yükleme yapabilmek için www.example.com adresine yapılan veri isteklerine izin vermek üzere, önceki iframe'i şu şekilde değiştirin:

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

Bu durumda yalnızca air alt dizinindeki içerik yerel olarak yüklenir.

Sanal alan eşlemesiyle ilgili daha fazla bilgi için, bkz. HTML kare ve iframe öğeleri ve Adobe AIR'de HTML güvenliği.

AIR uygulamalarında yalnızca uzak sanal alanlardaki içerik (http: ve https: kaynaklarından yüklenen), tanımlama bilgilerini kullanabilir (document.cookie özelliği). Uygulama sanal alanında, kalıcı verileri saklamak için başka yollar da mevcuttur, bunlara EncryptedLocalStore, SharedObject ve FileStream sınıfları dahildir.

WebKit Clipboard API'si şu olaylarla yürütülür: copy, cut ve paste. Bu olaylarda geçen olay nesnesi clipboardData özelliğiyle panoya erişim sağlar. Pano verilerini okumak veya bu verileri yazmak için aşağıdaki clipboardData nesnesi yöntemlerini kullanın:

Uygulama sanal alanının dışındaki JavaScript kodu panoya yalnızca bu olayları kullanarak erişebilir. Ancak uygulama sanal alanındaki içerik, AIR Clipboard sınıfını kullanarak sistem panosuna doğrudan erişebilir. Örneğin panodaki metin biçimi verilerini almak için aşağıdaki ifadeyi kullanabilirsiniz:

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

Geçerli veri MIME türleri şunlardır:

Panoyu kullanmayla ilgili daha fazla bilgi için bkz. Kopyalama ve yapıştırma ve Using the Pasteboard from JavaScript (Apple Geliştirici Merkezi) (JavaScript'te Yapıştırma Alanı'nı Kullanma).

HTML'e doğru veya HTML'den sürükle ve bırak hareketleri şu DOM olaylarını üretir: dragstart, drag, dragend, dragenter, dragover, dragleave ve drop. Bu olaylarda geçen olay nesnesi, dataTransfer özelliğiyle sürüklenen verilere erişim sağlar. dataTransfer özelliği, bir clipboard olayıyla ilişkilendirilen clipboardData nesnesiyle aynı yöntemleri sağlayan bir nesneye başvurur. Örneğin bir drop olayından metin biçimi verileri almak için şu işlevi kullanabilirsiniz:

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

dataTransfer nesnesinin sahip olduğu önemli üyeler şunlardır:

AIR uygulamasına sürükle ve bırak eylemine yönelik destek eklemeyle ilgili daha fazla bilgi için bkz. AIR uygulamasında taşıma ve bırakma ve Using the Drag-and-Drop from JavaScript (Apple Geliştirici Merkezi) (JavaScript'te Sürükleme ve Bırakmayı Kullanma).

AIR, uygulama sanal alanında çalışan içerik için innerHTML ve outerHTML özelliklerinin kullanılmasına yönelik güvenlik kısıtlamaları getirir. load olayı işleyicilerinin çalıştırılması sırasında ve sayfa load olayından önce, innerHTML ve outerHTML özelliklerinin kullanımında hiçbir kısıtlama yoktur. Ancak sayfa yüklendikten sonra, innerHTML veya outerHTML özelliklerini yalnızca belgeye statik içerik eklemek için kullanabilirsiniz. Çalıştırılabilir kod olarak değerlendirilen innerHTML veya outerHTML özelliklerine atanan bir dizede bulunan herhangi bir ifade yok sayılır. Örneğin bir olay geri çağırma niteliğini öğe tanımına dahil ederseniz, olay dinleyicisi eklenmez. Benzer şekilde, gömülü <script> etiketleri de değerlendirilmez. Daha fazla bilgi için, bkz. Adobe AIR'de HTML güvenliği.

Sayfanın load olayından önce uygulama sanal alanında write() ve writeln() yöntemlerinin kullanımı kısıtlı değildir. Ancak sayfa yüklendikten sonra, bu yöntemlerden birini çağırmak sayfayı temizlemez veya yeni bir sayfa oluşturmaz. Birçok web tarayıcısında olduğu gibi, bir sayfa yüklenmesini bitirdikten sonra uygulama dışı sanal alanda document.write() veya writeln() yöntemini çağırmak geçerli sayfayı temizler ve yeni, boş bir sayfa açar.

Belgedeki tüm öğelerin düzenlenebilir olması için document.designMode özelliğini on olan bir değere ayarlayın. Yerleşik düzenleyici desteği metin düzenleme, kopyalama, yapıştırma ve sürükleyip bırakmayı içerir. designMode özelliğinin on olarak ayarlanması, body öğesinin contentEditable özelliğinin true olarak ayarlanmasına eşdeğerdir. Bir belgenin hangi bölümlerinin düzenlenebilir olacağını tanımlamak için çoğu HTML öğesinde contentEditable özelliğini kullanabilirsiniz. Ek bilgi için bkz. HTML contentEditable niteliği.

Bir pencerenin üst düzey frameset veya body etiketinde (uygulamanın ana penceresi de dahil olmak üzere), kapanan pencereye (veya uygulamaya) yanıt vermek için unload olayını kullanmayın. Bunun yerine NativeApplication nesnesinin exiting olayını kullanın (uygulamanın ne zaman kapandığını saptamak için). Veya NativeWindow nesnesinin closing olayını kullanın (pencerenin ne zaman kapandığını saptamak için). Örneğin aşağıdaki JavaScript kodu, kullanıcı uygulamayı kapattığında ("Goodbye.") mesajını görüntüler:

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

Ancak komut dosyaları, bir karenin, iframe'in veya üst düzey pencere içeriğinin gezinmesi sonucu oluşan unload olayına başarılı bir şekilde yanıt verebilir.

Window nesnesi, JavaScript çalışma bağlamında global nesne olarak kalır. AIR, uygulama sanal alanında, önemli ana bilgisayar nesnelerinin yanı sıra yerleşik AIR sınıflarına erişim sağlamak için JavaScript Window nesnesine yeni özellikler ekler. Ayrıca, bazı yöntemler ve özellikler, uygulama sanal alanının içinde bulunup bulunmamalarına bağlı olarak farklı davranışlar gösterir.

Window.runtime özelliği

runtime özelliği, yerleşik runtime sınıflarını uygulama sanal alanının içinden başlatmanızı ve kullanmanızı sağlar. Bu sınıflar AIR ve Flash Player API'lerini içerir. (Ancak örneğin Flex çerçevesini içermez.) Örneğin aşağıdaki ifade bir AIR file nesnesi oluşturur:

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

AIR SDK'de sağlanan AIRAliases.js dosyası, bu gibi başvuruları kısaltmanızı sağlayan başka ad tanımları içerir. Örneğin AIRAliases.js bir sayfaya içe aktarıldığında, aşağıdaki ifade kullanılarak bir File nesnesi oluşturulabilir:

var preferencesFile = new air.File();

window.runtime özelliği, yalnızca uygulama sanal alanındaki içerik ve frame veya iframe'ler içeren bir sayfanın üst belgesi için tanımlanır.

Bkz. AIRAliases.js dosyasını kullanma.

Window.nativeWindow özelliği

nativeWindow özelliği, alttaki yerel window nesnesine bir başvuru sağlar. Bu özellik sayesinde ekran konumu, boyutu ve görünürlüğü gibi window işlevlerini ve özelliklerini komut dosyasına yazabilir ve kapatma, yeniden boyutlandırma ve taşıma gibi window olaylarını işleyebilirsiniz. Örneğin aşağıdaki ifade pencereyi kapatır:

window.nativeWindow.close();

Not: NativeWindow nesnesi tarafından sağlanan pencere kontrol özellikleri, JavaScript Window nesnesi tarafından sağlanan özelliklerle örtüşür. Bu gibi durumlarda en uygun bulduğunuz yöntemi kullanabilirsiniz.

window.nativeWindow özelliği, yalnızca uygulama sanal alanındaki içerik ve kareler veya iframe'ler içeren bir sayfanın üst belgesi için tanımlanır.

Window.htmlLoader özelliği

htmlLoader özelliği, HTML içeriğine sahip olan AIR HTMLLoader nesnesine bir başvuru sağlar. Bu özellik sayesinde, HTML ortamının görünümünü ve davranışını komut dosyasına yazabilirsiniz. Örneğin kontrolün varsayılan, beyaz bir arka plan boyayıp boyamadığını belirlemek için htmlLoader.paintsDefaultBackground özelliğini kullanabilirsiniz:

window.htmlLoader.paintsDefaultBackground = false;

Not: HTMLLoader nesnesi window özelliğine sahiptir, bu özellik, sahip olduğu HTML içeriğinin JavaScript Window nesnesine başvurur. Bu özelliği, içeriğe sahip olan HTMLLoader nesnesine bir başvuru yoluyla JavaScript ortamına erişmek için kullanabilirsiniz.

window.htmlLoader özelliği, yalnızca uygulama sanal alanındaki içerik ve kareler veya iframe'ler içeren bir sayfanın üst belgesi için tanımlanır.

Window.parentSandboxBridge ve Window.childSandboxBridge özellikleri

parentSandboxBridge ve childSandboxBridge özellikleri sayesinde, üst ve alt kareler arasında bir arabirim tanımlayabilirsiniz. Daha fazla bilgi için bkz. Farklı güvenlik sanal alanlarında çapraz komut dosyası içeriği.

Window.setTimeout() ve Window.setInterval() işlevleri

AIR, setTimeout() ve setInterval() işlevlerinin uygulama sanal alanında kullanılmasına yönelik güvenlik kısıtlamaları getirir. setTimeout() veya setInterval() işlevlerini çağırırken bir dize olarak çalıştırılacak kodu tanımlayamazsınız. Bir işlev başvurusu kullanmanız gerekir. Daha fazla bilgi için bkz. setTimeout() ve setInterval().

Window.open() işlevi

open() yöntemi uygulama dışı bir sanal alanda çalışan bir kod tarafından çağrıldığında, yalnızca kullanıcı etkileşiminin (fareyi tıklatma veya tuşabasma gibi) bir sonucu olarak çağrılırsa bir pencere açar. Ayrıca, uygulama başlığı pencere başlığına önek olarak getirilir (pencerelerin uzak içerik tarafından açılmasını engellemek için ). Daha fazla bilgi için bkz.JavaScript window.open() yönteminin çağrılmasına ilişkin kısıtlamalar.

NativeApplication nesnesi uygulama durumu hakkında bilgi sağlar, uygulama düzeyi birçok önemli olayı gönderir ve uygulama davranışının kontrol edilmesine yönelik faydalı işlevler sağlar. NativeApplication nesnesinin tek bir örneği otomatik olarak oluşturulur ve bu özelliğe sınıf tanımlı NativeApplication.nativeApplication özelliği yardımıyla erişilebilir.

Nesneye JavaScript kodundan erişmek için şunu kullanabilirsiniz:

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

Veya AIRAliases.js komut dosyası içe aktarılmışsa, daha kısa biçimini kullanabilirsiniz:

var app = air.NativeApplication.nativeApplication;

NativeApplication nesnesine yalnızca uygulama sanal alanından erişilebilir. NativeApplication nesnesiyle daha fazla bilgi için bkz. AIR çalışma zamanı ve işletim sistemi bilgileriyle çalışma.

Bir JavaScript URL şemasında tanımlanan kodu çalıştırma, (href="javascript:alert('Test')" gibi) uygulama sanal alanının içinde engellenmiştir. Hata verilmez.