1. Technologies web pour développeurs
  2. Les API Web
  3. L'API HTML DOM

Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

L'API HTML DOM

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨juillet 2015⁩.

* Some parts of this feature may have varying levels of support.

L'API HTML DOM est composée des interfaces qui définissent les fonctionnalités de chacun des éléments dans HTML, 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 le DOM.
  • 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 que Web Components, Web Storage, Web Workers, WebSocket et Server-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 que Drag 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'un document ; chaque document est représenté par une instance de l'interface Document. Un document, à son tour, consiste en un arbre hiérarchique de nœ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'interface Node, 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'interface Element. Une instance d'objet Element représente un seul élément dans un document créé à l'aide soit de HTML, soit d'un vocabulaire XML tel que SVG.

Par exemple, considérons un document avec deux éléments, dont l'un possède deux autres éléments imbriqués à l'intérieur :

Structure d'un document avec des éléments à l'intérieur d'un document dans une fenêtre

Alors que l'interface Document est définie dans la spécification DOM, 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êtes HTTP lors du chargement de la page, telles que la location depuis laquelle le document a été chargé, les cookies, la date de modification, le site référent, etc.
  • L'accès à des listes d'éléments dans le bloc <head> du document et dans le body, ainsi qu'à des listes des images, liens, scripts, etc. contenus dans le document.
  • La prise en charge de l'interaction avec l'utilisateur·ice en examinant le focus et en exécutant des commandes sur le contenu é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 de souris et de clavier, au glisser-déposer, au contrô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, cut et paste.

Interfaces des éléments HTML

L'interface Element a été davantage adaptée pour représenter spécifiquement les éléments HTML en introduisant l'interface HTMLElement, dont héritent toutes les classes d'éléments HTML plus spécifiques. Cela étend la classe Element pour ajouter des fonctionnalités générales spécifiques à HTML aux nœuds d'élément. Les propriétés ajoutées par HTMLElement comprennent par exemple hidden et innerText.

Un document HTML est un arbre DOM dans lequel chacun des nœuds est un élément HTML, représenté par l'interface HTMLElement. La classe HTMLElement, à son tour, implémente Node, 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'interface Node 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'interface HTMLElement 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'interface HTMLElement pour fournir les caractéristiques nécessaires à un élément spécifique, la classe HTMLElement 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 type HTMLCanvasElement. HTMLCanvasElement augmente le type HTMLElement en ajoutant des propriétés telles que height et des méthodes comme getContext() pour fournir des fonctionnalités spécifiques au canvas.

L'héritage global des classes d'éléments HTML ressemble à ceci :

Hiérarchie des interfaces pour les éléments HTML

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 type HTMLAnchorElement. 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 par HTMLElement et Element, ainsi que par Node et, finalement, EventTarget.

Chaque niveau définit un aspect clé de l'utilité de l'élément. À partir de Node, 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 de EventTarget : 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 et HTMLVideoElement, sont tous deux basés sur le type commun HTMLMediaElement, qui à son tour est basé sur HTMLElement, 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 du DOM, voir Introduction 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).

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'une JavaScript Promise 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.

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'interface EventSource représente la source qui a envoyé ou envoie des événements envoyés par le serveur.

Exemples

Dans cet exemple, l'événement input 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

js
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éthode getElementById() de l'interface Document pour obtenir l'objet DOM représentant les éléments <input> dont les ID sont userName et sendButton. 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'objet HTMLInputElement 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éthode focus() qu'il hérite de HTMLElement.

Ensuite, addEventListener() est appelé pour ajouter un gestionnaire pour l'événement input 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 :

html
<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&nbsp;:</label>
    <input type="text" id="userName" /> (*)
  </p>
  <p>
    <label for="userEmail">E-mail&nbsp;:</label>
    <input type="email" id="userEmail" />
  </p>
  <input type="submit" value="Envoyer" id="sendButton" />
</form>

Résultat

Spécifications

Specification
HTML
# htmlelement

Compatibilité des navigateurs

Voir aussi

Références

Guides

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content