Cette page a été traduite à partir de l'anglais par la communauté.Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.
L'API HTML DOM
Baseline Widely available *
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.
L'API HTML DOM est composée des interfaces qui définissent les fonctionnalités de chacun deséléments dansHTML, ainsi que des types et interfaces de support sur lesquels ils s'appuient.
Les domaines fonctionnels inclus dans l'API HTML DOM comprennent :
- L'accès aux éléments HTML et leur contrôle via leDOM.
- L'accès aux données des formulaires et leur manipulation.
- L'interaction avec le contenu des images 2D et le contexte d'un
<canvas>HTML, par exemple pour dessiner par-dessus. - La gestion des médias associés aux éléments multimédias HTML (
<audio>et<video>). - Le glisser-déposer de contenu sur les pages web.
- L'accès à l'historique de navigation du navigateur.
- Des interfaces de support et de connexion pour d'autres API telles queWeb Components,Web Storage,Web Workers,WebSocket etServer-sent events.
Concepts et utilisation du HTML DOM
Dans cet article, nous nous concentrerons sur les parties du HTML DOM qui impliquent l'interaction avec des éléments HTML. Les discussions sur d'autres domaines, tels queDrag and Drop,WebSockets,Web Storage, etc. se trouvent dans la documentation de ces API.
Structure d'un document HTML
Le Document Object Model (DOM) est une architecture qui décrit la structure d'undocument ; chaque document est représenté par une instance de l'interfaceDocument. Un document, à son tour, consiste en un arbre hiérarchique denœuds, dans lequel un nœud est un enregistrement fondamental représentant un seul objet au sein du document (tel qu'un élément ou un nœud de texte).
Les nœuds peuvent être strictement organisationnels, fournissant un moyen de regrouper d'autres nœuds ou un point à partir duquel une hiérarchie peut être construite ; d'autres nœuds peuvent représenter des composants visibles d'un document. Chaque nœud est basé sur l'interfaceNode, qui fournit des propriétés pour obtenir des informations sur le nœud ainsi que des méthodes pour créer, supprimer et organiser des nœuds au sein du DOM.
Les nœuds n'ont pas de notion d'inclure le contenu réellement affiché dans le document. Ce sont des récipients vides. La notion fondamentale d'un nœud pouvant représenter un contenu visuel est introduite par l'interfaceElement. Une instance d'objetElement représente un seul élément dans un document créé à l'aide soit de HTML, soit d'un vocabulaireXML tel queSVG.
Par exemple, considérons un document avec deux éléments, dont l'un possède deux autres éléments imbriqués à l'intérieur :
Alors que l'interfaceDocument est définie dans la spécificationDOM, la spécification HTML l'enrichit significativement pour ajouter des informations spécifiques à l'utilisation du DOM dans le contexte d'un navigateur web, ainsi qu'à son utilisation pour représenter spécifiquement des documents HTML.
Parmi les éléments ajoutés àDocument par la norme HTML :
- La prise en charge de l'accès à diverses informations fournies par les en-têtesHTTP lors du chargement de la page, telles que lalocation depuis laquelle le document a été chargé, lescookies, ladate de modification, lesite référent, etc.
- L'accès à des listes d'éléments dans le bloc
<head>du document et dans lebody, ainsi qu'à des listes desimages,liens,scripts, etc. contenus dans le document. - La prise en charge de l'interaction avec l'utilisateur·ice en examinant lefocus et en exécutant des commandes sur lecontenu éditable.
- Des gestionnaires d'événements pour les événements de document définis par la norme HTML afin de permettre l'accès aux événements desouris et declavier, auglisser-déposer, aucontrôle des médias, et plus encore.
- Des gestionnaires d'événements pour des événements pouvant être délivrés à la fois aux éléments et aux documents ; ceux-ci incluent actuellement uniquement les actions
copy,cutetpaste.
Interfaces des éléments HTML
L'interfaceElement a été davantage adaptée pour représenter spécifiquement les éléments HTML en introduisant l'interfaceHTMLElement, dont héritent toutes les classes d'éléments HTML plus spécifiques. Cela étend la classeElement pour ajouter des fonctionnalités générales spécifiques à HTML aux nœuds d'élément. Les propriétés ajoutées parHTMLElement comprennent par exemplehidden etinnerText.
Un documentHTML est un arbre DOM dans lequel chacun des nœuds est un élément HTML, représenté par l'interfaceHTMLElement. La classeHTMLElement, à son tour, implémenteNode, donc chaque élément est aussi un nœud (mais l'inverse n'est pas vrai). De cette manière, les fonctionnalités structurelles implémentées par l'interfaceNode sont également disponibles pour les éléments HTML, leur permettant d'être imbriqués les uns dans les autres, créés et supprimés, déplacés, etc.
L'interfaceHTMLElement est cependant générique, ne fournissant que les fonctionnalités communes à tous les éléments HTML telles que l'ID de l'élément, ses coordonnées, le HTML constituant l'élément, des informations sur la position de défilement, etc.
Afin d'étendre les fonctionnalités de base de l'interfaceHTMLElement pour fournir les caractéristiques nécessaires à un élément spécifique, la classeHTMLElement est sous-classée pour ajouter les propriétés et méthodes nécessaires. Par exemple, l'élément<canvas> est représenté par un objet de typeHTMLCanvasElement.HTMLCanvasElement augmente le typeHTMLElement en ajoutant des propriétés telles queheight et des méthodes commegetContext() pour fournir des fonctionnalités spécifiques au canvas.
L'héritage global des classes d'éléments HTML ressemble à ceci :
Ainsi, un élément hérite des propriétés et méthodes de tous ses ancêtres. Par exemple, considérons un élément<a>, qui est représenté dans le DOM par un objet de typeHTMLAnchorElement. L'élément inclut alors les propriétés et méthodes spécifiques à l'ancre décrites dans la documentation de cette classe, mais aussi celles définies parHTMLElement etElement, ainsi que parNode et, finalement,EventTarget.
Chaque niveau définit un aspect clé de l'utilité de l'élément. À partir deNode, l'élément hérite des concepts entourant la capacité pour l'élément d'être contenu par un autre élément, et de contenir d'autres éléments lui-même. D'une importance particulière est ce qui est gagné en héritant deEventTarget : la capacité de recevoir et de gérer des événements tels que des clics de souris, des événements de lecture et de pause, etc.
Il existe des éléments qui partagent des points communs et ont donc un type intermédiaire supplémentaire. Par exemple, les éléments<audio> et<video> présentent tous deux des médias audiovisuels. Les types correspondants,HTMLAudioElement etHTMLVideoElement, sont tous deux basés sur le type communHTMLMediaElement, qui à son tour est basé surHTMLElement, et ainsi de suite.HTMLMediaElement définit les méthodes et propriétés communes entre les éléments audio et vidéo.
Ces interfaces spécifiques aux éléments constituent la majorité de l'API HTML DOM, et sont l'objet de cet article. Pour en savoir plus sur la structure réelle duDOM, voirIntroduction au DOM.
Public cible du HTML DOM
Les fonctionnalités exposées par le HTML DOM font partie des API les plus couramment utilisées dans la boîte à outils d'un·e développeur·euse web.Toutes les applications web sauf les plus simples utiliseront certaines fonctionnalités du HTML DOM.
Interfaces de l'API HTML DOM
La majorité des interfaces qui composent l'API HTML DOM correspondent presque un pour un à des éléments HTML individuels, ou à un petit groupe d'éléments ayant des fonctionnalités similaires. En outre, l'API HTML DOM inclut quelques interfaces et types pour prendre en charge les interfaces des éléments HTML.
Interfaces des éléments HTML
Ces interfaces représentent des éléments HTML spécifiques (ou des ensembles d'éléments apparentés qui partagent les mêmes propriétés et méthodes associées).
HTMLAnchorElementHTMLAreaElementHTMLAudioElementHTMLBaseElementHTMLBodyElementHTMLBRElementHTMLButtonElementHTMLCanvasElementHTMLDataElementHTMLDataListElementHTMLDetailsElementHTMLDialogElementHTMLDirectoryElementHTMLDivElementHTMLDListElementHTMLElementHTMLEmbedElementHTMLFieldSetElementHTMLFormElementHTMLHRElementHTMLHeadElementHTMLHeadingElementHTMLHtmlElementHTMLIFrameElementHTMLImageElementHTMLInputElementHTMLLabelElementHTMLLegendElementHTMLLIElementHTMLLinkElementHTMLMapElementHTMLMediaElementHTMLMenuElementHTMLMetaElementHTMLMeterElementHTMLModElementHTMLObjectElementHTMLOListElementHTMLOptGroupElementHTMLOptionElementHTMLOutputElementHTMLParagraphElementHTMLPictureElementHTMLPreElementHTMLProgressElementHTMLQuoteElementHTMLScriptElementHTMLSelectElementHTMLSlotElementHTMLSourceElementHTMLSpanElementHTMLStyleElementHTMLTableCaptionElementHTMLTableCellElementHTMLTableColElementHTMLTableElementHTMLTableRowElementHTMLTableSectionElementHTMLTemplateElementHTMLTextAreaElementHTMLTimeElementHTMLTitleElementHTMLTrackElementHTMLUListElementHTMLUnknownElementHTMLVideoElement
Interfaces d'éléments HTML dépréciées
Interfaces d'éléments HTML obsolètes
Interfaces d'intégration aux applications web et au navigateur
Ces interfaces offrent un accès à la fenêtre et au document du navigateur qui contiennent le HTML, ainsi qu'à l'état du navigateur, aux plugins disponibles (le cas échéant) et à diverses options de configuration.
Interfaces d'intégration dépréciées
Interfaces d'intégration obsolètes
Interfaces de prise en charge des formulaires
Ces interfaces fournissent la structure et les fonctionnalités requises par les éléments utilisés pour créer et gérer des formulaires, y compris les éléments<form> et<input>.
Interfaces de canvas et d'image
Ces interfaces représentent des objets utilisés par l'API Canvas ainsi que l'élément<img> et les éléments<picture>.
Interfaces multimédias
Les interfaces multimédias fournissent un accès HTML au contenu des éléments multimédias :<audio> et<video>.
Interfaces de glisser-déposer
Ces interfaces sont utilisées par l'API de glisser-déposer HTML pour représenter des éléments individuels pouvant être glissés (ou en cours de glissement), des groupes d'éléments glissés ou pouvant être glissés, et pour gérer le processus de glisser-déposer.
Interfaces de l'historique des pages
Les interfaces de l'API History permettent d'accéder aux informations sur l'historique du navigateur, ainsi que de faire avancer et reculer l'onglet courant du navigateur dans cet historique.
Interfaces des Web Components
Ces interfaces sont utilisées par l'API Web Components pour créer et gérer leséléments personnalisés disponibles.
Interfaces diverses et de support
Ces types d'objets de support sont utilisés de diverses manières dans l'API HTML DOM. De plus,PromiseRejectionEvent représente l'événement émis lorsqu'uneJavaScriptPromise est rejetée.
Interfaces appartenant à d'autres API
Plusieurs interfaces sont techniquement définies dans la spécification HTML tout en faisant partie d'autres API.
Interfaces du stockage web
L'API Web Storage fournit la capacité pour les sites web de stocker des données temporairement ou de manière permanente sur l'appareil de l'utilisateur·ice pour une réutilisation ultérieure.
Interfaces des Web Workers
Ces interfaces sont utilisées par l'API Web Workers à la fois pour établir la capacité des workers à interagir avec une application et son contenu, et pour prendre en charge la messagerie entre fenêtres ou applications.
BroadcastChannelDedicatedWorkerGlobalScopeMessageChannelMessageEventMessagePortSharedWorkerSharedWorkerGlobalScopeWorkerWorkerGlobalScopeWorkerLocationWorkerNavigator
Interfaces WebSocket
Ces interfaces, définies par la spécification HTML, sont utilisées par l'API WebSockets.
Interfaces des événements envoyés par le serveur
L'interfaceEventSource représente la source qui a envoyé ou envoie desévénements envoyés par le serveur.
Exemples
Dans cet exemple, l'événementinput d'un élément<input> est surveillé afin de mettre à jour l'état du bouton "submit" d'un formulaire selon qu'un champ donné a actuellement une valeur ou non.
JavaScript
const champNom = document.getElementById("userName");const boutonEnvoyer = document.getElementById("sendButton");boutonEnvoyer.disabled = true;// [note : ceci est désactivé car cela fait toujours charger cet article avec cet exemple focalisé et déroulé dans la vue]// champNom.focus();champNom.addEventListener("input", (event) => { const elem = event.target; const valid = elem.value.length !== 0; if (valid && boutonEnvoyer.disabled) { boutonEnvoyer.disabled = false; } else if (!valid && !boutonEnvoyer.disabled) { boutonEnvoyer.disabled = true; }});Ce code utilise la méthodegetElementById() de l'interfaceDocument pour obtenir l'objet DOM représentant les éléments<input> dont les ID sontuserName etsendButton. Avec ceux-ci, nous pouvons accéder aux propriétés et méthodes qui fournissent des informations sur ces éléments et en donnent le contrôle.
L'objetHTMLInputElement pour la propriétédisabled du bouton « Envoyer » est défini àtrue, ce qui désactive le bouton « Envoyer » afin qu'il ne puisse pas être cliqué. De plus, le champ de saisie du nom d'utilisateur·ice est rendu actif en appelant la méthodefocus() qu'il hérite deHTMLElement.
Ensuite,addEventListener() est appelé pour ajouter un gestionnaire pour l'événementinput au champ de nom d'utilisateur·ice. Ce code examine la longueur de la valeur actuelle de l'entrée ; si elle est zéro, alors le bouton « Envoyer » est désactivé s'il ne l'est pas déjà. Sinon, le code s'assure que le bouton est activé.
Avec cela en place, le bouton « Envoyer » est toujours activé lorsque le champ de saisie du nom d'utilisateur·ice a une valeur, et désactivé lorsqu'il est vide.
HTML
Le HTML du formulaire ressemble à ceci :
<p> Veuillez fournir les informations ci-dessous. Les éléments marqués par "*" sont requis.</p><form action="" method="get"> <p> <label for="userName" required>Votre nom :</label> <input type="text" /> (*) </p> <p> <label for="userEmail">E-mail :</label> <input type="email" /> </p> <input type="submit" value="Envoyer" /></form>Résultat
Spécifications
| Specification |
|---|
| HTML # htmlelement |