Element : méthode insertAdjacentHTML()

Syntaxe

insertAdjacentHTML(position, input)

Paramètres

position

Une chaîne de caractères représentant la position relative à l'élément. Doit être l'une des chaînes de caractères suivantes :

"beforebegin"

Avant l'élément. Valide uniquement si l'élément est dans l'arbre DOM et a un élément parent.

"afterbegin"

Juste à l'intérieur de l'élément, avant son premier enfant.

"beforeend"

Juste à l'intérieur de l'élément, après son dernier enfant.

"afterend"

Après l'élément. Valide uniquement si l'élément est dans l'arbre DOM et a un élément parent.

input

Une instance de TrustedHTML ou une chaîne de caractères définissant le HTML ou XML à analyser.

Valeur de retour

Aucune (undefined).

Exceptions

Cette méthode peut lever une DOMException de l'un des types suivants :

NoModificationAllowedError DOMException

Levée si position est "beforebegin" ou "afterend" et que l'élément n'a pas de parent ou que son parent est l'objet Document.

SyntaxError DOMException

Levée si :

• position n'est pas l'une des quatre valeurs listées.
• L'entrée est du XML qui n'est pas bien formé.

TypeError

Levée si la propriété est définie sur une chaîne de caractères lorsque les Trusted Types sont appliqués par une CSP et qu'aucune politique par défaut n'est définie.

Description

La méthode insertAdjacentHTML() ne réanalyse pas l'élément sur lequel elle est utilisée, et ne corrompt donc pas les éléments existants à l'intérieur de cet élément. Cela évite l'étape supplémentaire de sérialisation, ce qui la rend beaucoup plus rapide que la manipulation directe de innerHTML.

Lorsque <p> est l'élément, nous pouvons visualiser les positions possibles pour le contenu inséré "toto" comme suit :

<!-- beforebegin -->
<p>
  <!-- afterbegin -->
  toto
  <!-- beforeend -->
</p>
<!-- afterend -->

La méthode ne prévoit aucun traitement particulier pour les éléments <template>. Dans la plupart des cas, les développeur·euse·s doivent utiliser la fonction insertAdjacentHTML() sur la propriété content du modèle, plutôt que de manipuler directement les nœuds enfants d'un élément de modèle.

Considérations de sécurité

La méthode n'effectue aucun assainissement visant à supprimer les éléments présentant un risque de XSS, tels que <script> ou les attributs de contenu des gestionnaires d'évènements.

Lorsque vous insérez du code HTML dans une page à l'aide de insertAdjacentHTML(), vous devez passer des objets TrustedHTML plutôt que des chaînes de caractères, et imposer des types fiables à l'aide de la directive CSP require-trusted-types-for. Cela garantit que les données sont transmises par une fonction de transformation, qui a la possibilité d'assainir les données afin de supprimer tout balisage potentiellement dangereux avant leur injection.

La méthode Element.insertAdjacentText() ou Node.textContent doit être utilisée lorsque vous savez que le contenu fourni par l'utilisateur·ice doit être du texte brut. Cela permet d'insérer les données sous forme de texte brut au lieu de les analyser en HTML.

Exemples

Insérer du HTML

Cet exemple démontre les quatre positions d'insertion. Tout le texte inséré est en gras, tandis que le texte inséré à l'intérieur de l'élément est en plus mis en forme en monotype rouge (code).

HTML

<select id="position">
  <option>beforebegin</option>
  <option>afterbegin</option>
  <option>beforeend</option>
  <option>afterend</option>
</select>

<button id="inserer">Insérer du HTML</button>
<button id="reinitialiser">Réinitialiser</button>

<p>
  Du texte, avec un <code id="sujet">élément mis en forme en code</code>
  à l'intérieur.
</p>

CSS

code {
  color: red;
}

JavaScript

Les types de confiance ne sont pas pris en charge par tous les navigateurs, nous allons donc commencer par définir une prothèse d'émulation des types de confiance. Celle-ci sert de remplacement transparent à l'API JavaScript des types de confiance :

if (typeof typesDeConfiance === "undefined")
  typesDeConfiance = { createPolicy: (n, regles) => regles };

Ensuite, nous définissons une politique nommée contenu-de-la-politique pour créer des objets TrustedHTML à partir de l'entrée (nous devons également appliquer la contenu-de-la-politique en utilisant CSP). Le code implémente une politique sans effet afin de permettre à cet exemple de fonctionner sans dépendance tierce. Votre propre code applicatif doit utiliser une bibliothèque tierce telle que la bibliothèque « DOMPurify » pour retourner un contenu assaini à partir de l'entrée non fiable.

const politique = trustedTypes.createPolicy("contenu-de-la-politique", {
  createHTML(input) {
    return input; // Ne faites pas cela dans votre propre code !
    // À la place, faites quelque chose comme :
    // return DOMPurify.sanitize(input);
  },
});

const texteNonSecure = "<strong>texte inséré</strong>";
const HTMLDeConfiance = politique.createHTML(texteNonSecure);

Le code restant insère le HTML de confiance à la position sélectionnée par rapport à l'élément ayant l'id sujet.

const inserer = document.querySelector("#inserer");
inserer.addEventListener("click", () => {
  const sujet = document.querySelector("#sujet");
  const positionSelect = document.querySelector("#position");
  sujet.insertAdjacentHTML(positionSelect.value, HTMLDeConfiance);
});

const reinitialiser = document.querySelector("#reinitialiser");
reinitialiser.addEventListener("click", () => {
  document.location.reload();
});

Résultat

Spécifications

Compatibilité des navigateurs

Voir aussi

• La méthode Element.insertAdjacentElement()
• La méthode Element.insertAdjacentText()
• L'interface XMLSerializer : Sérialise un arbre DOM en une chaîne de caractères XML
• L'API Trusted Types