Avantages de l’API externe et conditions requises

Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures

L’API externe correspond à la partie d’ActionScript qui fournit le mécanisme de communication entre ActionScript et le code exécuté dans une application dite externe, c’est-à-dire qui joue le rôle de conteneur pour Flash Player (en général un navigateur Web ou une application de projection autonome). Dans ActionScript 3.0, la fonctionnalité de l’API externe est assurée par la classe ExternalInterface. Dans les versions de Flash Player antérieures à Flash Player 8, l’action fscommand() était utilisée pour établir les communications avec l’application conteneur. La classe ExternalInterface remplace l’action fscommand().

Remarque : si vous devez utiliser l’ancienne fonction fscommand() (par exemple pour maintenir la compatibilité avec d’anciennes applications ou pour interagir avec une application conteneur SWF tierce ou avec le lecteur autonome Flash Player), elle est disponible au niveau du package flash.system.

La classe ExternalInterface est un sous-système permettant de communiquer facilement d’ActionScript et Flash Player à JavaScript dans une page HTML.

La classe ExternalInterface est disponible uniquement dans les circonstances suivantes :

  • Dans toutes les versions prises en charge d’Internet Explorer pour Windows (5.0 et les versions ultérieures)

  • Dans un navigateur qui prend en charge l’interface NPRuntime, qui actuellement comprend Firefox 1.0 et versions ultérieures, Mozilla 1.7.5 et versions ultérieures, Netscape 8.0 et versions ultérieures, ainsi que Safari 1.3 et versions ultérieures.

  • Dans une application AIR, lorsque le fichier SWF est intégré dans une page HTML affichée par la commande HTMLLoader.

Dans tous les autres cas de figure (par exemple exécution dans un lecteur autonome), la propriété ExternalInterface.available renvoie la valeur false.

Depuis ActionScript, vous pouvez appeler une fonction JavaScript sur la page HTML. L’API externe apporte les améliorations fonctionnelles suivantes grâce à fscommand() :

  • Vous pouvez utiliser toutes les fonctions JavaScript, pas seulement les fonctions compatibles avec fscommand().

  • Vous pouvez transmettre n’importe quel nombre d’arguments, avec n’importe quels noms ; vous n’êtes pas limité à une commande et une chaîne d’argument. L’API externe offre donc bien plus de souplesse que fscommand().

  • Vous pouvez transmettre divers types de données (Boolean, Number et String, entre autres) et n’êtes plus limité aux paramètres String.

  • Vous pouvez recevoir la valeur d’un appel, et cette valeur retourne immédiatement à ActionScript (comme la valeur de retour d’un appel que vous faites).

Important : si le nom attribué à l’occurrence de Flash Player sur une page HTML (l’attribut id de la balise object) contient un tiret (-) ou un autre caractère défini en tant qu’opérateur dans JavaScript (tels +, *, /, \, ., etc.), les appels à ExternalInterface effectués depuis ActionScript ne fonctionnent pas lorsque la page Web du conteneur est consultée dans Internet Explorer. En outre, si les balises HTML qui définissent l’occurrence de Flash Player (les balises object et embed) sont imbriquées dans une balise form HTML, les appels à ExternalInterface effectués depuis ActionScript ne fonctionnent pas.