Document : méthode writeln()

Syntaxe

writeln(markup)
writeln(markup, markup2)
writeln(markup, markup2, /* …, */ markupN)

Paramètres

markup, …, markupN

Des objets TrustedHTML ou des chaînes de caractères contenant le texte à écrire dans le document.

Valeur de retour

Aucune (undefined).

Exceptions

InvalidStateError DOMException

La méthode a été appelée sur un document XML, ou appelée lorsque le parseur exécute actuellement un constructeur d'élément personnalisé.

TypeError

Une chaîne de caractères est passée comme l'un des paramètres lorsque les types de confiance sont appliqués et qu'aucune politique par défaut n'a été définie pour créer des objets TrustedHTML.

Description

La méthode est essentiellement identique à document.write() mais ajoute une nouvelle ligne (les informations du sujet lié s'appliquent également à cette méthode). Cette nouvelle ligne ne sera visible que si elle est injectée dans un élément où les sauts de ligne sont affichés. Les informations supplémentaires de document.write() s'appliquent également à cette méthode.

Considérations de sécurité

La méthode peut être un vecteur d'attaques inter-site (XSS), où des chaînes potentiellement dangereuses fournies par un·e utilisateur·ice sont injectées dans le DOM sans avoir été préalablement assainies. Alors que la méthode peut empêcher l'exécution des éléments HTML <script> lorsqu'ils sont injectés dans certains navigateurs (voir Intervenir contre document.write() ^(angl.) pour Chrome), elle reste vulnérable à de nombreuses autres manières dont des attaquant·e·s peuvent composer du HTML pour exécuter du JavaScript malveillant.

Vous pouvez atténuer ces problèmes en passant toujours des objets TrustedHTML au lieu de chaînes de caractères, et en appliquant les types de confiance à l'aide de la directive CSP require-trusted-types-for. Cela garantit que l'entrée est passée par une fonction de transformation, qui a la possibilité d'assainir l'entrée pour supprimer les balises potentiellement dangereuses (telles que les éléments HTML <script> et les attributs gestionnaires d'évènements), avant son injection.

Exemples

Écrire du TrustedHTML

Cet exemple utilise l'API des types de confiance pour assainir les chaînes de caractères HTML avant qu'elles ne soient écrites dans un document. Vous devez toujours utiliser les types de confiance pour passer des chaînes de caractères non fiables aux API non sécurisées.

L'exemple affiche initialement un texte par défaut et un bouton. Quand le bouton est cliqué, le document courant est ouvert, certaines chaînes de caractères HTML sont converties en instances de TrustedHTML et écrites dans le document, puis le document est fermé. Cela remplace le document dans le cadre d'exemple, y compris le HTML original du bouton et le JavaScript qui a effectué la mise à jour !

HTML

<p>Contenu original du document.</p>
<button id="remplacer" type="button">Remplacer le contenu du document</button>

JavaScript

D'abord nous utilisons la propriété Window.trustedTypes pour accéder à l'objet global TrustedTypePolicyFactory, et utilisons sa méthode createPolicy() pour définir une politique appelée "docPolicy".

La nouvelle politique définit une fonction de transformation createHTML() pour créer les objets TrustedHTML que nous passerons à la méthode writeln(). Cette méthode peut faire ce qu'elle veut avec la chaîne de caractères d'entrée : l'API des types de confiance exige simplement que vous passiez l'entrée par une fonction de transformation de politique, et non que la fonction de transformation fasse quelque chose de particulier.

Vous utiliseriez la méthode pour assainir l'entrée en supprimant les fonctionnalités potentiellement dangereuses telles que les balises <script> ou les attributs gestionnaires d'événements. L'assainissement est difficile à réaliser correctement, donc ce processus utilise généralement une bibliothèque tierce réputée telle que DOMPurify.

Nous implémentons ici un « assainisseur » rudimentaire qui remplace les symboles < dans les balises script d'ouverture et de fermeture par le caractère <. Les chaînes de caractères injectées dans cet exemple ne contiennent en réalité aucun élément dangereux, il s'agit donc uniquement d'une démonstration.

const policy = trustedTypes.createPolicy("docPolicy", {
  createHTML(string) {
    return string
      .replace("<script", "&lt;script")
      .replace("</script", "&lt;/script");
  },
});

Nous pouvons ensuite utiliser la méthode TrustedTypePolicy.createHTML() sur la politique retournée pour créer des objets TrustedHTML à partir de nos chaînes d'entrée originales. Ceux-ci sont ensuite passés à la fonction writeln() lorsque l'utilisateur·ice clique sur le bouton.

const remplacer = document.querySelector("#remplacer");
const entreeUne = "<h1>Dehors avec";
const entreeDeux = "l'ancien</h1>";
const entreeTrois = "<pre>dedans avec";
const entreeQuatre = "le nouveau !</pre>";

remplacer.addEventListener("click", () => {
  document.open();
  document.writeln(policy.createHTML(entreeUne));
  document.writeln(
    policy.createHTML(entreeDeux),
    policy.createHTML(entreeTrois),
  );
  document.writeln(policy.createHTML(entreeQuatre));
  document.close();
});

Résultats

Cliquez sur le bouton. Notez qu'une nouvelle ligne est ajoutée après chaque appel à writeln(), mais ceci ne sera visible que dans l'élément HTML <pre> car sa mise en page préserve les espaces blancs par défaut.

Spécifications

Compatibilité des navigateurs