AIR での JavaScript

AIR では、コンテンツは、そのコンテンツの生成元に従って個別のサンドボックスに配置されます。サンドボックス規則は、Adobe Flash Player で実装されているサンドボックスの規則と同様、ほとんどの Web ブラウザーで実装されている同一生成元ポリシーに従っています。また、AIR には、アプリケーションコンテンツを格納して保護する、新しいアプリケーションサンドボックスタイプが用意されています。AIR アプリケーションの開発時に扱う場合があるサンドボックスのタイプについて詳しくは、セキュリティサンドボックスを参照してください。

ランタイム環境および AIR API へのアクセスは、アプリケーションサンドボックス内で実行される HTML および JavaScript からのみ可能です。ただし、その際、JavaScript の動的な評価と実行は、様々な形で、セキュリティ上の理由からアプリケーションサンドボックス内で大きく制限されます。これらの制限は、実際にアプリケーションでサーバーから直接情報を読み込むかどうかに関わらず適用されます（ファイルコンテンツ、ペーストされたストリングおよび直接ユーザー入力であっても、信頼できない可能性があります）。

ページ内のコンテンツの生成元によって、割り当て先のサンドボックスが決まります。アプリケーションディレクトリ（app: URL スキームで参照するインストールディレクトリ）から読み込まれたコンテンツのみ、アプリケーションサンドボックスに配置されます。ファイルシステムから読み込まれたコンテンツは、local-with-file system サンドボックスまたは local-trusted サンドボックスに配置されます。このサンドボックスでは、ローカルファイルシステム上のコンテンツへのアクセスおよび操作は許可されますが、リモートコンテンツへのアクセスおよび操作は許可されません。ネットワークから読み込まれたコンテンツは、元のドメインに対応するリモートサンドボックスに配置されます。

リモートサンドボックス内のコンテンツをアプリケーションページから自由に操作できるようにするには、リモートコンテンツと同じドメインにページをマップします。例えば、インターネットサービスからマップデータを表示するアプリケーションを作成する場合は、そのサービスからコンテンツを読み込んで表示するアプリケーションのページをサービスドメインにマップします。リモートサンドボックスおよびドメインにページをマップするための属性は、HTML の frame エレメントと iframe エレメントに追加された新しい属性です。

非アプリケーションサンドボックス内のコンテンツで安全に AIR 機能を使用できるようにするには、親サンドボックスブリッジを設定します。アプリケーションコンテンツで他のサンドボックス内のコンテンツのメソッドの呼び出しおよびプロパティへのアクセスを安全に行えるようにするには、子サンドボックスブリッジを設定します。この場合の安全とは、明示的に公開していないオブジェクト、プロパティまたはメソッドに、リモートコンテンツから誤って参照しないようにすることを指します。単純データ型、関数および匿名オブジェクトのみ、ブリッジを介して渡すことができます。ただし、危険性のある関数は明示的に公開しないでください。例えば、ユーザーのシステム上の任意の場所にあるファイルの読み取りと書き込みをリモートコンテンツに許可するインターフェイスを公開すると、ユーザーに多大な被害を与える可能性をリモートコンテンツが持つことになります。

ページの読み込みが完了すると、eval() 関数の使用はアプリケーションサンドボックス内で制限されます。JSON 形式のデータを安全に解析できるように一部の使用は許可されますが、実行可能ステートメントを生成する評価はすべてエラーになります。異なるサンドボックス内のコンテンツに対するコードの制限で、eval() 関数の許可される使用について説明しています。

アプリケーションサンドボックスでは、ページの読み込みが完了する前に関数コンストラクターを使用できます。ページの load イベントハンドラーがすべて終了した後は、新しい関数は作成できません。

アプリケーションサンドボックス内の HTML ページでは、script タグを使用してアプリケーションディレクトリ外から JavaScript ファイルを読み込むことはできません。アプリケーションのページでアプリケーションディレクトリ外からスクリプトを読み込むには、そのページを非アプリケーションサンドボックスにマップする必要があります。

AIR には、アプリケーションでデータ要求を行うために使用できる XMLHttpRequest（XHR）オブジェクトが用意されています。次の例に、簡単なデータ要求を示します。

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

ブラウザーとは対照的に、AIR では、アプリケーションサンドボックス内で実行されるコンテンツは任意のドメインのデータを要求できます。JSON ストリングを含む XHR の結果は、実行可能コードもその結果に含まれる場合を除き、データオブジェクトになります。実行可能ステートメントが XHR 結果で表される場合、エラーがスローされ、評価の試行は失敗します。

リモートソースからコードが意図せず挿入されないようにするため、同期 XHR は、ページの読み込みが完了する前に行われた場合は空の結果を返します。非同期 XHR は、常に、ページが読み込まれた後に返します。

デフォルトでは、AIR は、非アプリケーションサンドボックスでのクロスドメイン XMLHttpRequest をブロックします。アプリケーションサンドボックス内の親ウィンドウでは、非アプリケーションサンドボックス内のコンテンツを含む子フレームでのクロスドメイン要求を許可することを選択できます。それには、コンテナとなっている frame エレメントまたは iframe エレメントで、allowCrossDomainXHR（AIR で追加された属性）を true に設定します。

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

リモートサンドボックスにマップされているアプリケーションコンテンツを含むフレームまたはインラインフレームからリモートサーバーに XMLHttpRequest を送出する場合は、マッピング URL で、XHR で使用するサーバーアドレスをマスクしていないことを確認してください。例えば、example.com ドメインのリモートサンドボックスにアプリケーションコンテンツをマップする、次の iframe 定義について考えます。

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

sandboxRoot 属性は www.example.com アドレスのルート URL を再マップするので、すべての要求はアプリケーションディレクトリから読み込まれ、リモートサーバーからは読み込まれません。要求は、ページナビゲーションと XMLHttpRequest のいずれから発生するかに関わらず、再マップされます。

リモートサーバーへのデータ要求が誤ってブロックされないようにするには、sandboxRoot を、ルートではなくリモート URL のサブディレクトリにマップします。このディレクトリは存在していなくてもかまいません。例えば、www.example.com への要求でアプリケーションディレクトリではなくリモートサーバーからの読み込みを許可するには、上述の iframe を次のように変更します。

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

この場合、air サブディレクトリ内のコンテンツのみローカルに読み込まれます。

サンドボックスのマッピングについて詳しくは、HTML の frame エレメントと iframe エレメントおよび Adobe AIR の HTML セキュリティを参照してください。

AIR アプリケーションでは、リモートサンドボックス内のコンテンツ（http: ソースおよび https: ソースから読み込まれたコンテンツ）のみ、Cookie（document.cookie プロパティ）を使用できます。アプリケーションサンドボックスには、EncryptedLocalStore、SharedObject および FileStream クラスなど、永続データを格納するための他の手段が用意されています。

WebKit Clipboard API は、copy、cut、paste の各イベントによって動作します。これらのイベントで渡されるイベントオブジェクトでは、clipboardData プロパティを使用してクリップボードにアクセスできます。クリップボードのデータを読み取ったり、書き込んだりするには、clipboardData オブジェクトの次のメソッドを使用します。

アプリケーションサンドボックス外の JavaScript コードからクリップボードにアクセスするには、これらのイベントを使用する必要があります。ただし、アプリケーションサンドボックス内のコンテンツでは、AIR の Clipboard クラスを使用してシステムクリップボードに直接アクセスできます。例えば、次のステートメントを使用すると、クリップボードのテキスト形式のデータを取得できます。

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

データの有効な MIME タイプは、次のとおりです。

クリップボードの使用について詳しくは、コピー＆ペーストおよび「JavaScript からのペーストボードの使用（Apple デベロッパーセンター）」を参照してください。

HTML への、また HTML からのドラッグ＆ドロップ操作は、dragstart、drag、dragend、dragenter、dragover、dragleave、drop の各 DOM イベントを発生させます。これらのイベントで渡されるイベントオブジェクトでは、dataTransfer プロパティを使用してドラッグしたデータにアクセスできます。dataTransfer プロパティは、クリップボードイベントに関連付けられている clipboardData オブジェクトと同じメソッドを備えたオブジェクトを参照します。例えば、次の関数を使用すると、drop イベントからテキスト形式のデータを取得できます。

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

dataTransfer オブジェクトには、次の重要なメンバーがあります。

AIR アプリケーションにドラッグ＆ドロップのサポートを追加する方法について詳しくは、AIR でのドラッグ＆ドロップおよび「JavaScript からのドラッグ＆ドロップの使用（Apple デベロッパーセンター）」を参照してください。

AIR では、アプリケーションサンドボックス内で実行されるコンテンツの innerHTML プロパティと outerHTML プロパティの使用に対して、セキュリティ制限が適用されます。ページの load イベントの前、また load イベントハンドラーの実行中は、innerHTML プロパティと outerHTML プロパティの使用は制限されません。ただし、ページが読み込まれると、innerHTML プロパティまたは outerHTML プロパティを使用できるのは、ドキュメントへの静的コンテンツの追加に限定されます。実行可能コードになる、innerHTML または outerHTML に割り当てられたストリング内のステートメントは、すべて無視されます。例えば、イベントのコールバック属性をエレメント定義に含めると、イベントリスナーは追加されません。同様に、埋め込みの <script> タグは評価されません。詳しくは、Adobe AIR の HTML セキュリティを参照してください。

ページの load イベントの前は、write() メソッドと writeln() メソッドの使用はアプリケーションサンドボックスで制限されません。ただし、ページが読み込まれると、これらのメソッドのいずれかを呼び出しても、ページがクリアされることも新しいページが作成されることもありません。非アプリケーションサンドボックスでは、ほとんどの Web ブラウザーの場合と同様に、ページの読み込み完了後に document.write() または writeln() を呼び出すと、現在のページがクリアされ、新しい空白のページが開かれます。

ドキュメント内のすべてのエレメントを編集可能にするには、document.designMode プロパティを値 on に設定します。ビルトインエディターのサポートに含まれるのは、テキストの編集、コピー、ペーストおよびドラッグ＆ドロップです。designMode を on に設定することは、body エレメントの contentEditable プロパティを true に設定することと同じです。編集可能にするドキュメントのセクションを定義するため、HTML エレメントのほとんどで contentEditable プロパティを使用できます。詳しくは、HTML の contentEditable 属性を参照してください。

ウィンドウ（アプリケーションのメインウィンドウを含む）のトップレベルの frameset タグまたは body タグでは、閉じられるウィンドウ（またはアプリケーション）への応答に unload イベントを使用しないでください。代わりに、NativeApplication オブジェクトの exiting イベントを使用します（アプリケーションが終了するときを検出するために使用）。または、NativeWindow オブジェクトの closing イベントを使用します（ウィンドウが閉じるときを検出するために使用）。例えば、次の JavaScript コードでは、ユーザーがアプリケーションを閉じるときにメッセージ（「Goodbye.」）を表示します。

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

ただし、スクリプトでは、フレーム、インラインフレームまたはトップレベルウィンドウのコンテンツのナビゲーションによって発生した unload イベントに正常に応答できます。

Window オブジェクトは、JavaScript 実行コンテキストではグローバルオブジェクトのままです。アプリケーションサンドボックスでは、重要なホストオブジェクトと同様、AIR のビルトインクラスへのアクセスを提供するため、新しいプロパティが JavaScript の Window オブジェクトに追加されます。また、一部のメソッドとプロパティは、アプリケーションサンドボックス内であるかどうかによって動作が異なります。

Window.runtime プロパティ

runtime プロパティを使用すると、アプリケーションサンドボックス内から、ビルトインのランタイムクラスをインスタンス化して使用できます。これらのクラスには、AIR および Flash Player の API が含まれます（ただし、Flex フレームワークなどは含まれません）。例えば、次のステートメントでは、AIR ファイルオブジェクトを作成します。

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

AIR SDK に付属する AIRAliases.js ファイルには、このような参照を短くすることができるエイリアス定義が含まれています。例えば、AIRAliases.js をページに読み込むと、次のステートメントで File オブジェクトを作成できます。

var preferencesFile = new air.File();

window.runtime プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフレームがあるページの親ドキュメントのためだけに定義されています。

AIRAliases.js ファイルの使用を参照してください。

Window.nativeWindow プロパティ

nativeWindow プロパティは、基になるネイティブウィンドウオブジェクトへの参照を提供します。このプロパティを使用すると、画面の位置、サイズ、可視性など、ウィンドウの関数とプロパティのスクリプトを作成することも、終了、サイズ変更、移動などのウィンドウイベントを処理することもできます。例えば、次のステートメントではウィンドウを閉じます。

window.nativeWindow.close();

注意： NativeWindow オブジェクトが提供するウィンドウ制御機能は、JavaScript の Window オブジェクトが提供する機能と重複します。そのような場合は、使いやすい方のメソッドを使用できます。

window.nativeWindow プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフレームがあるページの親ドキュメントのためだけに定義されています。

Window.htmlLoader プロパティ

htmlLoader プロパティは、HTML コンテンツを含む AIR の HTMLLoader オブジェクトへの参照を提供します。このプロパティを使用すると、HTML 環境の外観と動作のスクリプトを作成できます。例えば、htmlLoader.paintsDefaultBackground プロパティを使用して、コントロールでデフォルトの白い背景を描画するかどうかを指定できます。

window.htmlLoader.paintsDefaultBackground = false;

注意： HTMLLoader オブジェクト自体に、格納している HTML コンテンツの JavaScript Window オブジェクトを参照する window プロパティがあります。このプロパティを使用すると、コンテナとなっている HTMLLoader への参照を通じて JavaScript 環境にアクセスできます。

window.htmlLoader プロパティは、アプリケーションサンドボックス内のコンテンツと、フレームまたはインラインフレームがあるページの親ドキュメントのためだけに定義されています。

Window.parentSandboxBridge プロパティと Window.childSandboxBridge プロパティ

parentSandboxBridge プロパティと childSandboxBridge プロパティを使用すると、親と子のフレーム間のインターフェイスを定義できます。詳しくは、異なるセキュリティサンドボックス内のコンテンツのクロススクリプトを参照してください。

Window.setTimeout() 関数と Window.setInterval() 関数

AIR では、アプリケーションサンドボックス内での setTimeout() 関数と setInterval() 関数の使用に対して、セキュリティ制限が適用されます。setTimeout() または setInterval() を呼び出すときに、ストリングとして実行されるコードを定義することはできません。関数参照を使用する必要があります。詳しくは、setTimeout() および setInterval()[setTimeout() および setInterval()]を参照してください。

Window.open() 関数

非アプリケーションサンドボックス内で実行されるコードから呼び出す場合、open() メソッドは、ユーザー操作（マウスクリックやキー入力など）の結果として呼び出されたときにのみウィンドウを開きます。また、ウィンドウのタイトルには、アプリケーションタイトルが前に付けられます（リモートコンテンツによって開かれたウィンドウが、アプリケーションによって開かれたウィンドウを偽装しないようにするため）。詳しくは、JavaScript window.open() メソッドの呼び出しに関する制限を参照してください。

NativeApplication オブジェクトは、アプリケーションの状態に関する情報を提供し、いくつかの重要なアプリケーションレベルのイベントを送出し、アプリケーション動作の制御に役立つ関数を提供します。NativeApplication オブジェクトの単一インスタンスは、自動的に作成され、クラスで定義されている NativeApplication.nativeApplication プロパティを使用してアクセスできます。

このオブジェクトに JavaScript コードからアクセスするには、次のステートメントを使用できます。

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

または、AIRAliases.js スクリプトが読み込まれている場合は、次の短い形式を使用できます。

var app = air.NativeApplication.nativeApplication;

NativeApplication オブジェクトには、アプリケーションサンドボックス内からのみアクセスできます。NativeApplication オブジェクトについて詳しくは、AIR ランタイムとオペレーティングシステムに関する情報の操作を参照してください。

JavaScript URL スキーム（href="javascript:alert('Test')" など）で定義されたコードの実行は、アプリケーションサンドボックス内でブロックされます。エラーはスローされません。