| Пакет | flash.external |
| Класс | public final class ExternalInterface |
| Наследование | ExternalInterface  Object |
| Язык версии: | ActionScript 3.0 |
| Версии среды выполнения: | AIR 1.0, Flash Player 9, Flash Lite 4 |
С помощью класса ExternalInterface можно вызвать функцию ActionScript в среде выполнения Flash, использующей 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 требует от web-браузера пользователя поддержки ActiveX® или NPRuntime API, используемых им для выполнения сценариев с использованием подключаемых модулей. Если в списке отсутствует комбинация браузер/операционная система, при наличии поддержки NPRuntime API класс ExternalInterface должен также поддерживаться. См. http://www.mozilla.org/projects/plugins/npruntime.html.
Примечание. При внедрении SWF-файлов в страницу HTML убедитесь в том, что атрибут id задан и что атрибуты id и name тегов object и embed не содержат следующих символов:
. - + * / \
Примечание для программ Flash Player. Flash Player версии 9.0.115.0 и более поздних позволяет использовать . (точка) в атрибутах id и name.
Примечание для программ Flash Player. В проигрывателе Flash Player 10 и более поздних версий, запущенном в браузере, при использовании этого класса в программных средствах открытие всплывающего окна может не выполняться. Различные браузеры (и конфигурации браузеров) могут блокировать всплывающие окна в любое время; невозможно гарантировать, что какое-либо всплывающее окно будет отображаться. Однако для повышения вероятности открытия всплывающего окна используйте этот класс только в коде, который выполняется в качестве непосредственного результата действия пользователя (например, в обработчике событий для события щелчка мышью или нажатия клавиши).
Используя ActionScript на странице HTML, можно сделать следующее:
- Вызвать любую функцию на языке JavaScript.
- Передать любое число аргументов с любыми именами.
- Передать любой тип данных (логический, числовой, строковый и так далее).
- Получить возвращаемое функцией JavaScript значение.
Используя JavaScript на странице HTML, можно сделать следующее:
- Вызвать любую функцию на языке ActionScript.
- Передать аргументы с использованием стандартной функции нотации.
- Возвратить значение в функцию JavaScript.
Примечание для программ Flash Player. Flash Player в настоящее время не поддерживает SWF-файлы, встроенные в формы HTML.
Примечание для программ AIR. В Adobe AIR класс ExternalInterface может использоваться для обеспечения взаимодействия сценария JavaScript HTML-страницы, загруженной в элемент управления HTMLLoader, и ActionScript из содержимого SWF, вложенного в эту HTML-страницу.
Связанные элементы API
Скрыть унаследованные общедоступные свойства
Показать унаследованные общедоступные свойства| Свойство | Определено | ||
|---|---|---|---|
| available : Boolean [статические] [только для чтения]
Определяет, является ли этот проигрыватель контейнером, обеспечивающим работу внешнего интерфейса. | ExternalInterface | ||
 | constructor : Object
Ссылка на объект класса или функцию конструктора для данного экземпляра объекта. | Object | |
| marshallExceptions : Boolean = false [статические]
Определяет, будет ли внешний интерфейс пытаться обойти исключения ActionScript для текущего браузера и исключения JavaScript для проигрывателя. | ExternalInterface | ||
| objectID : String [статические] [только для чтения]
Возвращает атрибут id тега object в Internet Explorer или атрибут name тега embed в Netscape. | ExternalInterface | ||
| Метод | Определено | ||
|---|---|---|---|
[статические]
Регистрирует метод ActionScript, как вызываемый из контейнера. | ExternalInterface | ||
[статические]
Вызывает функцию, предоставляемую контейнером SWF, передавая нуль или более аргументов. | ExternalInterface | ||
|
Показывает, определено ли заданное свойство для объекта. | Object | |
|
Показывает, есть ли экземпляр класса Object в цепи прототипов объекта, заданного в качестве параметра. | Object | |
|
Показывает наличие заданного свойства и его перечисляемость. | Object | |
|
Задает доступность динамического свойства для операций цикла. | Object | |
|
Возвращает строковое представление этого объекта, отформатированного в соответствии со стандартами, принятыми для данной локали. | Object | |
|
Возвращает строковое представление заданного объекта. | Object | |
|
Возвращает элементарное значение заданного объекта. | Object | |
available | свойство |
available:Boolean [только для чтения] | Язык версии: | ActionScript 3.0 |
| Версии среды выполнения: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Определяет, является ли этот проигрыватель контейнером, обеспечивающим работу внешнего интерфейса. Если внешний интерфейс доступен, свойство принимает значение 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, Flash Lite 4 |
Определяет, будет ли внешний интерфейс пытаться обойти исключения ActionScript для текущего браузера и исключения JavaScript для проигрывателя. Для выявления исключений JavaScript в ActionScript и наоборот следует присвоить данному свойству значение true в явном виде.
Связанные элементы API
Пример ( Использование этого примера )
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 | свойство |
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 можно осуществить вызов зарегистрированной в проигрывателе функции.
Примечание. Для локального содержимого, запущенного в браузере, вызов метода ExternalInterface.addCallback() работает только тогда, когда файл и содержащая его web-страница находятся в локальной достоверной изолированной среде. Для получения дополнительной информации см. раздел центра разработчиков Flash Player Безопасность.
Параметры
functionName:String — Имя, по которому контейнер может осуществить вызов функции.
| |
closure:Function — Вызываемое завершение функции. Это может быть как независимая функция, так и метод завершения, который ссылается на метод экземпляра объекта. Передав завершение метода, можно направить обратный вызов методу определенного экземпляра объекта.
Примечание. Повтор метода |
Выдает
Error — Контейнер не поддерживает входящие вызовы. Поддержка входящих вызовов присутствует только в браузере Internet Explorer для Windows и браузерах, использующих NPRuntime API, например Mozilla версии 1.7.5 или новее и Firefox версии 1.0 или новее.
| |
SecurityError — В ActionScript ответный вызов добавлен в изолированную программную среду безопасности с закрытым доступом, поэтому перезаписать данный ответный вызов невозможно. Для решения этой проблемы перепишите ActionScript так, чтобы вместо вызова метода addCallback() вызывался метод Security.allowDomain().
| |
SecurityError — Окружение, в котором содержится элемент, принадлежит изолированной программной среде, к которой у вызывающего кода доступа нет. Для решения этой проблемы следуйте приведенным ниже инструкциям:
|
Связанные элементы API
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, данный метод производит вызов функции JavaScript в элементе script.
Если в качестве контейнера выступает другой контейнер ActiveX, данный метод отправляет событие FlashCall ActiveX с заданным именем, и контейнер обрабатывает данное событие.
Если в контейнере содержится подключаемый модуль Netscape, можно запрограммировать пользовательскую поддержку нового интерфейса NPRuntime или внедрить управление HTML и встроить проигрыватель туда. После внедрения управления HTML можно осуществлять управление проигрывателем через интерфейс JavaScript собственного контейнера приложения.
Примечание. Для локального содержимого, запущенного в браузере, вызов метода ExternalInterface.call() работает только тогда, когда файл и содержащая его web-страница (при ее наличии) находятся в локальной доверенной изолированной среде. Вдобавок, чтобы SWF-файл не использовал этот метод, настройте параметр allowNetworking тегов object и embed HTML-страницы с SWF-содержимым. Для получения дополнительной информации см. раздел центра разработчиков Flash Player Безопасность.
Примечание для программ Flash Player. В Flash Player 10 и Flash Player 9 Update 5 некоторые браузеры запрещают этот метод, если включена блокировка всплывающих окон. В таком случае этот метод можно успешно вызвать только в ответ на пользовательское событие (например, в обработчике событий щелчка мыши или нажатия клавиши).
Параметры
functionName:String — Символьное имя вызываемой функции в контейнере. Использование имени функции, не содержащего буквенно-цифровые символы, является причиной ошибки этапа выполнения (ошибка 2155). Можно использовать блок try..catch для обработки ошибки.
| |
... arguments — Аргументы, передаваемые функции в контейнере. Можно указать 0 или несколько параметров, разделенных запятой. Они могут принадлежать любому типу данных ActionScript. При обращении к функции JavaScript типы данных ActionScript автоматически преобразуются в типы данных JavaScript. При обращении к какому-либо другому контейнеру параметры кодируются в сообщении запроса.
|
* — Ответ, полученный от контейнера. Если вызов функции не удался (такой функции в контейнере не существует, интерфейс недоступен, возникла рекурсия (при использовании браузера Netscape или Opera), реакция системы безопасности), возвращается null и появляется сообщение об ошибке.
|
Выдает
Error — Контейнер не поддерживает исходящие вызовы. Поддержка исходящих вызовов присутствует только в браузере Internet Explorer для Windows и браузерах, использующих NPRuntime API, например Mozilla версии 1.7.5 или новее и Firefox версии 1.0 или новее.
| |
SecurityError — Окружение, в котором содержится элемент, принадлежит изолированной программной среде, к которой у вызывающего кода доступа нет. Для решения этой проблемы следуйте приведенным ниже инструкциям:
|
Пример ( Использование этого примера )
//
// 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);
}
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);
}
}
}
}
<!-- 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>
Tue Jun 12 2018, 11:34 AM Z