| Pacote | flash.external |
| Classe | public final class ExternalInterface |
| Herança | ExternalInterface  Object |
| Versão da linguagem: | ActionScript 3.0 |
| Versões de runtime: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Usando a classe ExternalInterface, você pode chamar uma função ActionScript no tempo de execução de Flash, usando JavaScript na página HTML. A função ActionScript pode retornar uma valor e o JavaScript a recebe imediatamente como o valor de retorno da chamada.
Esta funcionalidade substitui o método fscommand().
Use a classe ExternalInterface nas combinações a seguir do navegador e do sistema operacional:
| Navegador | Sistema operacional | Sistema operacional |
|---|---|---|
| Internet Explorer 5.0 e posterior | Windows | |
| Netscape 8.0 e posterior | Windows | MacOS |
| Mozilla 1.7.5 e posterior | Windows | MacOS |
| Firefox 1.0 e posterior | Windows | MacOS |
| Safari 1.3 e posterior | MacOS |
O Flash Player para Linux versão 9.0.31.0 e posterior suporta a classe ExternalInterface nos seguintes navegadores:
| Navegador |
|---|
| Mozilla 1.7.x e posterior |
| Firefox 1.5.0.7 e posterior |
| SeaMonkey 1.0.5 e posterior |
A classe ExternalInterface exige que o navegador da Web do usuário suporte o ActiveX ® ou o NPRuntime API que é exposto por alguns navegadores para script de plug-in. Mesmo se uma combinação do navegador e do sistema operacional não estiver listada acima, ela deve suportar a classe ExternalInterface se suportar o NPRuntime API. Consulte http://www.mozilla.org/projects/plugins/npruntime.html.
Observação: Ao incorporar arquivos SWF a uma página HTML, verifique se o atributo id está definido e se os atributos id e name das tags object e embed não incluem os seguintes caracteres:
. - + * / \
Observação para aplicativos de Flash Player: a versão 9.0.115.0 de posterior do Flash Player permite o . caractere (ponto) nos atributos id ename.
Observação sobre os aplicativos do Flash Player: no Flash Player 10 e posterior em execução no navegador, o uso dessa classe programaticamente para abrir uma janela pop-up pode não ser bem-sucedido. Vários navegadores (e configurações de navegador) podem bloquear janelas pop-up a qualquer momento; não é possível garantir que todas as janelas pop-up sejam exibidas. No entanto, para ter boa chance de sucesso, use essa classe para abrir uma janela pop-up somente no código que seja executado como um resultado direto da ação do usuário (por exemplo, em um manipulador de eventos para um evento de clique de mouse ou de pressionamento de tecla.)
No ActionScript, é possível fazer o seguinte na página HTML:
- Chamar qualquer função JavaScript.
- Transmitir qualquer número de argumentos, com quaisquer nomes.
- Transmitir vários tipos de dados (Boolean, Number, String e assim por diante).
- Receber um valor de retorno da função JavaScript.
No JavaScript na página HTML, é possível:
- Chamar qualquer função ActionScript.
- Transmitir argumentos usando a notação de chamada da função padrão.
- Retornar um valor para a função JavaScript.
Observação para aplicativos de Flash Player: o Flash Player não suporta atualmente arquivos SWF incorporados dentro de formas HTML.
Observação para aplicativos de AIR: No Adobe AIR, a classe ExternalInterface pode ser usada para realizar a comunicação entre o Javascript em uma página HTML carregada no controle de HTMLLoader e ActionScript no conteúdo SWF incorporado naquela página de HTML.
Mais exemplos
Accessing Flex from JavaScript
About ExternalInterface API security in Flex
Elementos da API relacionados
Ocultar propriedades públicas herdadas
Mostrar propriedades públicas herdadas| Propriedade | Definido por | ||
|---|---|---|---|
| available : Boolean [estático] [somente leitura]
Indica se este player está em um contêiner que oferece uma interface externa. | ExternalInterface | ||
 | constructor : Object
Uma referência ao objeto de classe ou à função de construtor de uma determinada ocorrência de objeto. | Object | |
| marshallExceptions : Boolean = false [estático]
Indica se a interface externa deve tentar transmitir exceções ActionScript ao navegador atual e exceções JavaScript ao player. | ExternalInterface | ||
| objectID : String [estático] [somente leitura]
Retorna o atributo de id da marca de objeto no Internet Explorer ou o atributo de nome da marca incorporada no Netscape. | ExternalInterface | ||
| Método | Definido por | ||
|---|---|---|---|
[estático]
Registra um método ActionScript como chamável a partir do contêiner. | ExternalInterface | ||
[estático]
Chama uma função exposta pelo contêiner SWF, transmitindo zero ou mais argumentos. | ExternalInterface | ||
|
Indica se um objeto tem uma propriedade especificada definida. | Object | |
|
Indica se uma ocorrência da classe Object está na cadeia de protótipos do objeto especificado como o parâmetro. | Object | |
|
Indica se a propriedade especificada existe e é enumerável. | Object | |
|
Define a disponibilidade de uma propriedade dinâmica para operações de repetição. | Object | |
|
Retorna a representação da string deste objeto, formatado segundo as convenções específicas para a localidade. | Object | |
|
Retorna a representação de string do objeto especificado. | Object | |
|
Retorna o valor primitivo do objeto especificado. | Object | |
available | propriedade |
available:Boolean [somente leitura] | Versão da linguagem: | ActionScript 3.0 |
| Versões de runtime: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Indica se este player está em um contêiner que oferece uma interface externa. Se a interface externa estiver disponível, esta propriedade será true; caso contrário, ela será false.
Nota: ao usar a API externa com HTML, sempre verifique se o HTML concluiu o carregamento antes de tentar chamar quaisquer métodos JavaScript.
Implementação
public static function get available():BooleanExemplo ( Como usar este exemplo )
available para determinar se o player está em um contêiner que oferece uma interface externa.
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 | propriedade |
public static var marshallExceptions:Boolean = false| Versão da linguagem: | ActionScript 3.0 |
| Versões de runtime: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4 |
Indica se a interface externa deve tentar transmitir exceções ActionScript ao navegador atual e exceções JavaScript ao player. É necessário definir explicitamente essa propriedade como true para detectar as exceções JavaScript no ActionScript e detectar as exceções ActionScript no JavaScript.
Elementos da API relacionados
Exemplo ( Como usar este exemplo )
addCallback(). A nova função emite uma exceção para que o código JavaScript que está sendo executado no navegador possa detectá-la. Este exemplo também contém uma instrução try..catch para detectar quaisquer exceções emitidas pelo navegador quando a função throwit() é chamada.
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 | propriedade |
addCallback | () | método |
public static function addCallback(functionName:String, closure:Function):void| Versão da linguagem: | ActionScript 3.0 |
| Versões de runtime: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Registra um método ActionScript como chamável a partir do contêiner. Após uma chamada bem-sucedida do addCallBack(), a função registrada no player pode ser chamada pelo código JavaScript ou ActiveX no contêiner.
Observação: Para o conteúdo local que está sendo executado em um navegador, as chamadas para o método ExternalInterface.addCallback() só funcionarão se o arquivo SWF e a página da Web contida estiverem na área de segurança local confiável. Para obter mais informações, consulte o tópico do Centro de desenvolvedores do Flash Player: Security.
Parâmetros
functionName:String — Nome pelo qual o contêiner pode chamar a função.
| |
closure:Function — Função de fechamento a ser chamada. Esta pode ser uma função livre ou pode ser um fechamento de método que se refere a um método de uma ocorrência de objeto. Ao transmitir um fechamento de método, é possível direcionar o retorno de chamada em um método de uma ocorrência de objeto específica.
Observação: a repetição |
Lança
Error — O contêiner não suporta as chamadas recebidas. As chamadas recebidas são suportadas somente no Internet Explorer para Windows e navegadores que usam o NPRuntime API como Mozilla 1.7.5 e posterior ou Firefox 1.0 e posterior.
| |
SecurityError — Um retorno de chamada com o nome especificado já foi adicionado pelo ActionScript em uma caixa de proteção à qual você não tem acesso; não é possível sobrescrever essa chamada de retorno. Para resolver este problema, regrave o ActionScript que originalmente chamou o método addCallback() para que ele também chame o método Security.allowDomain().
| |
SecurityError — O ambiente incluído pertence a uma área de segurança para a qual o código de chamada não tem acesso. Para corrigir este problema, siga estas etapas:
|
Elementos da API relacionados
call | () | método |
public static function call(functionName:String, ... arguments):*| Versão da linguagem: | ActionScript 3.0 |
| Versões de runtime: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Chama uma função exposta pelo contêiner SWF, transmitindo zero ou mais argumentos. Se a função não estiver disponível, a chamada retorna null; caso contrário, ela retorna o valor fornecido pela função. A recursão não é permitida nos navegadores Opera ou Netscape; nestes navegadores uma chamada recursiva produz uma resposta null. (A recursão é suportada nos navegadores Internet Explorer e Firefox).
Se o contêiner for uma página HTML, esse método chamará uma função JavaScript em um elemento script.
Se o contêiner for outro contêiner ActiveX, esse método enviará o evento FlashCall ActiveX com o nome especificado e o contêiner processará o evento.
Se o contêiner estiver hospedando o plug-in Netscape, é possível gravar o suporte personalizado para a nova interface do NPRuntime ou incorporar um controle HTML e incorporar o Flash Player no controle de HTML. Se você tiver incorporado um controle de HTML, será possível se comunicar com o Flash Player por meio de uma interface do JavaScript para o aplicativo do contêiner nativo.
Observação: Para o conteúdo local que está sendo executado em um navegador, as chamadas para o método ExternalInterface.call() só serão permitidas se o arquivo SWF e a página da Web contida (se houver) estiverem na área de segurança local confiável. Além disso, é possível evitar que um arquivo SWF use este método ao definir o parâmetro allowNetworking das marcas object e embed na página HTML que contém o conteúdo SWF. Para obter mais informações, consulte o tópico do Centro de desenvolvedores do Flash Player: Security.
Observação sobre os aplicativos do Flash Player: no Flash Player 10 e no Flash Player 9 Update 5, alguns navegadores da Web restringem esse método caso haja um bloqueador de pop-ups habilitado. Nessa situação, você só pode chamar esse método com êxito em resposta a um evento de usuário (por exemplo, no manipulador de eventos de um clique do mouse ou um evento de pressionamento de tecla).
Parâmetros
functionName:String — Nome alfanumérico da função a ser chamada no contêiner. O uso de um nome de função não alfanumérico causa um erro de tempo de execução (erro 2155). Você pode usar um bloco try..catch para tratar o erro.
| |
... arguments — Argumentos a serem transmitidos para a função no contêiner. É possível especificar zero ou mais parâmetros, separando-os por vírgulas. Eles podem ser de qualquer tipo de dados do ActionScript. Quando a chamada for para uma função JavaScript, os tipos ActionScript serão automaticamente convertidos em tipos JavaScript; quando a chamada for para algum outro contêiner ActiveX, os parâmetros serão codificados na mensagem de solicitação.
|
* — Resposta recebida do contêiner. Se a chamada falhou – por exemplo, se não houver tal função no contêiner, a interface não está disponível, uma recursão ocorreu (com um navegador Netscape ou Opera), ou há um problema de segurança – null é retornado e um erro é despachado.
|
Lança
Error — O contêiner não suporta as chamadas enviadas. As chamadas enviadas são suportadas somente no Internet Explorer para Windows e navegadores que usam o NPRuntime API como Mozilla 1.7.5 e posterior ou Firefox 1.0 e posterior.
| |
SecurityError — O ambiente incluído pertence a uma área de segurança para a qual o código de chamada não tem acesso. Para corrigir este problema, siga estas etapas:
|
Exemplo ( Como usar este exemplo )
//
// 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>
Wed Jun 13 2018, 11:10 AM Z