attr()

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

We’d love to hear your thoughts on the next set of proposals for the JavaScript language. You can find a description of the proposals here.
Please take two minutes to fill out our short survey.

Hinweis: Die Funktion attr() kann mit jeder CSS-Eigenschaft verwendet werden, aber die Unterstützung für andere Eigenschaften als content ist experimentell.

Die attr() CSS Funktion wird verwendet, um den Wert eines Attributs des ausgewählten Elements abzurufen und ihn in einem Eigenschaftswert zu verwenden, ähnlich wie die var() Funktion einen benutzerdefinierten Eigenschaftswert ersetzt. Sie kann auch mit Pseudo-Elementen verwendet werden, in welchem Fall der Attributwert des Ursprungselements des Pseudo-Elements zurückgegeben wird.

Probieren Sie es aus

blockquote {
  margin: 1em 0;
}

blockquote::after {
  display: block;
  content: " (source: " attr(cite) ") ";
  color: hotpink;
}
<blockquote cite="https://mozilla.org/en-US/about/">
  Mozilla makes browsers, apps, code and tools that put people before profit.
</blockquote>

<blockquote cite="https://web.dev/about/">
  Google believes in an open, accessible, private, and secure web.
</blockquote>

Syntax

css
/* Basic usage */
attr(data-count)
attr(href)

/* With type */
attr(data-width px)
attr(data-size rem)
attr(data-name raw-string)
attr(id type(<custom-ident>))
attr(data-count type(<number>))
attr(data-size type(<length> | <percentage>))

/* With fallback */
attr(data-count type(<number>), 0)
attr(data-width px, inherit)
attr(data-something, "default")

Parameter

Die Syntax der attr() Funktion ist wie folgt:

attr(<attr-name> <attr-type>? , <fallback-value>?)

Die Parameter sind:

<attr-name>

Der Attributname, dessen Wert vom ausgewählten HTML-Element (oder den ausgewählten Elementen) abgerufen werden soll.

<attr-type>

Gibt an, wie der Attributwert in einen CSS-Wert analysiert wird. Dies kann das Schlüsselwort raw-string, eine type() Funktion oder eine CSS-Dimensionseinheit sein (angegeben mit einem <attr-unit> Bezeichner). Wenn weggelassen, ist der Standard raw-string.

  • Das Schlüsselwort raw-string bewirkt, dass der Literalwert des Attributs als Wert eines CSS-Strings behandelt wird, ohne dass eine CSS-Analyse durchgeführt wird (einschließlich CSS-Escapes, Leerzeichenentfernung, Kommentare, usw.). Der <fallback-value> wird nur verwendet, wenn das Attribut fehlt; das Angeben eines leeren Werts löst den Fallback nicht aus.

    css
    attr(data-name raw-string, "stranger")
    

    Hinweis: Dieses Schlüsselwort wurde ursprünglich in Chromium-Browsern als string benannt und unterstützt. Beide Schlüsselwörter werden vorübergehend für Rückwärtskompatibilität unterstützt.

  • Die type() Funktion nimmt ein <syntax> als Argument, das angibt, in welchen Datentyp der Wert analysiert werden soll. Das <syntax> kann <angle>, <color>, <custom-ident>, <image>, <integer>, <length>, <length-percentage>, <number>, <percentage>, <resolution>, <string>, <time>, <transform-function> oder eine Kombination davon sein.

    css
    attr(id type(<custom-ident>), none)
    attr(data-count type(<number>), 0)
    

    Um mehrere Typen zu akzeptieren, listen Sie alle zulässigen <syntax> in der type() Funktion, getrennt durch ein |.

    css
    attr(data-size type(<length> | <percentage>), 0px)
    

    Hinweis: Aus Sicherheitsgründen ist <url> nicht als <syntax> erlaubt.

    Um jeden Datentyp zu akzeptieren, verwenden Sie * als Typ. Dies löst immer noch eine CSS-Analyse aus, jedoch ohne Anforderungen darüber hinaus, dass es gültig analysiert wird und das Ergebnis dieser Analyse direkt als Token ersetzt, anstatt als <string> Wert.

    css
    attr(data-content type(*))
    
  • Der <attr-unit> Bezeichner gibt die Einheit an, die ein numerischer Wert haben sollte (falls vorhanden). Dies kann das Zeichen % (Prozentsatz) oder eine CSS-Distanzeinheit wie px, rem, deg, s, usw. sein.

    css
    attr(data-size rem)
    attr(data-width px, inherit)
    attr(data-rotation deg)
    
<fallback-value>

Der zu verwendende Wert, wenn das angegebene Attribut fehlt oder einen ungültigen Wert enthält.

Rückgabewert

Der Rückgabewert der attr() Funktion ist der Wert des HTML-Attributs, dessen Name <attr-name> ist, analysiert als der angegebene <attr-type> oder als CSS-String analysiert.

Wenn ein <attr-type> gesetzt ist, wird attr() versuchen, das Attribut in diesen <attr-type> zu analysieren und zurückzugeben. Kann das Attribut nicht in den angegebenen <attr-type> analysiert werden, wird stattdessen der <fallback-value> zurückgegeben. Wenn kein <attr-type> gesetzt ist, wird das Attribut in einen CSS-String analysiert.

Wenn kein <fallback-value> gesetzt ist, wird der Rückgabewert standardmäßig ein leerer String sein, wenn kein <attr-type> gesetzt ist, oder der garantiert ungültige Wert, wenn ein <attr-type> gesetzt ist.

Beschreibung

Einschränkungen und Sicherheit

Die attr() Funktion kann auf Attribute verweisen, die vom Autor der Seite nie zur Stilisierung vorgesehen waren und möglicherweise sensible Informationen enthalten (z. B. ein Sicherheitstoken, das von Skripten auf der Seite verwendet wird). Im Allgemeinen ist das in Ordnung, kann jedoch zu einer Sicherheitsbedrohung werden, wenn es in URLs verwendet wird. Daher können Sie attr() nicht verwenden, um URLs dynamisch zu erstellen.

html
<!-- This won't work! -->
<span data-icon="https://example.org/icons/question-mark.svg">help</span>
<style>
  span[data-icon] {
    background-image: url(attr(data-icon));
  }
</style>

Werte, die attr() verwenden, werden als attr()-kontaminiert markiert. Die Verwendung eines attr()-kontaminierten Werts als oder in einem <url> macht eine Deklaration „ungültig zur Berechnungszeit“ oder kurz IACVT.

Rückwärtskompatibilität

Im Allgemeinen ist die moderne attr() Syntax rückwärtskompatibel, da die alte Verwendungsmethode – ohne Angeben eines <attr-type> – sich genauso verhält wie zuvor. attr(data-attr) in Ihrem Code zu haben, entspricht dem Schreiben von attr(data-attr type(<string>)) oder dem einfacheren attr(data-attr string).

Es gibt jedoch zwei Randfälle, in denen sich die moderne attr()-Syntax anders verhält als die alte Syntax.

Im folgenden Abschnitt ignorieren Browser, die die moderne attr()-Syntax nicht unterstützen, die zweite Deklaration, da sie diese nicht analysieren können. Das Ergebnis in diesen Browsern ist "Hello World".

html
<div text="Hello"></div>
css
div::before {
  content: attr(text) " World";
}
div::before {
  content: attr(text) 1px;
}

In Browsern mit Unterstützung für die moderne Syntax wird die Ausgabe ... nichts sein. Diese Browser analysieren die zweite Deklaration erfolgreich, aber da dies ein ungültiger Inhalt für die content-Eigenschaft ist, wird die Deklaration „ungültig zur Berechnungszeit“ oder kurz IACVT.

Um solche Situationen zu vermeiden, wird Feature-Erkennung empfohlen.

Ein zweiter Randfall ist folgender:

html
<div id="parent"><div id="child" data-attr="foo"></div></div>
css
#parent {
  --x: attr(data-attr);
}
#child::before {
  content: var(--x);
}

Browser ohne Unterstützung für die moderne Syntax zeigen den Text "foo" an. In Browsern mit moderner attr()-Unterstützung gibt es keine Ausgabe.

Dies liegt daran, dass attr() – ähnlich wie benutzerdefinierte Eigenschaften, die die var() Funktion verwenden – zur Berechnungszeit der Werte ersetzt werden. Mit dem modernen Verhalten versucht --x zuerst, das data-attr-Attribut vom #parent-Element zu lesen, was zu einem leeren String führt, da es kein solches Attribut auf #parent gibt. Dieser leere String wird dann vom #child-Element geerbt, was zu einer content: ; Deklaration führt.

Um solche Situationen zu vermeiden, geben Sie geerbte attr()-Werte nicht an Kind-Elemente weiter, es sei denn, Sie möchten dies ausdrücklich.

Feature-Erkennung

Sie können die Unterstützung für die moderne attr()-Syntax mit der @supports At-Regel erkennen. Im Test versuchen Sie, eine erweiterte attr() zu einer (nicht benutzerdefinierten) CSS-Eigenschaft zuzuweisen.

Zum Beispiel:

css
@supports (x: attr(x type(*))) {
  /* Browser has modern attr() support */
}

@supports not (x: attr(x type(*))) {
  /* Browser does not have modern attr() support */
}

Wir können denselben Test in JavaScript mit CSS.supports() durchführen:

js
if (CSS.supports("x: attr(x type(*))")) {
  /* Browser has modern attr() support */
}

if (!CSS.supports("x: attr(x type(*))")) {
  /* Browser does not have modern attr() support */
}

Formale Syntax

<attr()> = 
attr( <attr-name> <attr-type>? , <declaration-value>? )

<attr-name> =
[ <ident-token>? '|' ]? <ident-token>

<attr-type> =
type( <syntax> ) |
raw-string |
<attr-unit>

<syntax> =
'*' |
<syntax-component> [ <syntax-combinator> <syntax-component> ]* |
<syntax-string>

<syntax-component> =
<syntax-single-component> <syntax-multiplier>? |
'<' transform-list '>'

<syntax-combinator> =
'|'

<syntax-string> =
<string>

<syntax-single-component> =
'<' <syntax-type-name> '>' |
<ident>

<syntax-multiplier> =
'#' |
'+'

<syntax-type-name> =
angle |
color |
custom-ident |
image |
integer |
length |
length-percentage |
number |
percentage |
resolution |
string |
time |
url |
transform-function

Beispiele

content-Eigenschaft

In diesem Beispiel fügen wir den Wert des data-foo data-* globales Attribut zu den Inhalten des <p> Elements hinzu.

HTML

html
<p data-foo="hello">world</p>

CSS

css
[data-foo]::before {
  content: attr(data-foo) " ";
}

Ergebnis

Verwendung eines Fallback-Werts

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

In diesem Beispiel fügen wir den Wert des data-browser data-* globales Attribut zum <p> Element hinzu. Wenn das data-browser-Attribut auf dem <p> Element fehlt, fügen wir den Fallback-Wert "Unknown" hinzu.

HTML

html
<p data-browser="Firefox">My favorite browser is:</p>
<p>Your favorite browser is:</p>

CSS

css
p::after {
  content: " " attr(data-browser, "Unknown");
  color: tomato;
}

Ergebnis

Farbwert

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

In diesem Beispiel setzen wir den CSS-Wert von background-color auf den Wert des data-background data-* globales Attribut, das dem <div> Element zugewiesen ist.

HTML

html
<div class="background" data-background="lime">
  background expected to be red if your browser does not support advanced usage
  of attr()
</div>

CSS

css
.background {
  background-color: red;
}

.background[data-background] {
  background-color: attr(data-background type(<color>), red);
}

Ergebnis

Verwendung von Dimensionseinheiten

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

In diesem Beispiel wird das data-rotation-Attribut in eine deg-Einheit analysiert, die die Drehung des Elements angibt.

HTML

html
<div data-rotation="-3">I am rotated by -3 degrees</div>
<div data-rotation="2">And I by 2 degrees</div>
<div>And so am I, using the fallback value of 1.5deg</div>

CSS

css
div {
  width: fit-content;
  transform-origin: 50% 50%;
  rotate: attr(data-rotation deg, 1.5deg);
}

Ergebnis

Parsing von attr()-Werten als <custom-ident>s

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

In diesem Beispiel werden die Werte für die view-transition-name Eigenschaft aus dem id Attribut des Elements abgeleitet. Das Attribut wird in ein <custom-ident> analysiert, was view-transition-name als Wert akzeptiert.

Die resultierenden Werte für view-transition-name sind card-1, card-2, card-3, usw.

HTML

Das HTML enthält vier Karten mit unterschiedlichen id-Attributen und einen "Shuffle cards" <button>, der die Karten mischt.

html
<div class="cards">
  <div class="card" id="card-1">1</div>
  <div class="card" id="card-2">2</div>
  <div class="card" id="card-3">3</div>
  <div class="card" id="card-4">4</div>
</div>
<button>Shuffle cards</button>

CSS

Die Karten sind in einem Flex-Container angeordnet:

css
.cards {
  display: flex;
  flex-direction: row;
  gap: 1em;
  padding: 1em;
}

Auf jeder Karte holt die attr() Funktion das id-Attribut und analysiert es in ein <custom-ident>, das als Wert für die view-transition-name Eigenschaft verwendet wird. Wenn auf einer Karte kein id gesetzt ist, wird der Fallback-Wert none stattdessen verwendet.

css
.card {
  view-transition-name: attr(id type(<custom-ident>), none);
  view-transition-class: card;
}

JavaScript

Wenn der <button> gedrückt wird, werden die Karten gemischt. Dies geschieht, indem die Reihenfolge eines Arrays mit Referenzen zu allen Karten randomisiert und dann die order Eigenschaft jeder Karte auf ihre neue Array-Indexposition aktualisiert wird.

Um jede Karte in ihre neue Position zu animieren, werden View Transitions verwendet. Dies geschieht, indem das order-Update in einem Aufruf von document.startViewTransition eingeschlossen wird.

js
const shuffle = (array) => {
  for (let i = array.length - 1; i >= 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [array[i], array[j]] = [array[j], array[i]];
  }
};

document.querySelector("button").addEventListener("click", (e) => {
  const $cards = Array.from(document.querySelectorAll(".card"));
  shuffle($cards);
  document.startViewTransition(() => {
    $cards.forEach(($card, i) => {
      $card.style.setProperty("order", i);
    });
  });
});

Ergebnis

Spezifikationen

Specification
CSS Values and Units Module Level 5
# attr-notation

Browser-Kompatibilität

Siehe auch