Document : La méthode getElementById()

La méthode getElementById() de l'interface Document renvoie un objet Element représentant l'élément dont la propriété id correspond à la chaîne de caractères spécifiée. Étant donné que les ID d'élément doivent être uniques, s'ils sont spécifiés, ils constituent un moyen utile d'accéder rapidement à un élément spécifique.

Si vous avez besoin d'accéder à un élément qui n'a pas d'ID, vous pouvez utiliser querySelector() pour trouver l'élément en utilisant un sélecteur.

Note : Les identifiants doivent être uniques à l'intérieur d'un document. Si deux éléments ou plus — d'un document — ont le même ID, cette méthode renvoie le premier élément trouvé.

Syntaxe

js
getElementById(id)

Note : La capitalisation de "Id" dans le nom de cette méthode doit être correcte pour que le code fonctionne ; getElementByID() n'est pas valide et ne fonctionnera pas, aussi naturel que cela puisse paraître.

Paramètres

id

L'identifiant (ID) de l'élément à localiser. Il est une chaîne de caractères sensible à la casse qui est unique ; un seul élément peut avoir un ID donné.

Valeur de retour

Un objet Element décrivant l'objet élément du DOM correspondant à l'identifiant (ID) spécifié ou null si aucun n'a été trouvé dans le document.

Exemples

HTML

html
<html lang="fr">
  <head>
    <title>exemple de getElementById</title>
  </head>
  <body>
    <p id="para">Un peu de texte ici</p>
    <button onclick="changerCouleur('blue');">bleu</button>
    <button onclick="changerCouleur('red');">rouge</button>
  </body>
</html>

JavaScript

js
function changerCouleur(nouvelleCouleur) {
  const paragraphe = document.getElementById("para");
  paragraphe.style.color = nouvelleCouleur;
}

Résultat

Notes d'utilisation

Contrairement à d'autres méthodes de recherche d'éléments, comme Document.querySelector() et Document.querySelectorAll(), getElementById est uniquement disponible comme méthode de l'objet global document et n'est pas disponible sur tous les objets du DOM. Parce que les valeurs d'ID doivent être uniques dans l'ensemble du document, il n'y a pas besoin d'avoir une version « locale » de la fonction.

Exemple

html
<!doctype html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <div id="parent-id">
      <p>bonjour tout le monde1</p>
      <p id="test1">bonjour tout le monde2</p>
      <p>bonjour tout le monde3</p>
      <p>bonjour tout le monde4</p>
    </div>
    <script>
      const parentDOM = document.getElementById("parent-id");
      const test1 = parentDOM.getElementById("test1");
      // erreur de lancement
      // TypeError inattendu : parentDOM.getElementById n'est pas une fonction
    </script>
  </body>
</html>

S'il n'y a pas d'élément avec l'identifiant (id) fourni, cette fonction retourne null. À noter que le paramètre id est sensible à la casse, ainsi document.getElementById("Main") retournera null au lieu de l'élément <div id="main"> étant donné que « M » et « m » sont différents pour cette méthode.

Les éléments absents du document ne sont pas cherchés par getElementById(). Quand vous créez un élément et y assignez un ID, vous devez insérer l'élément dans l'arbre du document avec Node.insertBefore() ou une méthode similaire avant de pouvoir y accéder avec getElementById() :

js
const element = document.createElement("div");
element.id = "testqq";
const el = document.getElementById("testqq"); // el vaudra null !

Dans des documents non-HTML, les implémentations du DOM doivent avoir une information qui précise quels attributs sont de type ID. Un attribut portant le nom « id » n'est pas de type ID tant qu'il n'a pas été explicitement défini ainsi (dans la DTD du document). L'attribut id est défini comme étant de type ID dans les langages courants comme XHTML, XUL, et d'autres. Les implémentations ne sachant pas déterminer si les attributs sont de type ID ou non sont supposées renvoyer null.

Spécifications

Specification
DOM Standard
# ref-for-dom-nonelementparentnode-getelementbyid②

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi

  • L'interface Document référence pour d'autres méthodes et propriétés que vous pouvez utiliser pour obtenir la référence vers des éléments du document.
  • La méthode Document.querySelector() pour utiliser des sélecteurs avec des requêtes comme 'div.myclass'.
  • La méthode Document.evaluate() qui dispose d'une méthode utilitaire pour sélectionner par xml:id dans les documents XHTML.