Element: setAttribute() Methode

Syntax

setAttribute(name, value)

Parameter

name

Ein String, der den Namen des Attributs angibt, dessen Wert gesetzt werden soll. Der Attributname wird automatisch in Kleinbuchstaben umgewandelt, wenn setAttribute() auf einem HTML-Element in einem HTML-Dokument aufgerufen wird.

value

Ein vertrauenswürdiger Typ oder ein String, der den zuzuweisenden Wert für das Attribut enthält.

Instanzen von vertrauenswürdigen Typen müssen für die folgenden Attribute übergeben werden, wenn Trusted Types erzwungen werden:

• Inhaltsattribute von Ereignishandlern, wie onclick und onload, erfordern ein TrustedScript.
• HTMLIFrameElement.srcdoc erfordert eine TrustedHTML-Instanz.
• HTMLScriptElement.src erfordert eine TrustedScriptURL-Instanz.
• SVGScriptElement.href erfordert eine TrustedScriptURL-Instanz.

Trusted Types werden für andere Attribute nicht erzwungen, sodass ein String oder ein beliebiger Trusted Type übergeben werden kann.

Ein angegebener Nicht-String-Wert wird automatisch in einen String umgewandelt.

Boolesche Attribute gelten als true, wenn sie überhaupt am Element vorhanden sind. Sie sollten value auf den leeren String ("") oder den Namen des Attributs setzen, ohne führende oder nachfolgende Leerzeichen. Siehe das Beispiel unten für eine praktische Demonstration.

Rückgabewert

Keine (undefined).

Ausnahmen

InvalidCharacterError DOMException

Wird ausgelöst, wenn der name-Wert kein gültiger XML-Name ist. Zum Beispiel, wenn er mit einer Zahl, einem Bindestrich oder einem Punkt beginnt oder Zeichen außer alphanumerischen Zeichen, Unterstrichen, Bindestrichen oder Punkten enthält.

TypeError

Wird ausgelöst, wenn value ein String anstelle eines Trusted Type Object übergeben wird (für jene Attribute, die sie erfordern), wenn Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

setAttribute() setzt den Wert eines Attributs am angegebenen Element. Falls das Attribut bereits existiert, wird der Wert aktualisiert; andernfalls wird ein neues Attribut mit dem angegebenen Namen und Wert hinzugefügt.

Um den Wert eines booleschen Attributs, wie disabled, zu setzen, können Sie jeden beliebigen Wert angeben. Es spielt keine Rolle, welchen Wert Sie verwenden; wenn das Attribut vorhanden ist, gilt sein Wert als true. Üblicherweise aktivieren wir boolesche Attribute, indem wir ihren Wert entweder auf den Namen des Attributs oder den leeren String ("") setzen. Das Fehlen eines booleschen Attributs bedeutet, dass sein Wert false ist; Sie müssen Element.removeAttribute() aufrufen, um die Wirkung der Aktivierung eines booleschen Attributs rückgängig zu machen.

Um den aktuellen Wert eines Attributs zu erhalten, verwenden Sie getAttribute(); um ein Attribut zu entfernen, rufen Sie removeAttribute() auf.

Sicherheitsüberlegungen

Einige Attribute können als Vektor für Cross-Site-Scripting (XSS)-Angriffe genutzt werden, bei denen potenziell unsichere Strings von einem Benutzer ohne vorherige Reinigung in das DOM injiziert werden oder Skripte ausgeführt werden, die möglicherweise bösartigen Code enthalten.

Zum Beispiel zeigt der folgende Code, wie ein potenziell nicht vertrauenswürdiger String, der von einem Benutzer bereitgestellt wird, ausgeführt wird, wenn der Button gedrückt wird.

const button = document.querySelector("button");
const potentiallyUnsafeString = "alert(1)";
button.setAttribute("onclick", potentiallyUnsafeString);

Sie könnten in ähnlicher Weise unzuverlässiges HTML in das DOM injizieren, indem Sie das Attribut HTMLIFrameElement.srcdoc setzen oder eine unzuverlässige URL an die Attribute HTMLScriptElement.src oder SVGScriptElement.href übergeben.

Sie können diese Probleme mindern, indem Sie immer das entsprechende Trusted Type Object (TrustedHTML, TrustedScript, oder TrustedScriptURL) für jede Eigenschaft anstelle von Strings zuweisen und Trusted Types durchsetzen mit der require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die beispielsweise potenziell gefährliches Markup aus HTML entfernt, bevor es injiziert wird.

Beispiele

Sichere Attribute setzen

Dieses Beispiel nutzt setAttribute(), um die Attribute name und disabled auf einem <button> zu setzen. Diese Attribute sind beide XSS-sicher. Da ihre Werte weder ausgeführt noch als HTML in das DOM geparst werden, benötigen wir keine Trusted Types zu übergeben.

HTML

<div>
  <button id="reset" type="button">Reset</button>
  <button id="toggle_disabled">Toggle</button>
</div>
<button id="hello_button">Some Text</button>

button {
  height: 30px;
  width: 100px;
  margin: 1em;
}

JavaScript

Zuerst holen wir das Button-Element und setzen sein name-Attribut mit setAttribute() auf "helloButton". Um zu demonstrieren, dass sich der Attributname geändert hat, holen wir dann den Attributtext und zeigen ihn auf dem Button an.

const helloButton = document.querySelector("#hello_button");
helloButton.setAttribute("name", "helloButton");

// Set button text to name to show the attribute changed
helloButton.innerText = helloButton.getAttribute("name");

Dieser Code ist für den Reset-Button. Er lädt einfach den Frame neu.

const reloadButton = document.querySelector("#reset");
reloadButton.addEventListener("click", () => document.location.reload());

Als nächstes zeigen wir, wie man ein boolesches Attribut setzt und zurücksetzt. Wenn der Toggle-Button geklickt wird, prüfen wir, ob die boolesche disabled-Eigenschaft definiert ist (diese Eigenschaft spiegelt das disabled-Attribut wider und ist true, wenn der Button deaktiviert ist, und false sonst). Wenn der Button deaktiviert ist, rufen wir Element.removeAttribute() auf, um das Attribut zu entfernen, was wiederum den Button aktiviert. Wenn der Button aktiviert ist, deaktivieren wir den Button, indem wir das disabled-Attribut auf "disabled" setzen.

const toggleDisabledButton = document.querySelector("#toggle_disabled");

toggleDisabledButton.addEventListener("click", () => {
  if (helloButton.disabled) {
    // Button is disabled. Enable by removing attribute
    helloButton.removeAttribute("disabled");
  } else {
    // Button enabled. Disable by setting value to anything
    // (normally "" or "disabled")
    helloButton.setAttribute("disabled", "disabled");
  }
});

Ergebnisse

Das laufende Beispiel ist unten gezeigt. Sie können sehen, dass der untere Button-Text "helloButton" ist, da wir die Name-Eigenschaft gesetzt und sie dann genutzt haben, um den Button-Text zu setzen. Sie können den "Toggle"-Button drücken, um den "helloButton" zu deaktivieren und zu aktivieren.

Unsichere Attribute setzen

In diesem Beispiel zeigen wir, wie man die Risiken mindern könnte, die auftreten, wenn setAttributes() auf das srcdoc Attribut auf einem <iframe> gesetzt wird. Dieses Attribut setzt das Quell-HTML eines Frames und kann potenziell unzuverlässigen oder unsicheren Code in das DOM injizieren.

Der Ansatz wäre ähnlich, wenn man src auf HTML-Skriptelementen, href auf SVG-Skriptelementen und die onXxxx-Ereignishandler-Attribute setzt: der Hauptunterschied besteht darin, dass man ihnen unterschiedliche Trusted Type Objects übergibt.

Trusted Types werden noch nicht in allen Browsern unterstützt, daher definieren wir zuerst das trusted types tinyfill. Dies fungiert als transparenter Ersatz für die Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Als nächstes erstellen wir eine TrustedTypePolicy, die eine createHTML() definiert, um einen Eingabestring in TrustedHTML-Instanzen zu transformieren. Üblicherweise nutzen Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um die Eingabe zu bereinigen, wie unten gezeigt:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Dann verwenden wir dieses policy-Objekt, um ein TrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen und das Ergebnis dem Element zuzuweisen:

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Inject the TrustedHTML (which contains a trusted string)
const iframeElement = document.querySelector("#an_iframe");
iframeElement.setAttribute("srcdoc", trustedHTML);

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Element.hasAttribute()
• Element.getAttribute()
• Element.removeAttribute()
• Element.toggleAttribute()