attr()

Die Syntax der attr()-Funktion lautet wie folgt:

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

Die Parameter sind:

<attr-name>

Der Name des Attributs, dessen Wert vom ausgewählten HTML-Element (den ausgewählten HTML-Elementen) abgerufen werden soll.

<attr-type>

Gibt an, wie der Attributwert in einen CSS-Wert geparst wird. Dies kann das Schlüsselwort string, eine type()-Funktion oder eine CSS-Dimensionseinheit sein. Wenn es weggelassen wird, ist der Standardwert string.

• Das Schlüsselwort string parst den Wert in einen CSS-String.

  css

  attr(data-name string, "stranger")
  

• Die type()-Funktion nimmt ein <syntax> als Argument, das angibt, in welchen Datentyp der Wert geparst 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 zuzulassen, listen Sie alle erlaubten <syntax>-Elemente in der type()-Funktion, getrennt durch ein |, auf.

  css

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

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

• Der <attr-unit>-Bezeichner gibt die Einheit an, die ein numerischer Wert haben soll (falls vorhanden). Es kann das %-Zeichen (Prozentsatz) oder eine CSS-Abstandseinheit wie px, rem, deg, s usw. sein.

  css

  attr(data-size rem)
  attr(data-width px, inherit)
  attr(data-rotation deg)
  

<fallback-value>

Der Wert, der verwendet werden soll, wenn das angegebene Attribut fehlt oder einen ungültigen Wert enthält.

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

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

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

Die attr()-Funktion kann auf Attribute verweisen, die vom Seitenautor niemals für Styling-Zwecke vorgesehen waren und möglicherweise sensible Informationen enthalten (zum Beispiel ein Sicherheitstoken, das von Skripten auf der Seite verwendet wird). Im Allgemeinen ist das in Ordnung, aber es kann zu einem Sicherheitsrisiko werden, wenn es in URLs verwendet wird. Daher können Sie attr() nicht verwenden, um URLs dynamisch zu erstellen.

<!-- 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()-belastet" markiert. Die Verwendung eines attr()-belasteten Wertes als oder in einem <url> führt dazu, dass eine Deklaration "ungültig zur Zeit der berechneten Werte" oder kurz IACVT wird.

Generell gilt, dass die moderne attr()-Syntax rückwärtskompatibel ist, weil die alte Art der Verwendung — ohne Angabe eines <attr-type> — sich wie zuvor verhält. Wenn Sie attr(data-attr) in Ihrem Code haben, ist das dasselbe wie attr(data-attr type(<string>)) oder das einfachere 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 Ausschnitt werden Browser, die die moderne attr()-Syntax nicht unterstützen, die zweite Deklaration verwerfen, weil sie sie nicht parsen können. Das Ergebnis in diesen Browsern ist "Hello World".

<div text="Hello"></div>

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 werden die zweite Deklaration erfolgreich parsen, aber da sie ungültigen Inhalt für die content-Eigenschaft darstellt, wird die Deklaration "ungültig zur Zeit der berechneten Werte" oder kurz IACVT.

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

Ein zweiter Randfall ist der folgende:

<div id="parent"><div id="child" data-attr="foo"></div></div>

#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 — zum Zeitpunkt der berechneten Werte ersetzt wird. 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, sollten Sie keine geerbten attr()-Werte auf Kinder übertragen, es sei denn, Sie möchten dies ausdrücklich.

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

Zum Beispiel:

@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:

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 */
}

<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  

In diesem Beispiel fügen wir den Wert des data-foo data-* globalen Attributs dem Inhalt des <p>-Elements voran.

HTML

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

CSS

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

Ergebnis

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

HTML

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

CSS

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

Ergebnis

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

HTML

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

CSS

.background {
  height: 100vh;
}

.background {
  background-color: red;
}

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

Ergebnis

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

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

body {
  min-height: 100svh;
  display: grid;
  place-content: center;
  gap: 1em;
}
div {
  margin: 0 auto;
  border: 1px solid;
  border-radius: 0.25em;
  padding: 0.5em;
}

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

Ergebnis

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> geparst, das ist, 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 "Karten mischen"-<button>, der die Karten mischt.

<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>

<div class="warning">
  <p>
    You browser does not support advanced <code>attr()</code>. As a result, this
    demo won’t do anything.
  </p>
</div>

CSS

Die Karten sind in einem Flex-Container layoutet:

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

:root {
  view-transition-name: none;
}
::view-transition {
  pointer-events: none;
}

@supports (x: attr(x type(*))) {
  .warning {
    display: none;
  }
}

@layer layout {
  .card {
    border-radius: 0.25em;
    width: 20vw;
    max-width: 5em;
    aspect-ratio: 1 / 1.6;
    background: lightgrey;

    display: grid;
    place-content: center;
    font-size: 2em;
  }

  * {
    box-sizing: border-box;
  }

  body {
    min-height: 100svh;
    display: grid;
    place-content: center;
  }

  button {
    justify-self: center;
  }
}

@layer warning {
  .warning {
    padding: 1em;
    border: 1px solid #ccc;
    background: rgba(255 255 205 / 0.8);
    text-align: center;
    order: -1;
    margin: 1em;
  }

  .warning > :first-child {
    margin-top: 0;
  }
  .warning > :last-child {
    margin-bottom: 0;
  }
}

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

.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, das Referenzen zu allen Karten enthält, randomisiert und dann die order-Eigenschaft jeder Karte auf ihre neue Array-Indexposition aktualisiert wird.

Um jede Karte zu ihrer neuen Position zu animieren, werden View Transitions verwendet. Dies wird durch das Einwickeln der order-Aktualisierung in einen Aufruf von document.startViewTransition erreicht.

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

• Attributselektoren
• HTML data-* Attribute
• SVG data-* Attribute