From 079fefb94cacbc3d34fc5fb4e274877a4339116c Mon Sep 17 00:00:00 2001 From: tristantheb Date: Tue, 25 May 2021 21:51:09 +0200 Subject: FIX: Update from english, fix issue with example - Issue #623 (#869) * FIX: Update from english, fix #623 * Review - minor edits Co-authored-by: julieng --- .../client-side_web_apis/introduction/index.html | 354 ++++++++++----------- 1 file changed, 175 insertions(+), 179 deletions(-) (limited to 'files/fr') diff --git a/files/fr/learn/javascript/client-side_web_apis/introduction/index.html b/files/fr/learn/javascript/client-side_web_apis/introduction/index.html index 1d763d914b..9ac5bc56a8 100644 --- a/files/fr/learn/javascript/client-side_web_apis/introduction/index.html +++ b/files/fr/learn/javascript/client-side_web_apis/introduction/index.html @@ -1,17 +1,17 @@ --- -title: Introduction aux API du Web +title: Introduction aux API Web slug: Learn/JavaScript/Client-side_web_APIs/Introduction tags: + - 3rd party - API - - API Web - - Apprentissage - Article - - Codage - - Débutant - - Navigateur - - Objet - - Tierce partie - - côté‑client + - Beginner + - Browser + - CodingScripting + - Learn + - Object + - WebAPI + - client-side translation_of: Learn/JavaScript/Client-side_web_APIs/Introduction original_slug: Apprendre/JavaScript/Client-side_web_APIs/Introduction --- @@ -19,218 +19,211 @@ original_slug: Apprendre/JavaScript/Client-side_web_APIs/Introduction
{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}
-

Tout d'abord, nous survolerons le concept d'API — qu'est-ce que c'est, comment ça fonctionne, comment les utiliser dans votre code, et comment sont-elles structurées ? Nous verrons également quelles sont les principales APIs et leur utilisation.

+

Tout d'abord, nous verrons dans les grandes lignes ce qu'est une API — leur fonctionnement, comment les utiliser dans votre code, leur structure. Nous verrons également quelles sont les principales API et leur utilisation.

- - - - - - - - - - + + + + + + + + + +
Prérequis :Des connaissances de base en informatique, une compréhension de base du HTML et CSS, des notions de JavaScript (voir premiers pas, briques JavaScript, objets JavaScript).
Objectif :Vous familiariser avec les APIs, ce qu'elles permettent de faire, et comment les utiliser dans votre code.
Prérequis :Des connaissances de base en informatique, une compréhension de base du HTML et CSS, des notions de JavaScript (voir premiers pas, briques JavaScript, objets JavaScript).
Objectif :Vous familiariser avec les API, ce qu'elles permettent de faire, et comment les utiliser dans votre code.
-

C'est quoi une API ?

+

Qu'est-ce qu'une API ?

-

Les APIs (Application Programming Interfaces) sont des constructions disponibles dans les langages de programmation pour permettre aux développeurs de créer plus facilement des fonctionnalités complexes. Elles s'occupent des parties de code plus complexes, fournissant au développeur une syntaxe plus facile à utiliser à la place.

+

Les API (Application Programming Interfaces soit « interface de programmation d'application ») sont des constructions disponibles dans les langages de programmation pour permettre aux développeurs de créer plus facilement des fonctionnalités complexes. Elles s'occupent des parties de code plus complexes, fournissant au développeur une syntaxe plus facile à utiliser à la place.

En guise d'exemple concret, pensez à des branchements électriques dans une maison, appartement ou autre logement. Si vous souhaitez utiliser un appareil dans votre maison, il vous suffit de le brancher dans une prise et cela fonctionne. Vous n'essayez pas de le brancher directement à l'alimentation électrique — le faire serait réellement inefficace, et, si vous n'êtes pas électricien, difficile et dangereux à réaliser.

-

+

-

Image source: Overloaded plug socket by The Clear Communication People, on Flickr.

+

Source de l'image : Overloaded plug socket par The Clear Communication People, sur Flickr.

De la même façon, par exemple, pour programmer des graphismes en 3D, il est beaucoup plus facile de le faire en utilisant une API écrite dans un langage de haut niveau comme JavaScript ou Python, plutôt que d'essayer d'écrire du code bas niveau (comme C ou C ++) qui contrôle directement le GPU de l'ordinateur ou d'autres fonctions graphiques.

-
-

Note : Voir aussi l'entrée API du glossaire pour plus de descriptions.

+
+

Note :

+

Voir aussi l'entrée du glossaire du terme API pour plus de descriptions.

-

APIs JavaScript côté client

+

API JavaScript côté client

-

Le JavaScript côté client en particulier a de nombreuses APIs à sa disposition — elles ne font pas partie du langage JavaScript lui-même, elles sont construites par dessus JavaScript, offrant des super-pouvoirs supplémentaires à utiliser dans votre code. Elles appartiennent généralement à une des deux catégories:

+

Le JavaScript côté client en particulier a de nombreuses API à sa disposition — elles ne font pas partie du langage JavaScript lui-même, elles sont construites par-dessus JavaScript, offrant des super-pouvoirs supplémentaires à utiliser dans votre code. Elles appartiennent généralement à une des deux catégories :

    -
  • API du navigateur : Elles sont intégrées au navigateur Web ; elles peuvent afficher des données provenant du navigateur et de son environnement informatique et faire des choses complexes utiles avec les dites données.
    - Par exemple: l'API de géolocalisation fournit des constructions JavaScript simples pour extraire des données d'emplacement et afficher votre position sur une carte Google Map. En arrière-plan, le navigateur utilise un code de niveau plus bas (par exemple C ++) pour communiquer avec le matériel GPS du périphérique (ou ce qui est disponible pour déterminer les données de position), récupérer les données de position et les renvoyer à l'environnement du navigateur pour l'utiliser dans votre code. Mais encore une fois, cette complexité est abstraite par l'API.
    • -
  • API tierces : Elles ne sont pas intégrées au navigateur par défaut, et vous devez généralement récupérer le code de l'API et des informations depuis un site Web.
    - Par exemple: l'API Twitter vous permet d'afficher vos derniers tweets sur votre site Web. Elle fournit un ensemble de constructions que vous pouvez utiliser pour interroger le service Twitter et qui renvoit alors les informations demandées.
    • +
  • Les API du navigateur sont intégrées au navigateur web et permettent de rendre disponibles les données du navigateur et de son environnement afin de réaliser des choses complexes avec. Ainsi, l'API Web Audio fournit des constructions JavaScript pour manipuler des données audio dans le navigateur. On pourra utiliser cette API afin de récupérer une piste audio puis d'abaisser son volume, d'y appliquer des effets, etc. Sous le capot, c'est le navigateur qui s'occupe des couches plus complexes en code « bas niveau » (C++ ou Rust par exemple) afin de réaliser le traitement du signal. Là encore, cette complexité est masquée par l'abstraction offerte par l'API.
    • +
  • Les API tierces ne sont pas intégrées au navigateur par défaut, et vous devez généralement récupérer le code de l'API et des informations depuis un site Web.
    + Par exemple: l'API Twitter vous permet d'afficher vos derniers tweets sur votre site Web. Elle fournit un ensemble de constructions que vous pouvez utiliser pour interroger le service Twitter et qui renvoie alors les informations demandées.
-

+

-

Relations entre JavaScript, APIs et autres outils JavaScript

+

Relations entre JavaScript, les API et autres outils JavaScript

-

Ci-dessus, nous avons indiqué ce qu'est une API JavaScript côté client et quelle est sa relation avec le langage JavaScript. Pour récapituler, clarifier, et apporter plus de précisions sur  d'autres outils JavaScript qui existent:

+

Ci-dessus, nous avons indiqué ce qu'est une API JavaScript côté client et sa relation avec le langage JavaScript. Pour récapituler, clarifier, et apporter plus de précisions sur d'autres outils JavaScript qui existent:

    -
  • JavaScript — Un langage de programmation de haut niveau intégré aux navigateurs, qui permet de mettre en œuvre des fonctionnalités sur les pages et applications Web. Notez que JavaScript est également disponible dans d'autres environnements de programmation, tels que Node. Mais ne vous en préoccupez pas pour l'instant.
    • -
  • API du navigateur — Constructions intégrées dans le navigateur, situées au‑dessus du langage JavaScript, permettant une mise en œuvre plus facile de fonctionnalités.
    • -
  • API tierce — Constructions intégrées à des plateformes tierces (par exemple Twitter, Facebook) qui permettent d'utiliser certaines fonctionnalités de ces plateformes dans vos propres pages Web (par exemple: afficher vos derniers Tweets sur votre page Web).
    • -
  • Bibliothèques JavaScript — Habituellement, un ou plusieurs fichiers JavaScript contenant des fonctions personnalisées que vous pouvez attacher à votre page Web pour accélérer ou activer l'écriture de fonctionnalités courantes. Des exemples incluent jQuery, Mootools et React.
    • -
  • Les frameworks JavaScript — Au‑dessus des bibliothèques, les frameworks JavaScript (par exemple Angular et Ember) sont plutôt des packages de HTML, CSS, JavaScript et autres technologies, que vous installez puis utilisez pour écrire une application web entière.
    - La différence essentielle entre une bibliothèque et un framework est « l'Inversion du Contrôle ». Avec une bibliothèque, c'est le développeur qui appelle les méthodes de la bibliothèque — il exerce le contrôle. Avec un framework, le contrôle est inversé : c'est le framework qui appelle le code du développeur.
    • +
  • JavaScript — Un langage de programmation de haut niveau intégré aux navigateurs, qui permet de mettre en œuvre des fonctionnalités sur les pages et applications Web. Notez que JavaScript est également disponible dans d'autres environnements de programmation, tels que Node. Mais ne vous en préoccupez pas pour l'instant.
    • +
  • Les API du navigateur — Constructions intégrées dans le navigateur, situées au‑dessus du langage JavaScript, permettant une mise en œuvre plus facile de fonctionnalités.
    • +
  • Les API tierces — Constructions intégrées à des plateformes tierces (par exemple Twitter, Facebook) qui permettent d'utiliser certaines fonctionnalités de ces plateformes dans vos propres pages Web (par exemple: afficher vos derniers Tweets sur votre page Web).
    • +
  • Les bibliothèques JavaScript — Habituellement, un ou plusieurs fichiers JavaScript contenant des fonctions personnalisées que vous pouvez attacher à votre page Web pour accélérer ou activer l'écriture de fonctionnalités courantes. Des exemples incluent jQuery, Mootools et React.
    • +
  • Les frameworks JavaScript — Au‑dessus des bibliothèques, les frameworks JavaScript (par exemple Angular et Ember) sont plutôt des packages de HTML, CSS, JavaScript et autres technologies, que vous installez puis utilisez pour écrire une application web entière.
    + La différence essentielle entre une bibliothèque et un framework est « l'Inversion du Contrôle ». Avec une bibliothèque, c'est le développeur qui appelle les méthodes de la bibliothèque — il exerce le contrôle. Avec un framework, le contrôle est inversé : c'est le framework qui appelle le code du développeur.
-

Que peuvent faire les API ?

+

Que peuvent faire les API ?

-

Il y a un beaucoup d'APIs disponibles dans les navigateurs modernes. Elles permettent de faire un large éventail de choses. Vous pouvez vous en faire une petite idée en jetant un coup d'œil à la page de l'index des API MDN. 

+

Il y a un beaucoup d'API disponibles dans les navigateurs modernes. Elles permettent de faire un large éventail de choses. Vous pouvez vous en faire une petite idée en jetant un coup d'œil à la page de l'index des API MDN.

-

API de navigateur courantes

+

API de navigateur courantes

En particulier, voici les catégories d'API de navigateur les plus courantes que vous utiliserez (et que nous allons voir dans ce module plus en détail) :

    -
  • Les APIs pour manipuler des documents chargés dans le navigateur. L'exemple le plus évident est l'API DOM (Document Object Model). Elle permet de manipuler le HTML et CSS — créer, supprimer et modifier du code HTML, appliquer de nouveaux styles à votre page dynamiquement, etc. Par exemple, chaque fois que vous voyez une fenêtre pop-up apparaître sur une page, ou qu'un nouveau contenu affiché, c'est que le DOM est en action. Découvrez-en plus sur ces types d'API dans la rubrique Manipuler des documents.
    • -
  • Les APIs pour récupérer des données du serveur, afin de mettre à jour des sections d'une page Web, sont couramment utilisées. Ce détail apparemment anodin a eu un impact énorme sur les performances et le comportement des sites — si vous avez juste besoin de mettre à jour une liste de produits ou afficher de nouveaux articles disponibles, le faire instantanément sans avoir à recharger toute la page du serveur peut rendre le site ou l'application beaucoup plus réactif et « accrocheur ». XMLHttpRequest et l'API Fetch sont les API qui rendent ça possible. Vous verrez aussi peut-être le terme Ajax pour qualifier cette technique. Pour en savoir plus sur ces APIs, voir Récupérer des données du serveur.
    • -
  • Les APIs pour dessiner et manipuler des graphiques sont maintenant couramment prises en charge dans les navigateurs — les plus populaires sont Canvas et WebGL. Elles permettent la mise à jour, par programmation, des pixels contenus dans un élément HTML {{htmlelement ("canvas")}} pour créer des scènes 2D et 3D. Par exemple, vous pouvez dessiner des formes comme des rectangles ou des cercles, importer une image sur le canvas, et lui appliquer un filtre sépia ou niveau de gris à l'aide de l'API Canvas ou encore créer une scène 3D complexe avec éclairage et textures en utilisant WebGL. De telles APIs sont souvent combinées avec d'autres APIs, par exemple {{domxref("window.requestAnimationFrame()")}}, pour créer des boucles d'animation (faire des mises à jour continues de scènes) et ainsi créer des dessins animés et des jeux. Pour en savoir plus sur ces APIs, voir Dessiner des éléments graphiques.
    • -
  • Les APIs audio et vidéo comme {{domxref("HTMLMediaElement")}}, Web Audio API ou WebRTC, permettent de faire des choses vraiment intéressantes avec du multimédia, telles que la création de contrôles UI personnalisées pour jouer de l'audio et vidéo, l'affichage de textes comme des légendes et des sous-titres, la récupération de vidéos depuis votre webcam pour l'afficher sur l'ordinateur d'une autre personne dans une visio‑conférence ou encore l'ajout d'effets sur des pistes audio (tels que le gain, la distortion, la balance, etc.). Pour en savoir plus sur ces APIs, voir APIs audio et vidéo.
    • -
  • Les APIs de périphérique permettent essentiellement de manier et récupérer des données à partir de périphériques modernes, de manière utile pour les applications Web. Nous avons déjà parlé de l'API de géolocalisation accédant aux données d'emplacement de l'appareil afin que vous puissiez repérer votre position sur une carte. Autres exemples : indiquer à l'utilisateur qu'une mise à jour est disponible pour une application Web via des notifications système (voir l'API Notifications) ou des vibrations (voir l'API Vibration).
    • -
  • Les APIs de stockage côté client deviennent de plus en plus répandues dans les navigateurs Web — la possibilité de stocker des données côté client est très utile si vous souhaitez créer une application qui enregistre son état entre les chargements de page, et peut-être même fonctionner lorsque le périphérique est hors ligne. Il existe un certain nombre d'options disponibles, par exemple le simple stockage nom/valeur avec l'API Web Storage, et le stockage plus complexe de données tabulaires avec l'API IndexedDB. Pour en savoir plus sur ces APIs, voir Stockage côté client.
    • +
  • Les API pour manipuler des documents chargés dans le navigateur. L'exemple le plus évident est l'API DOM (Document Object Model). Elle permet de manipuler le HTML et CSS — créer, supprimer et modifier du code HTML, appliquer de nouveaux styles à votre page dynamiquement, etc. Par exemple, chaque fois que vous voyez une fenêtre pop-up apparaître sur une page, ou qu'un nouveau contenu affiché, c'est que le DOM est en action. Découvrez-en plus sur ces types d'API dans la rubrique Manipuler des documents.
    • +
  • Les API pour récupérer des données du serveur, afin de mettre à jour des sections d'une page Web, sont couramment utilisées. Ce détail apparemment anodin a eu un impact énorme sur les performances et le comportement des sites — si vous avez juste besoin de mettre à jour une liste de produits ou afficher de nouveaux articles disponibles, le faire instantanément sans avoir à recharger toute la page du serveur peut rendre le site ou l'application beaucoup plus réactif et « accrocheur ». XMLHttpRequest et l'API Fetch sont les API qui rendent ça possible. Vous verrez aussi peut-être le terme Ajax pour qualifier cette technique. Pour en savoir plus sur ces API, voir Récupérer des données du serveur.
    • +
  • Les API pour dessiner et manipuler des graphiques sont maintenant couramment prises en charge dans les navigateurs — les plus populaires sont Canvas et WebGL. Elles permettent la mise à jour, par programmation, des pixels contenus dans un élément HTML <canvas> pour créer des scènes 2D et 3D. Par exemple, vous pouvez dessiner des formes comme des rectangles ou des cercles, importer une image sur le canevas, et lui appliquer un filtre sépia ou niveau de gris à l'aide de l'API Canvas ou encore créer une scène 3D complexe avec éclairage et textures en utilisant WebGL. De telles API sont souvent combinées avec d'autres API, par exemple window.requestAnimationFrame(), pour créer des boucles d'animation (faire des mises à jour continues de scènes) et ainsi créer des dessins animés et des jeux. Pour en savoir plus sur ces API, voir Dessiner des éléments graphiques.
    • +
  • Les API audio et vidéo comme HTMLMediaElement, Web Audio API ou WebRTC, permettent de faire des choses vraiment intéressantes avec du multimédia, telles que la création de contrôles UI personnalisées pour jouer de l'audio et vidéo, l'affichage de textes comme des légendes et des sous-titres, la récupération de vidéos depuis votre webcam pour l'afficher sur l'ordinateur d'une autre personne dans une visio‑conférence ou encore l'ajout d'effets sur des pistes audio (tels que le gain, la distorsion, la balance, etc.). Pour en savoir plus sur ces API, voir API audio et vidéo.
    • +
  • Les API de périphérique permettent essentiellement de manier et récupérer des données à partir de périphériques modernes, de manière utile pour les applications Web. Nous avons déjà parlé de l'API de géolocalisation accédant aux données d'emplacement de l'appareil afin que vous puissiez repérer votre position sur une carte. Autres exemples : indiquer à l'utilisateur qu'une mise à jour est disponible pour une application Web via des notifications système (voir l'API Notifications) ou des vibrations (voir l'API Vibration).
    • +
  • Les API de stockage côté client deviennent de plus en plus répandues dans les navigateurs Web — la possibilité de stocker des données côté client est très utile si vous souhaitez créer une application qui enregistre son état entre les chargements de page, et peut-être même fonctionner lorsque le périphérique est hors ligne. Il existe un certain nombre d'options disponibles, par exemple le simple stockage nom/valeur avec l'API Web Storage, et le stockage plus complexe de données tabulaires avec l'API IndexedDB. Pour en savoir plus sur ces API, voir Stockage côté client.
-

APIs tierces courantes

+

API tierces courantes

-

Il y a une grande variété d'APIs tierces; en voici quelques unes des plus populaires que vous allez probablement utiliser tôt ou tard : 

+

Il y a une grande variété d'API tierces ; en voici quelques-unes des plus populaires que vous allez probablement utiliser tôt ou tard :

    -
  • L'API Twitter — vous permet, par exemple, d'afficher vos derniers tweets sur votre site Web.
    • -
  • L'API Google Maps — vous permet d'afficher des cartes sur vos pages web. Il s'agit à dire vrai d'une suite complète d'APIs, qui gèrent une grande variété de tâches, comme en témoigne l'API Picker Google Maps.
    • -
  • L'API Facebook — vous permet d'utiliser diverses parties de l'écosystème Facebook au profit de votre application, par exemple permettre de se connecter via Facebook, accepter des paiements via l'application, déployer des campagnes publicitaires ciblées, etc.
    • -
  • L'API YouTube — vous permet d'intégrer des vidéos YouTube sur votre site, de rechercher sur YouTube, de créer des playlists, etc.
    • -
  • L'API Twilio — fournit un framework permettant de créer des fonctionnalités d'appel vocal et vidéo dans votre application, d'envoyer des SMS/MMS depuis vos applications, et plus encore.
    • -
- -
-

Note : Vous pouvez trouver des informations sur beaucoup plus d'API tierces dans le répertoire Programmable Web API.

+
  • L'API Twitter vous permet d'afficher vos derniers tweets sur un site web.
    • +
  • Les API de cartographie comme Mapquest et Google Maps API vous permettent de réaliser toute sorte de cartes dans des pages web.
    • +
  • L'ensemble d'API de Facebook permet d'utiliser différentes parties de l'écosystème de Facebook dans votre application (par exemple pour la connexion avec un compte Facebook, la gestion des paiements ou de publicité, etc.).
    • +
  • Les API Telegram permettent d'intégrer le contenu de canaux Telegram sur un site web et de prendre en charge les bots.
    • +
  • L'API YouTube vous permet d'intégrer des vidéos YouTube sur votre site, de faire des recherches sur YouTube, de construire des listes de lecture, etc.
    • +
  • L'API Pinterest fournit des outils pour gérer des tableaux et épingles Pinterest et de les inclures à votre site web.
    • +
  • L'API Twilio fournit un ensemble d'outil pour intégrer des fonctionnalités d'appels audio et vidéo à une application et/ou d'envoyer des SMS/MMS.
    • +
  • L'API Mastodon permet de manipuler les fonctionnalités du réseau social Mastodon grâce à des programmes.
    • + + +
    +

    Note :

    +

    Vous pouvez trouver des informations sur beaucoup plus d'API tierces dans le répertoire Programmable Web API.

    -

    Comment les API fonctionnent-elles?

    +

    Comment les API fonctionnent-elles ?

    -

    Chaque API Javascript fonctionne de manière légèrement différente d'une autre, mais de manière générale, elles ont des fonctionnalités communes et des thèmes similaires.

    +

    Chaque API JavaScript fonctionne de manière légèrement différente d'une autre, mais de manière générale, elles ont des fonctionnalités communes et des thèmes similaires.

    -

    Elles sont fondées sur des objets

    +

    Elles sont fondées sur des objets

    -

    Les APIs interagissent avec le code en utilisant un ou plusieurs objets Javascript, qui servent de conteneurs pour les données utilisées par l'API (contenues dans les propriétés d'objet), et la fonctionnalité rendue disponible par l'API (contenue dans des méthodes d'objet).

    +

    Les API interagissent avec le code en utilisant un ou plusieurs objets JavaScript, qui servent de conteneurs pour les données utilisées par l'API (contenues dans les propriétés d'objet), et la fonctionnalité rendue disponible par l'API (contenue dans des méthodes d'objet).

    -
    -

    Note : Si vous n'êtes pas déjà familier avec le fonctionnement des objets, vous devriez revenir en arrière et parcourir le module objets Javascript avant de continuer.

    +
    +

    Note :

    +

    Si vous n'êtes pas déjà familier avec le fonctionnement des objets, vous devriez revenir en arrière et parcourir le module objets JavaScript avant de continuer.

    -

    Prenons pour exemple l'API Géolocalisation — c'est une API très simple composée de quelques simples objets :

    +

    Prenons comme exemple l'API Web Audio. Il s'agit d'une API assez complexe avec plusieurs objets. Voici les objets principaux :

      -
    • {{domxref ("Geolocation")}}, contient trois méthodes pour contrôler la récupération des données géographiques.
      • -
    • {{domxref ("Position")}}, représente la position de l'appareil à un moment donné — contient un objet {{domxref ("Coordinates")}} avec les informations de position réelles, plus un horodatage.
      • -
    • {{domxref ("Coordinates")}}, contient beaucoup de données utiles sur la position de l'appareil, y compris la latitude et la longitude, l'altitude, la vitesse et la direction du mouvement, et plus encore.
      • +
    • AudioContext, qui représente un graphe audio qui peut être utilisé afin de manipuler la lecture audio dans le navigateur et qui possède différentes méthodes et propriétés qui sont disponibles pour manipuler ce signal audio.
      • +
    • MediaElementAudioSourceNode, qui représente un élément <audio> contenant du son qu'on veut jouer et manipuler dans le contexte.
      • +
    • AudioDestinationNode, qui représente la destination de l'audio, c'est-à-dire le composant physique qui sera utilisé pour produire le son (il s'agit généralement des hauts-parleurs ou des écouteurs).
    -

    Alors comment ces objets interagissent-ils ? Si vous regardez notre exemple maps-example.html (regardez‑le aussi en direct), vous verrez le code suivant : 

    - -
    navigator.geolocation.getCurrentPosition(function(position) {
-  var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
-  var myOptions = {
-    zoom: 8,
-    center: latlng,
-    mapTypeId: google.maps.MapTypeId.TERRAIN,
-    disableDefaultUI: true
-  }
-  var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
-});
    - -
    -

    Note : Quand vous chargez l'exemple ci-dessus pour la première fois, vous devriez voir une boîte de dialogue demandant si vous acceptez de partager votre position avec cette application (voir la section {{anch ("Elles ont des mécanismes de sécurité supplémentaires si nécessaire")}} plus loin dans cet article).
    - Vous devez accepter pour pouvoir inscrire votre position sur la carte. Si vous ne pouvez toujours pas voir la carte, vous devrez activer l'autorisation à la main. Vous pouvez le faire de différentes manières selon le navigateur utilisé ; par exemple, dans Firefox, allez dans > Outils > Informations sur la page > Permissions, puis modifiez le paramètre Accèder à votre position ; dans Chrome, allez à Paramètres > Confidentialité > Afficher les paramètres avancés > Paramètres de contenu, puis modifiez les paramètres d'emplacement.
    -  

    -
    - -

    Pour récupérer l'objet {{domxref("Geolocation")}} du navigateur, on fait appel à {{domxref("Navigator.geolocation")}}. On se sert ensuite de la méthode {{domxref("Geolocation.getCurrentPosition()")}} pour obtenir la position actuelle de notre appareil. On commence donc avec

    - -
    navigator.geolocation.getCurrentPosition(function(position) { ... });
    - -

    C'est pareil que:

    - -
    var myGeo = navigator.geolocation;
-myGeo.getCurrentPosition(function(position) { ... });
    - -

    On peut utiliser la syntaxe point pour chaîner l'accès propriété/méthode et réduire ainsi le nombre de lignes à écrire.

    - -

    La méthode {{domxref("Geolocation.getCurrentPosition()")}} n'a qu'un seul paramètre obligatoire : une fonction anonyme qui s'exécute une fois que la position actuelle du périphérique a été récupérée avec succès. Cette fonction prend elle-même un paramètre, l'objet {{domxref("Position")}}, contenant les données de position actuelle.

    -
    -

    Note : Une fonction prise en argument par une autre fonction s'appelle une fonction de rappel.

    -
    +

    Alors comment ces objets interagissent-ils ? Si vous regardez notre exemple d'élément audio (regardez‑le aussi en direct), vous verrez le code suivant :

    -

    Elles utilisent des fonctions de rappel

    +
    <audio src="outfoxing.mp3"></audio>
 
-
    Cette manière d'appeler des fonctions seulement quand une opération est terminée, pour s'assurer de la bonne fin d'une opération avant d'utiliser les données renvoyées dans une autre opération, est très courante dans les API JavaScript. C'est ce qu'on appelle des opérations {{glossary("asynchronous", "asynchrones")}}.
    
+<button class="paused">Play</button>
+<br>
+<input type="range" min="0" max="1" step="0.01" value="1" class="volume">
    + +

    Nous incluons, tout d'abord, un élément <audio> avec lequel nous intégrons un MP3 dans la page. Nous n'incluons pas de contrôles par défaut du navigateur. Ensuite, nous incluons un <button> que nous utiliserons pour lire et arrêter la musique, et un élément <input> de type range, que nous utiliserons pour ajuster le volume de la piste en cours de lecture.

    -

    Récupérer la position actuelle de l'appareil repose sur un composant externe (le GPS de l'appareil ou un autre matériel de géolocalisation), on ne peut pas garantir que cela sera fait à temps pour utiliser immédiatement les données qu'il renvoie. Par conséquent, quelque chose comme cela ne fonctionne pas :

    +

    Ensuite, examinons le JavaScript de cet exemple.

    -
    var position = navigator.geolocation.getCurrentPosition();
-var myLatitude = position.coords.latitude;
    +

    Nous commençons par créer une instance AudioContext à l'intérieur de laquelle nous allons manipuler notre piste :

    -

    Si la première ligne n'a pas encore renvoyé son résultat, la deuxième ligne renvoie une erreur, car les données de position ne sont pas encore disponibles.

    +
    const AudioContext = window.AudioContext || window.webkitAudioContext;
+const audioCtx = new AudioContext();
    -

    Pour cette raison, les APIs impliquant des opérations asynchrones sont conçues pour utiliser des {{glossary ("callback function","fonctions de rappel")}} ou bien le système plus moderne des Promesses — maintenant disponible dans ECMAScript 6 et largement utilisé dans les nouvelles APIs.

    +

    Ensuite, nous créons des constantes qui stockent les références à nos éléments <audio>, <button> et <input>, et nous utilisons la méthode AudioContext.createMediaElementSource() pour créer un MediaElementAudioSourceNode représentant la source de notre audio — l'élément <audio> sera joué à partir de :

    -

    Pour les APIs tierces, elles doivent être inclues

    +
    const audioElement = document.querySelector('audio');
+const playBtn = document.querySelector('button');
+const volumeSlider = document.querySelector('.volume');
 
-
    On combine l'API Geolocation avec une API tierce — l'API Google Maps — pour tracer l'emplacement renvoyé par getCurrentPosition() sur une carte Google Map. Pour mettre cette API à disposition sur notre page on doit l'inclure — vous trouverez cette ligne dans le code HTML:
    
+const audioSource = audioCtx.createMediaElementSource(audioElement);
    -
    <script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>
    +

    Ensuite, nous incluons deux gestionnaires d'événements qui servent à basculer entre la lecture et la pause lorsque le bouton est pressé et à réinitialiser l'affichage au début lorsque la chanson est terminée :

    -

    Elles utilisent des constructeurs et des options pour être personnalisées

    +
    // lecture/pause de l'audio
+playBtn.addEventListener('click', function() {
+    // vérifier si le contexte est en état de suspension (politique de lecture automatique)
+    if (audioCtx.state === 'suspended') {
+        audioCtx.resume();
+    }
 
-
    Pour afficher la position de l'utilisateur sur la carte, on crée d'abord une instance d'objet LatLng avec le constructeur google.maps.LatLng(). Il prend les valeurs de géolocalisation {{domxref ("coords.latitude")}} et {{domxref ("coords.longitude")}} comme paramètres:
    
+  // si la piste est arrêtée, la lire
+    if (this.getAttribute('class') === 'paused') {
+        audioElement.play();
+        this.setAttribute('class', 'playing');
+        this.textContent = 'Pause'
+    // si une piste est en cours de lecture, l'arrêter
+} else if (this.getAttribute('class') === 'playing') {
+        audioElement.pause();
+        this.setAttribute('class', 'paused');
+        this.textContent = 'Lire';
+    }
+});
 
-
    var latlng = new google.maps.LatLng(
-    position.coords.latitude,
-    position.coords.longitude
-);
    
+// si la piste se termine
+audioElement.addEventListener('ended', function() {
+    playBtn.setAttribute('class', 'paused');
+    playBtn.textContent = 'Lire';
+});
    -

    L'objet que nous avons construit est définit comme la valeur de la propriété center d'un objet d'options, myOptions. Ces options vont être utilisées pour construire la carte.

    +
    +

    Note :

    +

    Certains d'entre vous ont peut-être remarqué que les méthodes play() et pause() utilisées pour lire et mettre en pause la piste ne font pas partie de l'API audio Web ; elles font partie de l'API HTMLMediaElement. qui est différente mais étroitement liée.

    +
    -

    On crée une instance d'objet pour représenter notre carte en appelant le constructeur google.maps.Map() avec deux paramètres — une référence à l'élément {{htmlelement ("div")}} sur lequel on veut afficher la carte (celui avec l'ID map_canvas), et l'objet d'options que nous avons défini juste au-dessus.

    +

    Ensuite, nous créons un objet GainNode à l'aide de la méthode AudioContext.createGain(), qui peut être utilisé pour ajuster le volume de l'audio qui le traverse, et nous créons un autre gestionnaire d'événements qui modifie la valeur du gain (volume) du graphique audio lorsque la valeur du curseur est modifiée :

    -
    var myOptions = {
-  zoom: 8,
-  center: latlng,
-  mapTypeId: google.maps.MapTypeId.TERRAIN,
-  disableDefaultUI: true
-}
+
    const gainNode = audioCtx.createGain();
 
-var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
    
+volumeSlider.addEventListener('input', function() {
+    gainNode.gain.value = this.value;
+});
    -

    Ceci fait, notre carte s'affiche.

    +

    La dernière chose à faire pour que cela fonctionne est de connecter les différents nœuds du graphe audio, ce qui est fait en utilisant la méthode AudioNode.connect() disponible sur chaque type de nœud :

    -

    Ce dernier bloc de code met en évidence deux modèles courants que vous verrez dans de nombreuses APIs. Tout d'abord, les objets des APIs contiennent généralement des constructeurs, qui sont appelés pour créer des instances d'objets. Ensuite, les objets APIs ont souvent plusieurs options disponibles qui peuvent être modifiées pour obtenir l'environnement exact que vous voulez pour votre programme. Les constructeurs d'API acceptent généralement des objets d'options en tant que paramètres, ce qui vous permet de définir leur comportement.

    +
    audioSource.connect(gainNode).connect(audioCtx.destination);
    -
    -

    Note : Ne vous inquiétez pas si vous ne comprenez pas immédiatement le détail de cet exemple . Nous aborderons plus amplement les APIs tierces parties dans un futur article.

    -
    +

    L'audio commence dans la source, qui est ensuite connectée au nœud de gain afin que le volume de l'audio puisse être ajusté. Le nœud de gain est ensuite connecté au nœud de destination afin que le son puisse être lu sur votre ordinateur (la propriété AudioContext.destination représente ce qui est le AudioDestinationNode par défaut disponible sur le matériel de votre ordinateur, par exemple vos haut-parleurs).

    -

    Elles ont des points d'entrée identifiables

    +

    Elles ont des points d'entrée reconnaissables

    -

    Lorsque vous utilisez une API, vous devez d'abord savoir quel est le point d'entrée de l'API. Dans l'API Geolocation, c'est assez simple — c'est la propriété {{domxref ("Navigator.geolocation")}} qui renvoie l'objet {{domxref ("Geolocation")}} du navigateur. Cet objet contient toutes les méthodes disponibles de géolocalisation à l'intérieur.

    +

    Lorsque vous utilisez une API, vous devez vous assurer que vous savez où se trouve le point d'entrée de l'API. Dans l'API Web Audio, c'est assez simple — il s'agit de l'objet AudioContext, qui doit être utilisé pour effectuer toute manipulation audio quelle qu'elle soit.

    -

    L'API DOM (Document Object Model) a un point d'entrée encore plus simple — ses caractéristiques sont généralement trouvées attachées à l'objet {{domxref ("Document")}}, ou à toute instance d'un élément HTML que vous souhaitez affecter d'une manière ou d'une autre. Par exemple:

    +

    L'API DOM (Document Object Model) a également un point d'entrée simple — ses fonctionnalités ont tendance à être trouvées accrochées à l'objet Document, ou à une instance d'un élément HTML que vous voulez affecter d'une manière ou d'une autre, par exemple :

    -
    var em = document.createElement('em'); // créer un nouvel élément
-var para = document.querySelector('p'); // référence à un élément p existant
-em.textContent = 'Hello there!'; // fournir à em un contenu textuel
-para.appendChild(em); // incorporer un paragraphe dans em
    +
    const em = document.createElement('em'); // crée un nouvel élément em
+const para = document.querySelector('p'); // référence à un élément p existant
+em.textContent = 'Hello there!'; // donne à em du contenu textuel
+para.appendChild(em); // intégre em dans le paragraphe
    -

    D'autres API ont des points d'entrée légèrement plus complexes, impliquant souvent un contexte spécifique dans lequel le code de l'API doit être écrit. Par exemple, l'objet contextuel de l'API Canvas est créé en obtenant une référence à l'élément {{htmlelement ("canvas")}} sur lequel vous voulez dessiner, puis en appelant sa méthode {{domxref ("HTMLCanvasElement.getContext ()")}} :

    +

    L'API Canvas repose également sur l'obtention d'un objet de contexte à utiliser pour manipuler les choses, bien que dans ce cas, il s'agisse d'un contexte graphique plutôt que d'un contexte audio. Son objet de contexte est créé en obtenant une référence à l'élément <canvas> sur lequel vous voulez dessiner, puis en appelant sa méthode HTMLCanvasElement.getContext() :

    -
    var canvas = document.querySelector('canvas');
-var ctx = canvas.getContext('2d');
    +
    const canvas = document.querySelector('canvas');
+const ctx = canvas.getContext('2d');
    -

    Tout ce que nous voulons faire sur canvas est alors obtenu en appelant les propriétés et méthodes de l'objet conteneur (qui est une instance de {{domxref ("CanvasRenderingContext2D")}}). Par exemple :

    +

    Tout ce que nous voulons faire au canevas est ensuite réalisé en appelant les propriétés et les méthodes de l'objet contexte (qui est une instance de CanvasRenderingContext2D), par exemple :

    Ball.prototype.draw = function() {
   ctx.beginPath();
@@ -240,69 +233,72 @@ var ctx = canvas.getContext('2d');
    };
    -

    Note : Vous pouvez voir le code source de notre démo « balles rebondissantes » (ou voir directement).

    +

    Note :

    +

    Vous pouvez voir ce code en action dans notre démo de balles rebondissantes (voyez-le fonctionner en direct également).

    -

    Elles utilisent des événements pour réagir aux changements d'état

    +

    Elles utilisent des événements pour gérer les changements d'état

    -

    Nous avons déjà parlé des événements plus haut dans ce cours, dans notre article Introduction aux événements — cet article explique en détail ce que sont les événements Web et leur utilisation dans votre code. Si vous ne vous êtes pas encore familiarisé avec le fonctionnement des événements de l'API Web côté client, vous devriez lire cet article avant de continuer.

    +

    Nous avons déjà abordé les événements plus tôt dans le cours dans notre article Introduction aux événements, qui examine en détail ce que sont les événements web côté client et comment ils sont utilisés dans votre code. Si vous n'êtes pas déjà familiarisé avec le fonctionnement des événements de l'API Web côté client, nous vous conseillons de lire cet article avant de poursuivre.

    -

    Certaines API Web ne détectent pas les événements, d'autres peuvent réagir à certains. Vous pouvez généralement trouver les propriétés des APIs qui permettent de lancer des fonctions lorsque les événements surviennent dans les sections "Gestionnaires d'événements" des documents de réference des APIs.

    +

    Certaines API Web ne contiennent aucun événement, mais la plupart en contiennent au moins quelques-uns. Les propriétés des gestionnaires qui nous permettent d'exécuter des fonctions lorsque des événements se produisent sont généralement répertoriées dans notre matériel de référence dans des sections distinctes intitulées « Gestionnaires d'événements ».

    -

    À titre de simple exemple, les instances de l'objet XMLHttpRequest (qui représentent une requête HTTP vers le serveur pour récupérer une ressource) ont un certain nombre d'événements disponibles. Par exemple, l'événement load est déclenché lorsqu'une réponse a été retournée avec succès avec la ressource demandée, et qu'elle devient alors disponible:

    +

    Nous avons déjà vu un certain nombre de gestionnaires d'événements utilisés dans notre exemple d'API audio Web ci-dessus.

    -
    var requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
-var request = new XMLHttpRequest();
+
    Pour fournir un autre exemple, les instances de l'objet XMLHttpRequest (chacune représente une requête HTTP au serveur pour récupérer une nouvelle ressource d'un certain type) a un certain nombre d'événements disponibles sur eux, par exemple, l'événement load est déclenché lorsqu'une réponse a été renvoyée avec succès contenant la ressource demandée, et qu'elle est désormais disponible.
    
+
+
    Le code suivant fournit un exemple simple de la façon dont cela peut être utilisé :
    
+
+
    let requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
+let request = new XMLHttpRequest();
 request.open('GET', requestURL);
 request.responseType = 'json';
 request.send();
 
 request.onload = function() {
-  var superHeroes = request.response;
+  const superHeroes = request.response;
   populateHeader(superHeroes);
   showHeroes(superHeroes);
 }
    
 
-
    
-
    Note : Vous pouvez voir le code source de notre exemple ajax.html (ou le voir directement).
    
+
    
+  
    Note :
    
+  
    Vous pouvez voir ce code en action dans notre exemple ajax.html (voyez-le en direct également).
    
 
    
 
-
    Les cinq premières lignes définissent l'emplacement de la ressource que nous voulons récupérer, créent une nouvelle instance d'un objet de requête en utilisant le constructeur XMLHttpRequest(), ouvrent une requête HTTP GET pour récupérer la ressource spécifiée, spécifient que la réponse doit être envoyée au format JSON, puis envoient la demande.
    
-
-
    La fonction gestionnaire onload indique ensuite ce qu'on fait avec la réponse. On sait que la réponse sera disponible dès que l'événement load est appelé (sauf si une erreur se produit), on sauvegarde donc la réponse — contenant le JSON renvoyé — dans la variable superHeroes, puis on la passe à deux fonctions différentes pour un traitement ultérieur.
    
+
    Les cinq premières lignes spécifient l'emplacement de la ressource que nous voulons récupérer, créent une nouvelle instance d'un objet de requête en utilisant le constructeur XMLHttpRequest(), ouvrent une requête HTTP GET pour récupérer la ressource spécifiée, spécifient que la réponse doit être envoyée au format JSON, puis envoient la requête.
    
 
-
    Elles ont des mécanismes de sécurité supplémentaires si nécessaire
    
+
    La fonction du gestionnaire onload précise ensuite ce que nous faisons de la réponse. Nous savons que la réponse sera renvoyée avec succès et disponible après le déclenchement de l'événement load (sauf si une erreur s'est produite), nous sauvegardons donc la réponse contenant le JSON renvoyé dans la variable superHeroes, puis nous la passons à deux fonctions différentes pour un traitement ultérieur.
    
 
-
    Les caractéristiques des APIs Web sont soumises aux mêmes considérations de sécurité que JavaScript et des autres technologies Web (par exemple, la same-origin policy), mais elles disposent parfois de mécanismes de sécurité supplémentaires.
    
+
    Elles disposent de mécanismes de sécurité supplémentaires adéquats
    
 
-
    Par exemple, certaines des APIs Web les plus modernes ne fonctionneront que sur les pages HTTPS car elles transmettent des données potentiellement sensibles (exemple: Service Workers et Push).
    
+
    Les fonctionnalités des API Web sont soumises aux mêmes considérations de sécurité que JavaScript et les autres technologies web (par exemple same-origin policy), mais elles disposent parfois de mécanismes de sécurité supplémentaires. Par exemple, certaines des API Web les plus modernes ne fonctionneront que sur des pages servies par HTTPS, car elles transmettent des données potentiellement sensibles (par exemple Service Workers et Push).
    
 
-
    En outre, certaines APIs Web demandent l'autorisation d'être activés par l'utilisateur une fois que les appels sont faits dans votre code. Par exemple, vous avez peut-être remarqué une boîte de dialogue comme celle-ci lors du chargement de notre exemple de Geolocation précédent :
    
+
    En outre, certaines API Web demandent la permission d'être activées à l'utilisateur une fois que les appels à ces interfaces sont effectués dans votre code. À titre d'exemple, l'API Notifications API demande la permission à l'aide d'une boîte de dialogue contextuelle :
    
 
-
    
+
    
 
-
    De même, l'API Notifications demande une autorisation:
    
+
    Les API Web Audio et HTMLMediaElement sont soumises à un mécanisme de sécurité appelé autoplay policy - cela signifie essentiellement que vous ne pouvez pas lire automatiquement l'audio lorsqu'une page se charge — vous devez permettre à vos utilisateurs de déclencher la lecture audio par le biais d'un contrôle comme un bouton. Cette mesure est prise parce que la lecture automatique de l'audio est généralement très ennuyeuse et que nous ne devrions pas y soumettre nos utilisateurs.
    
 
-
    
-
-
    Ces invites d'autorisation sont affichées aux utilisateurs pour des raisons de sécurité — si elles n'étaient pas en place, alors les sites pourraient commencer à suivre secrètement votre emplacement sans que vous le sachiez, ou à vous envoyer des messages indésirables avec beaucoup de notifications ennuyantes.
    
+
    
+  
    Note :
    
+  
    Selon la rigueur du navigateur, ces mécanismes de sécurité peuvent même empêcher l'exemple de fonctionner localement, c'est-à-dire si vous chargez le fichier d'exemple local dans votre navigateur au lieu de l'exécuter à partir d'un serveur web. Au moment de la rédaction de ce document, notre exemple d'API Web Audio ne fonctionnait pas localement sur Google Chrome — nous avons dû le télécharger sur GitHub avant qu'il ne fonctionne.
    
+
    
 
 
    Résumé
    
 
-
    À ce stade, vous devriez avoir une bonne idée de ce que sont les APIs, comment elles fonctionnent et ce que vous pouvez faire avec dans votre code JavaScript. Vous êtes probablement impatients de commencer à faire des choses amusantes avec des APIs spécifiques, alors allons-y ! Par la suite, nous verrons comment manipuler des documents avec le Document Object Model (DOM).
    
+
    À ce stade, vous devriez avoir une bonne idée de ce que sont les API, de leur fonctionnement et de ce que vous pouvez faire avec dans votre code JavaScript. Vous avec probablement hâte de commencer à faire des choses amusantes avec des API spécifiques, alors allons-y ! Par la suite, nous verrons comment manipuler des documents avec le Document Object Model (DOM).
    
 
 
    {{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}
    
 
-
    Dans ce module
    
+
    Dans ce module
    
 
 
-
-
     
    
-- 
cgit v1.2.3-54-g00ecf