パッケージflash.external
クラスpublic final class ExternalInterface
継承ExternalInterface Inheritance Object

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9

ExternalInterface クラスは外部 API であり、ActionScript と Flash Player のコンテナとの間で直接通信できるようにするアプリケーションプログラミングインターフェイスです。コンテナの例としては、JavaScript が含まれる HTML ページがあります。JavaScript と ActionScript 間のすべての通信に、ExternalInterface を使用することを推奨します。

HTML ページで JavaScript を使用することにより、Flash Player から ActionScript 関数を呼び出すことができます。ActionScript 関数は値を返すことができ、JavaScript は、呼び出しの戻り値として即座にこの値を受け取ります。

この機能は、fscommand() メソッドに代わるものです。

ExternalInterface クラスは、次のブラウザとオペレーティングシステムの組み合わせで使用してください。

ブラウザオペレーティングシステムオペレーティングシステム
Internet Explorer 5.0 以降 Windows  
Netscape 8.0 以降 Windows  Mac OS 
Mozilla 1.7.5 以降 Windows  Mac OS 
Firefox 1.0 以降 Windows  Mac OS 
Safari 1.3 以降  Mac OS 

Linux バージョン 9.0.31.0 以降用の Flash Player では、次のブラウザで ExternalInterface クラスがサポートされます。

ブラウザ
Mozilla 1.7.x 以降
Firefox 1.5.0.7 以降
SeaMonkey 1.0.5 以降

ExternalInterface クラスを利用するには、ユーザーの Web ブラウザが、一部のブラウザによってプラグインスクリプトとして公開されている ActiveX® または NPRuntime API のいずれかをサポートしている必要があります。 ブラウザおよびオペレーティングシステムの組み合わせが上記になくても、NPRuntime API がサポートされる場合、ExternalInterface クラスがサポートされます。 http://www.mozilla.org/projects/plugins/npruntime.html を参照してください。

注意：HTML ページに内に SWF ファイルを埋め込むときには、id 属性が設定されていることを確認し、id 属性および name 属性（object タグおよび embed タグ）に次の文字が含まれないようにします。 

. - + * / \

注意：Flash Player バージョン 9.0.115.0 以降では、.（ピリオド）文字を id 属性内および name 属性内で使用できます。

ブラウザで実行される Flash Player 10 以降では、このクラスをプログラムで使用してポップアップウィンドウを開く方法は有効でない場合があります。ブラウザ（およびブラウザの設定）によってはポップアップウィンドウがブロックされる場合があり、すべてのポップアップウィンドウが表示される保証はありません。ただし、ユーザー操作の直接の結果として実行されるコード (マウスのクリックやキー入力イベントのイベントハンドラなど) に限っては、このクラスを使用してポップアップウィンドウを開く方法が有効です。

ActionScript から、HTML ページに対して次のことを実行できます。

HTML ページの JavaScript から、次のことを実行できます。

Flash Player は現在、HTML フォームに埋め込まれた SWF ファイルをサポートしていません。

注意 : Adobe AIR では現在、ExternalInterface クラスはサポートされていません。

例を表示

関連項目

flash.system.fscommand()
External API requirements and advantages
Using the ExternalInterface class
Controlling outbound URL access

パブリックプロパティ
 プロパティ定義元
  available : Boolean
[静的] [読み取り専用] この Player が外部インターフェイスを備えたコンテナに含まれているかどうかを示します。
ExternalInterface
 Inheritedconstructor : Object
指定されたオブジェクトインスタンスのクラスオブジェクトまたはコンストラクタ関数への参照です。
Object
  marshallExceptions : Boolean = false
[静的] 外部インターフェイスによって、ActionScript 例外を現在のブラウザに、JavaScript 例外を Flash Player に渡そうとする必要があるかどうかを示します。
ExternalInterface
  objectID : String
[静的] [読み取り専用] Internet Explorer の場合は object タグの id 属性を返し、Netscape の場合は embed タグの name 属性を返します。
ExternalInterface
 Inheritedprototype : Object
[静的] クラスまたは関数オブジェクトのプロトタイプオブジェクトへの参照です。
Object
パブリックメソッド
 メソッド定義元
  
addCallback(functionName:String, closure:Function):void
[静的] ActionScript メソッドをコンテナから呼び出し可能なものとして登録します。
ExternalInterface
  
call(functionName:String, ... arguments):*
[静的] Flash Player コンテナで公開されている関数を呼び出し、必要に応じて引数を渡します。
ExternalInterface
 Inherited
hasOwnProperty(name:String):Boolean
オブジェクトに指定されたプロパティが定義されているかどうかを示します。
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
Object クラスのインスタンスが、パラメータとして指定されたオブジェクトのプロトタイプチェーン内にあるかどうかを示します。
Object
 Inherited
propertyIsEnumerable(name:String):Boolean
指定されたプロパティが存在し、列挙できるかどうかを示します。
Object
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
ループ処理に対するダイナミックプロパティの可用性を設定します。
Object
 Inherited
toString():String
指定されたオブジェクトのストリング表現を返します。
Object
 Inherited
valueOf():Object
指定されたオブジェクトのプリミティブな値を返します。
Object
プロパティの詳細
availableプロパティ
available:Boolean  [読み取り専用]

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9

この Player が外部インターフェイスを備えたコンテナに含まれているかどうかを示します。外部インターフェイスが利用できる場合、このプロパティは true になります。利用できない場合は false になります。

注意：HTML で外部 API を使用する場合、JavaScript メソッドを呼び出そうとする前に、HTML のロードが完了していることを必ず確認する必要があります。



実装
    public static function get available():Boolean

関連項目

Using the ExternalInterface class
Getting information about the external container

例
次の例では、available プロパティを使用して、外部インターフェイスを備えたコンテナ内に Player が含まれているかどうかを確認します。 
package {
       import flash.text.TextField;
       import flash.display.MovieClip;
       import flash.external.ExternalInterface;
     
       public class extint_test extends MovieClip {
         public function extint_test() {
           var isAvailable:Boolean = ExternalInterface.available;
           var availTxt:TextField = new TextField();
           availTxt.text = isAvailable.toString();
           addChild(availTxt);
         }
       }
     }
marshallExceptionsプロパティ 
public static var marshallExceptions:Boolean = false

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9.0.115.0

外部インターフェイスによって、ActionScript 例外を現在のブラウザに、JavaScript 例外を Flash Player に渡そうとする必要があるかどうかを示します。ActionScript で JavaScript 例外をキャッチし、JavaScript で ActionScript 例外をキャッチするには、このプロパティを明示的に true に設定する必要があります。

関連項目

addCallBack()
try..catch..finally ステートメント

例
次の例では、ActionScript 関数を作成し、addCallback() メソッドを使用して、埋め込み先のブラウザと共にその関数を登録します。新しい関数は、ブラウザで実行される JavaScript コードでキャッチできるように、例外をスローします。この例には、try..catch ステートメントも含まれており、throwit() 関数が呼び出されたときにブラウザからスローされるすべての例外をキャッチします。 
package
{
    import flash.external.*
    import flash.net.*;
    import flash.display.*;
    import flash.system.System;
    public class ext_test extends Sprite {
    function ext_test():void {
        ExternalInterface.marshallExceptions = true;
        ExternalInterface.addCallback("g", g);

        try {
        ExternalInterface.call("throwit");
        } catch(e:Error) {
        trace(e)
        }
    }
    function g() { throw new Error("exception from actionscript!!!!") }
    }
}
objectIDプロパティ 
objectID:String  [読み取り専用]

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9

Internet Explorer の場合は object タグの id 属性を返し、Netscape の場合は embed タグの name 属性を返します。



実装
    public static function get objectID():String

関連項目

Using the ExternalInterface class
Getting information about the external container
メソッドの詳細
addCallback()メソッド
public static function addCallback(functionName:String, closure:Function):void

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9

ActionScript メソッドをコンテナから呼び出し可能なものとして登録します。addCallBack() の呼び出しが成功すると、Flash Player 内に登録されている関数をコンテナ内の JavaScript や ActiveX から呼び出すことができます。

注意：ブラウザで実行されるローカルコンテンツでは、SWF ファイルおよびそれを含む Web ページが信頼できるローカルなセキュリティ Sandbox 内にある場合にのみ、ExternalInterface.addCallback() メソッドの呼び出しが動作します。詳しくは、次のトピックを参照してください。

パラメータ

functionName:String — コンテナが関数を呼び出すことができる名前です。
 
closure:Function — 呼び出す関数閉包です。これは独立した関数にすることも、オブジェクトインスタンスのメソッドを参照するメソッド閉包とすることもできます。メソッドクロージャを渡すことにより、コールバックを特定のオブジェクトインスタンスのメソッドに指定できます。


例外
Error — コンテナが着信コールをサポートしていません。着信コールは Windows 用の Internet Explorer、Mozilla 1.7.5 以降、Firefox 1.0 以降などの NPRuntime API を使用するブラウザでのみサポートされます。
 
SecurityError — 指定された名前を使用したコールバックが、アクセスしていない Sandbox 内で既に ActionScript によって追加されています。このコールバックを上書きできません。この問題を回避するには、addCallback() メソッドの呼び出し元の ActionScript を書き換えて、このスクリプトから Security.allowDomain() メソッドも呼び出すようにします。
 
SecurityError — コンテナ環境がセキュリティサンドボックスに属しているために、呼び出し側のコードにアクセス権がありません。この問題を修正するには、次の手順に従います。
  1. HTML ページに埋め込む SWF ファイルの object タグの中で次のパラメータを設定します。

    <param name="allowScriptAccess" value="always" />

  2. SWF ファイルで、次の ActionScript を追加します。

    flash.system.Security.allowDomain( sourceDomain )

関連項目

flash.system.Security.allowDomain()
Using the ExternalInterface class
Calling ActionScript code from the container
call()メソッド 
public static function call(functionName:String, ... arguments):*

言語バージョン: ActionScript 3.0
ランタイムバージョン: AIR 1.0 Flash Player 9

Flash Player コンテナで公開されている関数を呼び出し、必要に応じて引数を渡します。関数が利用できない場合は null を返します。それ以外の場合は、関数の戻り値を返します。 再帰は、Opera ブラウザまたは Netscape ブラウザでは許可されていません。これらのブラウザでは、再帰呼び出しで null 応答が発生します。Internet Explorer ブラウザおよび Firefox ブラウザでは、再帰がサポートされています。

コンテナが HTML ページである場合、このメソッドは script エレメントに囲まれた JavaScript 関数を呼び出します。

コンテナが別の ActiveX コンテナの場合、このメソッドは、指定された名前で FlashCall ActiveX イベントを送出し、そのイベントはコンテナによって処理されます。

コンテナが Netscape プラグインをホストしている場合、新しい NPRuntime インターフェイス用のカスタムサポートを記述するか、HTML コントロールを埋め込んだ後にそのコントロール内に Flash Player を埋め込むことができます。HTML コントロールを埋め込んだ場合、ネイティブコンテナアプリケーションに対する JavaScript インターフェイスを通じて Flash Player と通信できます。

注意：ブラウザで実行されるローカルコンテンツでは、SWF ファイルおよび含んでいる Web ページ（存在する場合）が信頼できるローカルなセキュリティ Sandbox 内にある場合にのみ、ExternalInterface.call() メソッドの呼び出しが許可されます。SWF ファイルがこのメソッドを使用しないようにすることもできます。その場合は、SWF コンテンツを含んでいる HTML ページに object タグおよび embed タグの allowNetworking パラメータを設定します。詳しくは、次のトピックを参照してください。

Flash Player 10 および Flash Player 9 Update 5 では、ポップアップブロッカーが有効になっている場合、一部の Web ブラウザでこのメソッドが制限されます。このシナリオでは、このメソッドの呼び出しはマウスのクリックやキー入力などのユーザーイベントに応じて、イベントハンドラで呼び出した場合にのみ成功します。

パラメータ

functionName:String — コンテナ内にある呼び出し先関数の英数字の名前です。英数字の関数名を使用すると、ランタイムエラー（エラー 2155）が発生します。try..catch ブロックを使用して、このエラーを処理できます。
 
... arguments — コンテナ内の関数に渡されるパラメータです。任意のパラメータを指定することができ、複数のパラメータを指定する場合はカンマで区切ります。パラメータには任意の ActionScript データ型を使用できます。呼び出し先が JavaScript 関数である場合、ActionScript のデータ型は JavaScript のデータ型に自動的に変換されます。呼び出し先が他の ActiveX コンテナである場合、パラメータは要求メッセージの中にエンコードされます。

戻り値
* — コンテナから受け取った応答です。呼び出しに失敗した場合は、null が返され、エラーがスローされます。失敗原因としては、コンテナに該当する関数が存在しない場合、インターフェイスが利用できない場合、再帰が発生した場合（Netscape ブラウザまたは Opera ブラウザの場合）、セキュリティ上の問題がある場合などがあります。

例外
Error — コンテナが送信コールをサポートしていません。送信コールは Windows 用の Internet Explorer、Mozilla 1.7.5 以降、Firefox 1.0 以降などの NPRuntime API を使用するブラウザでのみサポートされます。
 
SecurityError — コンテナ環境がセキュリティサンドボックスに属しているために、呼び出し側のコードにアクセス権がありません。この問題を修正するには、次の手順に従います。
  1. HTML ページに埋め込む SWF ファイルの object タグの中で次のパラメータを設定します。

    <param name="allowScriptAccess" value="always" />

  2. SWF ファイルで、次の ActionScript を追加します。

    flash.system.Security.allowDomain( sourceDomain )

関連項目

Using the ExternalInterface class
Calling external code from ActionScript
Controlling outbound URL access
例 例の使用法
ExternalInterfaceExample.as

次の例では、Flash Player および HTML コンテナ間でデータを送信する方法を示します。 
package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.external.ExternalInterface;
    import flash.text.TextField;
    import flash.utils.Timer;
    import flash.text.TextFieldType;
    import flash.text.TextFieldAutoSize;

    public class ExternalInterfaceExample extends Sprite {
        private var input:TextField;
        private var output:TextField;
        private var sendBtn:Sprite;

        public function ExternalInterfaceExample() {
            input = new TextField();
            input.type = TextFieldType.INPUT;
            input.background = true;
            input.border = true;
            input.width = 350;
            input.height = 18;
            addChild(input);

            sendBtn = new Sprite();
            sendBtn.mouseEnabled = true;
            sendBtn.x = input.width + 10;
            sendBtn.graphics.beginFill(0xCCCCCC);
            sendBtn.graphics.drawRoundRect(0, 0, 80, 18, 10, 10);
            sendBtn.graphics.endFill();
            sendBtn.addEventListener(MouseEvent.CLICK, clickHandler);
            addChild(sendBtn);

            output = new TextField();
            output.y = 25;
            output.width = 450;
            output.height = 325;
            output.multiline = true;
            output.wordWrap = true;
            output.border = true;
            output.text = "Initializing...\n";
            addChild(output);

            if (ExternalInterface.available) {
                try {
                    output.appendText("Adding callback...\n");
                    ExternalInterface.addCallback("sendToActionScript", receivedFromJavaScript);
                    if (checkJavaScriptReady()) {
                        output.appendText("JavaScript is ready.\n");
                    } else {
                        output.appendText("JavaScript is not ready, creating timer.\n");
                        var readyTimer:Timer = new Timer(100, 0);
                        readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
                        readyTimer.start();
                    }
                } catch (error:SecurityError) {
                    output.appendText("A SecurityError occurred: " + error.message + "\n");
                } catch (error:Error) {
                    output.appendText("An Error occurred: " + error.message + "\n");
                }
            } else {
                output.appendText("External interface is not available for this container.");
            }
        }
        private function receivedFromJavaScript(value:String):void {
            output.appendText("JavaScript says: " + value + "\n");
        }
        private function checkJavaScriptReady():Boolean {
            var isReady:Boolean = ExternalInterface.call("isReady");
            return isReady;
        }
        private function timerHandler(event:TimerEvent):void {
            output.appendText("Checking JavaScript status...\n");
            var isReady:Boolean = checkJavaScriptReady();
            if (isReady) {
                output.appendText("JavaScript is ready.\n");
                Timer(event.target).stop();
            }
        }
        private function clickHandler(event:MouseEvent):void {
            if (ExternalInterface.available) {
                ExternalInterface.call("sendToJavaScript", input.text);
            }
        }
    }
}
上記の ActionScript コードをテストするには、次の HTML テンプレートを使用して、生成された SWF ファイルを埋め込みます。 
<!-- saved from url=(0014)about:internet -->
 <html lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <title>ExternalInterfaceExample</title>
 <script language="JavaScript">
     var jsReady = false;
     function isReady() {
         return jsReady;
     }
     function pageInit() {
         jsReady = true;
         document.forms["form1"].output.value += "\n" + "JavaScript is ready.\n";
     }
     function thisMovie(movieName) {
         if (navigator.appName.indexOf("Microsoft") != -1) {
             return window[movieName];
         } else {
             return document[movieName];
         }
     }
     function sendToActionScript(value) {
         thisMovie("ExternalInterfaceExample").sendToActionScript(value);
     }
     function sendToJavaScript(value) {
         document.forms["form1"].output.value += "ActionScript says: " + value + "\n";
     }
 </script>
 </head>
 <body onload="pageInit();">
 
     <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
             id="ExternalInterfaceExample" width="500" height="375"
             codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
         <param name="movie" value="ExternalInterfaceExample.swf" />
         <param name="quality" value="high" />
         <param name="bgcolor" value="#869ca7" />
         <param name="allowScriptAccess" value="sameDomain" />
         <embed src="ExternalInterfaceExample.swf" quality="high" bgcolor="#869ca7"
             width="500" height="375" name="ExternalInterfaceExample" align="middle"
             play="true" loop="false" quality="high" allowScriptAccess="sameDomain"
             type="application/x-shockwave-flash"
             pluginspage="http://www.macromedia.com/go/getflashplayer">
         </embed>
     </object>
 
     <form name="form1" onsubmit="return false;">
         <input type="text" name="input" value="" />
         <input type="button" value="Send" onclick="sendToActionScript(this.form.input.value);" /><br />
         <textarea cols="60" rows="20" name="output" readonly="true">Initializing...</textarea>
     </form>
 
 </body>
 </html>



© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Thu Jan 8 2009, 12:14 AM -08:00