Element : méthode setAttribute()

Baseline

Large disponibilité

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.

Voir la compatibilité complète
En savoir plus

Attention : Cette méthode peut prendre des valeurs d'attribut qui sont analysées comme du HTML, un script ou une URL de script, selon l'attribut. Les API de ce type sont connues sous le nom de points d'injection et peuvent potentiellement être un vecteur pour des attaques de script inter-site (XSS), si la valeur provient initialement d'un·e attaquant·e.

Vous pouvez atténuer ce risque en passant toujours l'objet de type de confiance approprié (TrustedHTML, TrustedScript ou TrustedScriptURL) au lieu de chaînes de caractères pour les attributs qui les nécessitent, et en appliquant les types de confiance. Voir Considérations de sécurité pour plus d'informations.

La méthode setAttribute() de l'interface Element définit la valeur d'un attribut sur l'élément défini. Si l'attribut existe déjà, sa valeur est mise à jour ; sinon, un nouvel attribut est ajouté avec le nom et la valeur définis.

Si vous devez travailler avec le nœud Attr (par exemple en le clonant à partir d'un autre élément) avant de l'ajouter, vous pouvez utiliser la méthode setAttributeNode() à la place.

Syntaxe

setAttribute(qualifiedName, value)

Paramètres

qualifiedName

Une chaîne de caractères contenant le nom qualifié de l'attribut dont la valeur doit être définie. Le nom de l'attribut est automatiquement converti en minuscules lorsque setAttribute() est appelée sur un élément HTML dans un document HTML.

Le format du nom qualifié est prefix:localName ou localName, où les parties sont définies comme suit :

prefix Facultatif: Un « alias court » pour l'espace de noms, tel que retourné par la propriété prefix.
localName: Le nom local de l'attribut, tel que retourné par la propriété localName.

value

Un type de confiance ou une chaîne de caractères contenant la valeur à attribuer à l'attribut.

Des instances de type de confiance doivent être passées pour les attributs suivants lorsque les types de confiance sont appliqués :

Les attributs de contenu des gestionnaires d'évènements, tels que onclick et onload, nécessitent un TrustedScript.
HTMLIFrameElement.srcdoc nécessite une instance de TrustedHTML.
HTMLScriptElement.src nécessite une instance de TrustedScriptURL.
SVGScriptElement.href nécessite une instance de TrustedScriptURL.

Les types de confiance ne sont pas appliqués pour les autres attributs, donc une chaîne de caractères ou tout type de confiance peut être passé.

Une valeur qui n'est pas une chaîne de caractères définie est automatiquement convertie en chaîne de caractères.

Les attributs booléens sont considérés comme true s'ils sont présents sur l'élément. Vous devez définir value sur la chaîne de caractères vide ("") ou sur le nom de l'attribut, sans espace blanc au début ou à la fin. Voir l'exemple ci-dessous pour une démonstration pratique.

Valeur de retour

Aucune (undefined).

Exceptions

InvalidCharacterError DOMException

Levée si l'un des prefix ou localName n'est pas valide :

Le prefix doit comporter au moins un caractère et ne peut pas contenir d'espaces ASCII, NULL, / ou > (U+0000, U+002F ou U+003E, respectivement).
Le localName doit comporter au moins un caractère et ne peut pas contenir d'espaces ASCII, NULL, /, = ou > (U+0000, U+002F, U+003D ou U+003E, respectivement).

Note : Les versions antérieures de la spécification étaient plus restrictives et exigeaient que le qualifiedName soit un nom XML ^(angl.) valide.

TypeError

Levée si value est une chaîne de caractères au lieu d'un objet de type de confiance (pour les attributs qui les nécessitent) lorsque les Trusted Types sont appliqués par une CSP et qu'aucune politique par défaut n'est définie.

Description

setAttribute() définit la valeur d'un attribut sur l'élément défini. Si l'attribut existe déjà, sa valeur est mise à jour ; sinon, un nouvel attribut est ajouté avec le nom et la valeur définis.

Pour définir la valeur d'un attribut booléen, tel que disabled, vous pouvez définir n'importe quelle valeur. Peu importe la valeur que vous utilisez ; si l'attribut est présent, sa valeur est considérée comme true. Par convention, nous activons les attributs booléens en définissant leur valeur sur le nom de l'attribut ou sur la chaîne de caractères vide (""). L'absence d'un attribut booléen signifie que sa valeur est false ; vous devez appeler Element.removeAttribute() pour « annuler » l'effet de l'activation d'un attribut booléen.

Pour obtenir la valeur actuelle d'un attribut, utilisez