TrustedTypePolicyFactory.getPropertyType() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.getPropertyType(tagName, property, elementNs)

Beschreibung

Mit getPropertyType() fragst du die Trusted-Types-API, ob eine bestimmte JavaScript-Eigenschaft eines Elements eine sogenannte Injection Sink ist, also einen Trusted-Type-Wert erwartet. Beispiele sind innerHTML eines <div> oder src eines <script>. Die Methode wird über die globale Factory trustedTypes aufgerufen, also window.trustedTypes oder self.trustedTypes in Workern.

Als Ergebnis bekommst du den Namen des benötigten Typs als String: "TrustedHTML", "TrustedScript" oder "TrustedScriptURL". Ist die Eigenschaft kein Sink, gibt die Methode null zurück. Das hilft vor allem Frameworks, Template-Engines und Sanitizer-Bibliotheken: Sie können Werte vor dem Zuweisen gezielt durch die passende Methode einer TrustedTypePolicy schicken (createHTML(), createScript() oder createScriptURL()), ohne selbst eine Liste aller Sinks pflegen zu müssen.

Die Methode ist das Gegenstück zu getAttributeType(). Sie prüft Eigenschaften (el.innerHTML = …), während getAttributeType() Attribute prüft (el.setAttribute("src", …)). Die Antwort hängt nur von Element und Eigenschaft ab. Ob Trusted Types per CSP (require-trusted-types-for 'script') tatsächlich durchgesetzt werden, spielt dafür keine Rolle.

Parameter

Name	Typ	Default	Beschreibung
$tagName Pflicht	string		Tag-Name des Elements, z. B. `"div"`, `"script"` oder `"iframe"`. Groß- und Kleinschreibung spielt keine Rolle, der Name wird intern in Kleinbuchstaben umgewandelt.
$property Pflicht	string		Name der DOM-Eigenschaft, z. B. `"innerHTML"`, `"src"` oder `"textContent"`. Hier zählt die Groß- und Kleinschreibung (`"innerhtml"` ergibt `null`).
$elementNs	string	"http://www.w3.org/1999/xhtml"	Namensraum des Elements. Ohne Angabe gilt der HTML-Namensraum. Für SVG-Elemente gibst du `"http://www.w3.org/2000/svg"` an.

Rückgabewert

Typ

string | null

Beschreibung

"TrustedHTML", "TrustedScript" oder "TrustedScriptURL", wenn die Eigenschaft einen Trusted Type verlangt. Sonst null.

Beispiele

Einzelne Eigenschaften abfragen

if (window.trustedTypes) {
  console.log(trustedTypes.getPropertyType("div", "innerHTML"));
  console.log(trustedTypes.getPropertyType("script", "src"));
  console.log(trustedTypes.getPropertyType("script", "text"));
  console.log(trustedTypes.getPropertyType("div", "textContent"));
  console.log(trustedTypes.getPropertyType("div", "innerhtml")); // falsche Schreibweise
}

TrustedHTML TrustedScriptURL TrustedScript null null

Generischer Setter, der Werte automatisch über eine Policy absichert

// Policy mit sehr einfachen Regeln (nur zur Demonstration)
const policy = trustedTypes.createPolicy("app-default", {
  createHTML: (s) => s.replace(/</g, "&lt;"),
  createScript: () => { throw new TypeError("Inline-Skripte verboten"); },
  createScriptURL: (s) => {
    const url = new URL(s, location.href);
    if (url.origin !== location.origin) throw new TypeError(`Fremde URL: ${url}`);
    return url.href;
  }
});

const creators = {
  TrustedHTML: (v) => policy.createHTML(v),
  TrustedScript: (v) => policy.createScript(v),
  TrustedScriptURL: (v) => policy.createScriptURL(v)
};

const safeSet = (el, prop, value) => {
  const type = trustedTypes.getPropertyType(el.localName, prop, el.namespaceURI);
  el[prop] = type ? creators[type](value) : value;
  return type;
};

const box = document.createElement("div");
console.log(safeSet(box, "innerHTML", "<b>Hallo</b>"));
console.log(box.textContent);
console.log(safeSet(box, "title", "Tooltip"));

TrustedHTML <b>Hallo</b> null

Mit Feature-Erkennung auf Browser ohne Trusted Types zurückfallen

const requiredType = (tag, prop) =>
  globalThis.trustedTypes?.getPropertyType(tag, prop) ?? null;

const sinks = [
  ["iframe", "srcdoc"],
  ["embed", "src"],
  ["img", "src"]
];

for (const [tag, prop] of sinks) {
  console.log(`${tag}.${prop}:`, requiredType(tag, prop));
}

iframe.srcdoc: TrustedHTML embed.src: TrustedScriptURL img.src: null

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die Methode seit Version 83. In Firefox und Safari gibt es Trusted Types erst in neueren Versionen. Prüfe deshalb vorher mit window.trustedTypes oder globalThis.trustedTypes?., ob die API da ist. Für ältere Browser gibt es einen Polyfill (trusted-types auf npm).
Eigenschaft oder Attribut: getPropertyType(\"script\", \"src\") gilt nur für die Zuweisung script.src = …. Für setAttribute() nimmst du getAttributeType(). Die Namen können sich unterscheiden, etwa beim Attribut srcdoc und bei Eigenschaften wie innerHTML, zu denen es kein Attribut gibt.
Groß- und Kleinschreibung: Beim Tag-Namen ist sie egal, beim Eigenschaftsnamen nicht. Falsch geschriebene Eigenschaften ergeben still null. Das kann fälschlich den Eindruck erwecken, die Eigenschaft sei kein Sink.
Keine Sicherheitsgarantie: null heißt nur, dass Trusted Types diese Eigenschaft nicht erzwingt. Es heißt nicht, dass beliebige Werte unbedenklich sind, zum Beispiel javascript:-URLs in a.href. Eine gute Policy und ein Sanitizer (z. B. DOMPurify) bleiben nötig.
Die Methode liefert auch dann Ergebnisse, wenn keine CSP-Direktive require-trusted-types-for aktiv ist.

Siehe auch

TrustedTypePolicyFactory.getAttributeType() TrustedTypePolicyFactory.isScript() TrustedTypePolicyFactory.isScriptURL() TrustedTypePolicyFactory.createPolicy() TrustedTypePolicyFactory.isHTML()