ExternalInterface (flash.external.ExternalInterface)

Object
    |
    +-flash.external.ExternalInterface

public class ExternalInterface
extends Object
	

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

ExternalInterface по функциональности подобен методам fscommand(), CallFrame() и CallLabel(), но является более гибким и более применительным вообще. Использование ExternalInterface рекомендуется для связи между JavaScript и ActionScript.

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

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

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

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

Доступность: ActionScript 1.0; Flash Player 8

Сводная таблица свойств

Сводная таблица методов

addCallback (метод ExternalInterface.addCallback)

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

Доступность: ActionScript 1.0; Flash Player 8

Параметры

methodName:String - Имя, через которое функция ActionScript может быть выывана из JavaScript. Это имя не обязано совпадать с настоящим именем метода ActionScript.

instance:Object - Объект, в кторый будет разрешаться ссылка this внутри метода. Этот объект не обязательно должен быть объектом, на котором может быть найден метод—вы можете указать любой объект (или null).

method:Function - Метод ActionScript для вызова из JavaScript.

Возвращает

Boolean - Если вызов прошел успешно, возвращает true. Если вызов не прошел, потому что экземпляр был недоступен, было обнаружено ограничение безопасности или не было обнаружено такого объекта функции, или произошло нечто подобное, то возвращает false.

Возвращаемое значение false может также означать, что среда контейнера принадлежит песочнице безопасности, к которой код не меет доступа. Вы можете обойти эту проблему, указывая подходящее значение для атрибута allowScriptAccess тэга OBJECT или тэга EMBED в HTML контейнере, содержащем проигрыватель.

Пример

Следующий пример регистрирует функцию goToMacromedia() как вызываемую из контейнера с именем goHome.

import flash.external.*;

var methodName:String = "goHome";
var instance:Object = null;
var method:Function = goToMacromedia;
var wasSuccessful:Boolean = ExternalInterface.addCallback(methodName, instance, method);

var txtField:TextField = this.createTextField("txtField", this.getNextHighestDepth(), 0, 0, 200, 50);
txtField.border = true;
txtField.text = wasSuccessful.toString();

function goToMacromedia() {
    txtField.text = "http://www.macromedia.com";
    getURL("http://www.macromedia.com", "_self");
}

Для того, чтобы предшествующий пример работал правильно, вы должны скопировать и вставить следующий код в содержимое HTML-страницы. Этот код основывается на атрибуте id тэга OBJECT и атрибуте name тэга EMBED, чтобы получить значение externalInterfaceExample. Функция thisMovie возвращает соответствующий синтаксис в зависимости от браузера, так как Internet Explorer и Netscape ссылаются на объект клипа по-разному. Если только HTML-страница не лежит на сервере, ваш браузер может выдать предупреждение безопасности.

Примечание: Избегайте использования других методов доступа к объекту плагина, типа document.getElementById("pluginName") или document.all.pluginName, поскольку эти другие методы не работают последовательно во всех браузерах.

<form>
    <input type="button" onclick="callExternalInterface()" value="Call ExternalInterface" />
</form>
<script>
function callExternalInterface() {
    thisMovie("externalInterfaceExample").goHome();
}

function thisMovie(movieName) {
    if (navigator.appName.indexOf("Microsoft") != -1) {
        return window[movieName]
    }
    else {
        return document[movieName]
    }
}
</script>
	

available (свойство ExternalInterface.available)

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

Пример

Следующий пример использует свойство ExternalInterface.available, чтобы определить, находится ли проигрываетль в контейнере, предлагающем внешний интерфейс.

import flash.external.*;

var isAvailable:Boolean = ExternalInterface.available;
trace(isAvailable);
	

call (метод ExternalInterface.call)

Вызывает предлагаемую контейнером Flash-проигрывателя функцию, передавая ей 0 или более аргументов. Если требуемая функция не доступна, вызов возвращает null; в противном случае возвращает значение, предоставленное функцией. Рекурсия не разрешена; рекурсивный вызов приводит к ответу null.

Если контейнер является HTML-страницей, то этот метод вызывает функцию JavaScript в элементе <script>.

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

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

Параметры

methodName:String - Имя вызываемой в контейнере функции. Если функция принимает параметры, они должны следовать за параметром methodName.

parameter1:Object [необязательный параметр] - Любые передаваемые функции параметры. Вы можете указать ноль иди более параметров, разделенных запятыми. Параметры могут быть любого из допустимыых в ActionScript типов данных. При вызове функции JavaScript типы ActionScript автоматически приводятся к типам JavaScript. При вызове другого ActiveX-контейнера параметры кодируются в сообщении запроса.

Возвращает

Object - Ответ, полученный от контейнера. Если вызов не прошел (например, если в контейнере не оказалось нужной функции, или интерфейс недоступен, или возникла рекурсия, или возникли проблемы с безопасностью), то возвращается null.

Пример

Следующий пример вызывает JavaScript-функцию sayHello() в HTML-странице, содержащей SWF. Вызов происходит с помощью метода ExternalInterface.call().

import flash.external.*;

var greeting:String;
var btn:MovieClip = createButton(100, 30, 0xCCCCCC);
btn.onPress = function() {
    greeting = String(ExternalInterface.call("sayHello", "browser"));
    this.mcTxt.text = greeting; // >> Хай Флэш.
}

function createButton(width:Number, height:Number, color:Number):MovieClip {
    var depth:Number = this.getNextHighestDepth();
    var mc:MovieClip = this.createEmptyMovieClip("mc_" + depth, depth);
    var mcFmt:TextFormat;

    mc.beginFill(color);
    mc.lineTo(0, height);
    mc.lineTo(width, height);
    mc.lineTo(width, 0);
    mc.lineTo(0, 0);

    mcFmt = new TextFormat();
    mcFmt.align = "center";
    mcFmt.bold = true;

    mc.createTextField("mcTxt", depth, 0, 0, width, height);
    mc.mcTxt.text = "Call JS Function";
    mc.mcTxt.setTextFormat(mcFmt);

    return mc;
}
	

Для того, чтобы предшествующий пример работал правильно, вы должны скопировать и вставить следующий код в содержимое HTML-страницы. Если только HTML-страница не лежит на сервере, ваш браузер может выдать предупреждение безопасности.

<script>
    function sayHello(name) {
        alert(">> Привет" + name + ".");
        return ">> Хай Флэш.";
    }
</script>

Посмотреть комментарии LiveDocs по External Interface