attr()

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

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

Die Parameter sind:

<attr-name>

Der Attributname, dessen Wert von dem ausgewählten HTML-Element abgerufen werden soll.

<attr-type>

Gibt an, wie der Attributswert in einen CSS-Wert geparst werden soll. Dies kann das Schlüsselwort raw-string, eine type()-Funktion oder eine CSS-Dimensionseinheit (angegeben mit einem <attr-unit>-Bezeichner) sein. Wird dieser Parameter weggelassen, ist die Standardeinstellung raw-string.

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

  css

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

  Hinweis: Dieses Schlüsselwort wurde ursprünglich und in Chromium-Browsern als string unterstützt. Beide Schlüsselwörter werden kurzzeitig unterstützt, um die Rückwärtskompatibilität zu gewährleisten.

• 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 zu akzeptieren, listen Sie alle erlaubten <syntax>es in der type()-Funktion durch ein | getrennt auf.

  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 dennoch das CSS-Parsen aus, ohne Anforderungen daran abzuleiten, außer dass es gültig geparst wird und das Ergebnis dieses Parsens direkt als Token substituiert wird, anstatt als <string>-Wert.

  css

  attr(data-content type(*))
  

• Der <attr-unit>-Bezeichner gibt die Einheit an, die ein numerischer Wert haben soll (falls vorhanden). Es kann das %-Zeichen (Prozent) oder eine CSS-Distanzeinheit wie px, rem, deg, s etc. 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> ist, geparst als der angegebene <attr-type> oder als CSS-String.

Wenn ein <attr-type> festgelegt ist, versucht attr(), das Attribut in diesen angegebenen <attr-type> zu parsen und es 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> festgelegt ist, wird das Attribut als CSS-String geparst.

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.

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

<!-- This won't work! -->
<span data-icon="https://example.org/icons/question-mark.svg">help</span>

span[data-icon] {
  background-image: url(attr(data-icon));
}

Werte, die attr() verwenden, werden als attr()-gezeichnet markiert. Wenn ein attr()-gezeichneter Wert als <url> verwendet wird, wird die Deklaration als "invalid at computed value time" oder IACVT abgekürzt ungültig.

Im Allgemeinen ist die moderne attr()-Syntax rückwärtskompatibel, da die alte Art ihrer Verwendung — ohne Angabe eines <attr-type> — sich genauso verhält wie zuvor. Wenn Sie attr(data-attr) in Ihrem Code haben, entspricht das dem Schreiben von attr(data-attr type(<string>)) oder dem einfacheren attr(data-attr string)).

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

Im folgenden Codeausschnitt werden Browser, die die moderne attr()-Syntax nicht unterstützen, die zweite Deklaration verwerfen, da sie diese 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ültiger Inhalt für die content-Eigenschaft ist, wird die Deklaration als "invalid at computed value time" oder IACVT abgekürzt ungültig.

Um solche Situationen zu vermeiden, wird die Funktionsüberprüfung empfohlen.

Ein zweiter Grenzfall 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 computed value time 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 dazu führt, dass eine content: ;-Deklaration gesetzt wird.

Um solche Situationen zu vermeiden, übergeben Sie keine geerbten attr()-Werte an Kinder, es sei denn, Sie möchten dies explizit.

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

Beispielsweise:

@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 die gleiche Überprüfung 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 stellen wir den Wert des data-foo-data-*global attribute vor den Inhalt des <p>-Elements.

HTML

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

CSS

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

Ergebnis

In diesem Beispiel hängen wir den Wert des data-browser-data-*global attribute an das <p>-Element an. 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-*global attribute, das dem <div>-Element zugewiesen wurde.

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 von view-transition-name als Wert akzeptiert wird.

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

HTML

Das HTML enthält vier Karten mit verschiedenen id-Attributen und einen "Shuffle cards" <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 angeordnet:

.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 wird mit der attr()-Funktion das id-Attribut abgerufen und in ein <custom-ident> geparst, das als Wert für die view-transition-name-Eigenschaft verwendet wird. Wenn auf einer Karte kein 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 mit Verweisen auf alle Karten zufällig geändert wird und anschließend die order-Eigenschaft jeder Karte auf ihre neue Array-Indexposition aktualisiert wird.

Um jede Karte zu ihrer neuen Position zu animieren, werden Ansichtsübergänge verwendet. Dies geschieht, indem das order-Update in einem Aufruf von document.startViewTransition eingeschlossen wird.

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