ExternalInterface - Adobe ActionScript® 3（AS3 ）API リファレンス

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

言語バージョン:

ActionScript 3.0

ランタイムバージョン:

AIR 1.0, Flash Player 9, Flash Lite 4

ExternalInterface クラスは、ActionScript と SWF のコンテナとの間で直接通信できるようにするアプリケーションプログラミングインターフェイスです。コンテナには、JavaScript を使用した HTML ページや、Flash Player を使用して SWF ファイルを表示するデスクトップアプリケーションなどがあります。

ExternalInterface クラスを使用すると、HTML ページの JavaScript を使用することによって、Flash ランタイムで 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 アプリケーションに関する注意：Flash Player バージョン 9.0.115.0 以降では、.（ピリオド）文字を id 属性内および name 属性内で使用できます。

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

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

任意の JavaScript 関数を呼び出す
引数の数を名前と共に渡す
ブール（Boolean）、数値（Number）、ストリング（String）などの各種データ型を渡す
JavaScript 関数からの戻り値を受け取る

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

ActionScript 関数を呼び出す
標準の関数呼び出しの表記法を使用して、引数を渡す
JavaScript 関数に値を戻す

Flash Player アプリケーションに関する注意：Flash Player は現在、HTML フォームに埋め込まれた SWF ファイルをサポートしていません。

AIR アプリケーションに関する注意：Adobe AIR では、ExternalInterface クラスを使用して、HTMLLoader コントロールに読み込まれた HTML ページの JavaScript とその HTML ページに埋め込まれた SWF コンテンツの ActionScript との間で通信できます。

例を表示

さらに例を参照

Using the ExternalInterface API to access JavaScript
Accessing Flex from JavaScript
About ExternalInterface API security in Flex

	プロパティ	定義元
		available : Boolean [静的] [読み取り専用] この Player が外部インターフェイスを備えたコンテナに含まれているかどうかを示します。	ExternalInterface
		constructor : Object 指定されたオブジェクトインスタンスのクラスオブジェクトまたはコンストラクター関数への参照です。	Object
		marshallExceptions : Boolean = false [静的] 外部インターフェイスから、ActionScript の例外を現在のブラウザーに渡したり、JavaScript の例外をプレーヤーに渡したりする必要があるかどうかを示します。	ExternalInterface
		objectID : String [静的] [読み取り専用] Internet Explorer の場合は object タグの id 属性を返し、Netscape の場合は embed タグの name 属性を返します。	ExternalInterface

	メソッド	定義元
		addCallback(functionName:String, closure:Function):void [静的] ActionScript メソッドをコンテナから呼び出し可能なものとして登録します。	ExternalInterface
		call(functionName:String, ... arguments):* [静的] SWF コンテナで公開されている関数を呼び出し、必要に応じて引数を渡します。	ExternalInterface
		hasOwnProperty(name:String):Boolean オブジェクトに指定されたプロパティが定義されているかどうかを示します。	Object
		isPrototypeOf(theClass:Object):Boolean Object クラスのインスタンスが、パラメーターとして指定されたオブジェクトのプロトタイプチェーン内にあるかどうかを示します。	Object
		propertyIsEnumerable(name:String):Boolean 指定されたプロパティが存在し、列挙できるかどうかを示します。	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void ループ処理に対するダイナミックプロパティの可用性を設定します。	Object
		toLocaleString():String ロケール固有の規則に従って書式設定された、このオブジェクトのストリング表現を返します。	Object
		toString():String 指定されたオブジェクトのストリング表現を返します。	Object
		valueOf():Object 指定されたオブジェクトのプリミティブな値を返します。	Object

available

プロパティ

available:Boolean [読み取り専用]

言語バージョン:

ActionScript 3.0

ランタイムバージョン:

AIR 1.0, Flash Player 9, Flash Lite 4

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

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

実装
public static function get available():Boolean

例 ( この例の使用方法 )

次の例では、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, Flash Lite 4

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

objectID

プロパティ

objectID:String [読み取り専用]

言語バージョン:

ActionScript 3.0

ランタイムバージョン:

AIR 1.0, Flash Player 9, Flash Lite 4

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

実装
public static function get objectID():String

メソッドの詳細

addCallback

()

メソッド

public static function addCallback(functionName:String, closure:Function):void

言語バージョン:

ActionScript 3.0

ランタイムバージョン:

AIR 1.0, Flash Player 9, Flash Lite 4

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

注意：ブラウザーで実行されるローカルコンテンツでは、SWF ファイルとその埋め込み先の Web ページが local-trusted セキュリティサンドボックス内にある場合にのみ、ExternalInterface.addCallback() メソッドの呼び出しが機能します。詳細については、Flash Player デベロッパーセンターのトピック：セキュリティを参照してください。

パラメーター

	`functionName:String` — コンテナが関数を呼び出すことができる名前です。

	`closure:Function` — 呼び出す関数閉包です。これは独立した関数にすることも、オブジェクトインスタンスのメソッドを参照するメソッド閉包とすることもできます。メソッドクロージャを渡すことにより、コールバックを特定のオブジェクトインスタンスのメソッドに指定できます。注意：既存のコールバック関数に対して、closure 値に `null` を指定して `addCallback()` を繰り返し実行すると、コールバックが削除されます。

例外

	`Error` — コンテナが着信コールをサポートしていません。着信コールは Windows 用の Internet Explorer、Mozilla 1.7.5 以降、Firefox 1.0 以降などの NPRuntime API を使用するブラウザーでのみサポートされます。

	`SecurityError` — 指定された名前を使用したコールバックが、アクセスしていない Sandbox 内で既に ActionScript によって追加されています。このコールバックを上書きできません。この問題を回避するには、`addCallback()` メソッドの呼び出し元の ActionScript を書き換えて、このスクリプトから `Security.allowDomain()` メソッドも呼び出すようにします。

	`SecurityError` — コンテナ環境がセキュリティサンドボックスに属しているために、呼び出し側のコードにアクセス権がありません。この問題を修正するには、次の手順に従います。 HTML ページに埋め込む SWF ファイルの `object` タグの中で次のパラメーターを設定します。 `<param name="allowScriptAccess" value="always" />` SWF ファイルで、次の ActionScript を追加します。 `flash.system.Security.allowDomain( sourceDomain )`

call

()

メソッド

public static function call(functionName:String, ... arguments):*

言語バージョン:

ActionScript 3.0

ランタイムバージョン:

AIR 1.0, Flash Player 9, Flash Lite 4

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

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

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

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

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

Flash Player アプリケーションに関する注意：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` — コンテナ環境がセキュリティサンドボックスに属しているために、呼び出し側のコードにアクセス権がありません。この問題を修正するには、次の手順に従います。 HTML ページに埋め込む SWF ファイルの `object` タグの中で次のパラメーターを設定します。 `<param name="allowScriptAccess" value="always" />` SWF ファイルで、次の ActionScript を追加します。 `flash.system.Security.allowDomain( sourceDomain )`

例 ( この例の使用方法 )

次の例では、ExternalInterface クラス（flash.external.ExternalInterface）を使用して、Flash Player から HTML コンテナにストリングを送信し、そのストリングを JavaScript の alert() 関数を使用して表示する方法を示します。ActionScriptExamples.com で作成された例。

//
// Requires:
//   - A Flash Professional Label component on the Stage with an instance name of "lbl".
//   - A Flash Professional Button component on the Stage with an instance name of "button".
//
var xmlResponse:String = "<invoke name=\"isReady\" returntype=\"xml\"><arguments><number>1</number><number>" + stage.stageWidth + "</number><number>" + stage.stageHeight + "</number></arguments></invoke>";
 
lbl.text = "ExternalInterface.available: " + ExternalInterface.available;
lbl.width = 200;
button.enabled = ExternalInterface.available;
button.addEventListener(MouseEvent.CLICK, button_click);
 
function button_click(evt:MouseEvent):void {
    ExternalInterface.call("alert", xmlResponse);
}

例この例の使用方法

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;
    import flash.system.Security;
    
    public class ExternalInterfaceExample extends Sprite 
    {
        
    private var input:TextField;
        private var output:TextField;
        private var sendBtn:Sprite;
        
        public function ExternalInterfaceExample() 
        {
            // constructor code
            Security.allowDomain("*");
            
            
            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");
                output.appendText("ExternalInterface.objectID = " + ExternalInterface.objectID + "\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 sendToActionScript(value) {
       document.getElementById("ExternalInterfaceExample").sendToActionScript(value);
     }
     function sendToJavaScript(value) {
         document.forms["form1"].output.value += "ActionScript says: " + value + "\n";
     }
 </script>
 </head>
 <body onload="pageInit();">
 
  <object id="ExternalInterfaceExample"  name="ExternalInterfaceExample" 
  type="application/x-shockwave-flash" data="ExternalInterfaceExample.swf" width="550" height="400">
    <param name="movie" value="ExternalInterfaceExample.swf"/>
    <param name="quality" value="high"/>
    <param name="allowscriptaccess" value="always"/>
    <a href="http://www.adobe.com/go/getflash">
        <img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" alt="Get Adobe Flash player"/>
    </a>
  </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>

法律上の注意 | プライバシーポリシー

ExternalInterface - AS3

パッケージx

言語エレメント

付録

パッケージ flash.external

available

marshallExceptions

objectID

addCallback

call