Пакетflash.external
Классpublic final class ExternalInterface
НаследованиеExternalInterface Inheritance Object

Язык версии : ActionScript 3.0
Версии среды выполнения: AIR 1.0, Flash Player 9

Класс ExternalInterface является внешним API-интерфейсом, обеспечивающим непосредственную связь между ActionScript и контейнером для Flash Player (например, HTML-страницей с поддержкой JavaScript). Для связи компонентов JavaScript-ActionScript компания Adobe рекомендует использовать ExternalInterface.

В проигрывателе Flash Player функцию ActionScript можно вызвать, используя JavaScript на странице HTML. Функция ActionScript может возвратить значение, которое JavaScript немедленно получит в качестве возвращаемого значения вызова.

Поддержка данной возможности заменяет метод fscommand().

Используйте класс ExternalInterface при работе со следующими комбинациями обозревателей и операционных систем:

ОбозревательОперационная системаОперационная система
Internet Explorer версии 5.0 или новее Windows  
Netscape версии 8.0 или новее Windows  MacOS 
Mozilla 1.7.5 или новее Windows  MacOS 
Firefox версии 1.0 или новее Windows  MacOS 
Safari версии 1.3 или новее  MacOS 

Flash Player для Linux версии 9.0.31.0 и более новые версии программы обладают поддержкой класса ExternalInterface в следующих обозревателях:

Обозреватель
Mozilla версии 1.7.x или новее
Firefox версии 1.5.0.7 или новее
SeaMonkey версии 1.0.5 или новее

Класс ExternalInterface требует от веб-обозревателя пользователя поддержки ActiveX или NPRuntime API, используемых им для выполнения сценариев с использованием подключаемых модулей. Если в списке такая комбинация обозреватель — операционная система отсутствует, при наличии поддержки NPRuntime API класс ExternalInterface должен поддерживаться также. См. http://www.mozilla.org/projects/plugins/npruntime.html.

Примечание. При внедрении SWF-файлов в страницу HTML убедитесь в том, что атрибут id задан и что атрибуты id и name тегов object и embed не содержат следующих символов:

 . - + * / \

Примечание. Flash Player версии 9.0.115.0 и более новых допускает наличие символа . (точки) в атрибутах id и name.

Используя ActionScript на странице HTML, можно сделать следующее:

Используя JavaScript на странице HTML, можно сделать следующее:

В настоящее время Flash Player не поддерживает внедрение SWF-файлов в формы HTML.

Посмотреть примеры

См. также

flash.system.fscommand()

Общедоступные свойства
 СвойствоОпределено
  available : Boolean
[статические] [только для чтения] Определяет, является ли этот проигрыватель контейнером, обеспечивающим работу внешнего интерфейса.
ExternalInterface
 Inheritedconstructor : Object
Ссылка на объект класса или функцию конструктора для данного экземпляра объекта.
Object
  marshallExceptions : Boolean = false
[статические] Определяет, будет ли внешний интерфейс пытаться обойти исключения ActionScript для текущего обозревателя и исключения JavaScript для Flash Player.
ExternalInterface
  objectID : String
[статические] [только для чтения] Возвращает атрибут id тега object в Internet Explorer, или атрибут name тега embed в Netscape.
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

Определяет, является ли этот проигрыватель контейнером, обеспечивающим работу внешнего интерфейса. Если внешний интерфейс доступен, свойство принимает значение true; в противном случае — false.

Примечание. При использовании External API с HTML следует всегда дожидаться окончания загрузки HTML перед тем, как вызывать методы JavaScript.


Реализация
    public static function get available():Boolean

Пример
В следующем примере для определения, поддерживает ли проигрыватель внешний интерфейс, используется свойство available. 
     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. Для выявления исключений 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

Возвращает атрибут тега id объекта object в Internet Explorer или атрибут name тега embed в Netscape.


Реализация
    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

Регистрирует метод ActionScript, как вызываемый из контейнера. После успешного вызова метода addCallBack() содержащимся в контейнере кодом JavaScript или ActiveX можно осуществить вызов зарегистрированной в проигрывателе Flash Player функции.

Примечание. Для локального содержимого, запущенного в обозревателе, вызов метода ExternalInterface.addCallback() работает только тогда, когда файл и содержащая его веб-страница находятся в локальной достоверной изолированной среде. Дополнительные сведения см. в следующих источниках.

Параметры

functionName:String — Имя, по которому контейнер может осуществить вызов функции.
 
closure:Function — Вызываемое завершение функции. Это может быть как независимая функция, так и метод завершения, который ссылается на метод экземпляра объекта. Передав завершение метода, можно направить обратный вызов методу определенного экземпляра объекта.


Выдает
Error — Контейнер не поддерживает входящие вызовы. Поддержка входящих вызовов присутствует только в обозревателе Internet Explorer для Windows и обозревателях, использующих NPRuntime API, например Mozilla версии 1.7.5 или новее и Firefox версии 1.0 или новее.
 
SecurityError — В ActionScript ответный вызов добавлен в изолированную программную среду безопасности с закрытым доступом, поэтому перезаписать данный ответный вызов невозможно. Для решения этой проблемы перепишите ActionScript так, чтобы вместо вызова метода addCallback() вызывался метод Security.allowDomain().
 
SecurityError — Окружение, в котором содержится элемент, принадлежит изолированной программной среде, к которой у вызывающего кода доступа нет. Для решения этой проблемы следуйте приведенным ниже инструкциям:
  1. В теге object SWF-файла на странице HTML настройте следующий параметр:

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

  2. Добавьте в SWF-файл следующий ActionScript:

    flash.system.Security.allowDomain(sourceDomain)

См. также

flash.system.Security.allowDomain()
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, данный метод производит вызов функции JavaScript в элементе script.

Если в качестве контейнера выступает другой контейнер ActiveX, данный метод отправляет событие FlashCall ActiveX с заданным именем, и контейнер обрабатывает данное событие.

Если в контейнере содержится подключаемый модуль Netscape, можно запрограммировать пользовательскую поддержку нового интерфейса NPRuntime или внедрить управление HTML и встроить проигрыватель Flash Player туда. После внедрения управления HTML можно осуществлять управление проигрывателем Flash Player через интерфейс JavaScript собственного контейнера приложения.

Примечание. Для локального содержимого, запущенного в обозревателе, вызов метода ExternalInterface.addCallback() работает только тогда, когда файл и содержащая его веб-страница (при ее наличии) находятся в локальной достоверной изолированной среде. Вдобавок, чтобы SWF-файл не использовал этот метод, настройте параметр allowNetworking тегов object и embed HTML-страницы с SWF-содержимым. Дополнительные сведения см. в следующих источниках.

Параметры

functionName:String — Символьное имя вызываемой функции в контейнере.
 
... arguments — Аргументы, передаваемые функции в контейнере. Можно указать 0 или несколько параметров, разделенных запятой. Они могут принадлежать любому типу данных ActionScript. При обращении к функции JavaScript типы данных ActionScript автоматически преобразуются в типы данных JavaScript. При обращении к какому-либо другому контейнеру параметры кодируются в сообщении запроса.

Возвращает
* — Ответ, полученный от контейнера. Если вызов функции не удался (такой функции в контейнере не существует, интерфейс недоступен, возникла рекурсия (при использовании обозревателя Netscape или Opera), реакция системы безопасности), возвращается null и появляется сообщение об ошибке.

Выдает
Error — Контейнер не поддерживает исходящие вызовы. Поддержка исходящих вызовов присутствует только в обозревателе Internet Explorer для Windows и обозревателях, использующих NPRuntime API, например Mozilla версии 1.7.5 или новее и Firefox версии 1.0 или новее.
 
SecurityError — Окружение, в котором содержится элемент, принадлежит изолированной программной среде, к которой у вызывающего кода доступа нет. Для решения этой проблемы следуйте приведенным ниже инструкциям:
  1. В теге object SWF-файла на странице HTML настройте следующий параметр:

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

  2. Добавьте в SWF-файл следующий ActionScript:

    flash.system.Security.allowDomain(sourceDomain)

Примеры Как пользоваться примерами
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, внедрите созданный SWF-файл с использованием следующего шаблона HTML: 
 <!-- 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.
Wed Sep 24 2008, 07:56 AM -07:00