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 vom ausgewählten HTML-Element (oder den Elementen) abgerufen werden soll.

<attr-type>

Gibt an, wie der Attributwert in einen CSS-Wert geparst wird. Dies kann das Schlüsselwort raw-string, eine type() Funktion oder eine CSS-Dimensionseinheit sein (angegeben mit einem <attr-unit> Bezeichner). Wird dies weggelassen, standardisiert es auf raw-string.

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

  cssCopy to Clipboard

  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 für eine kurze Zeit aus Gründen der Abwärtskompatibilität unterstützt.

• Die type() Funktion nimmt ein <syntax> als Argument, das angibt, zu welchem 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.

  cssCopy to Clipboard

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

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

  cssCopy to Clipboard

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

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

  Um jeden Datentyp zu akzeptieren, verwenden Sie * als Typ. Dies löst immer noch eine CSS-Analyse aus, jedoch ohne weitere Anforderungen, außer dass es gültig analysiert und das Ergebnis dieser Analyse direkt als Token ersetzt, anstelle eines <string> Wertes.

  cssCopy to Clipboard

  attr(data-content type(*))
  

• Der <attr-unit> Bezeichner gibt die Einheit an, die ein numerischer Wert haben sollte (falls vorhanden). Es kann sich um das %-Zeichen (Prozentsatz) oder eine CSS-Längeneinheit wie px, rem, deg, s, usw. handeln.

  cssCopy to Clipboard

  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 als CSS-String geparst.

Wenn ein <attr-type> festgelegt ist, versucht attr(), das Attribut in den angegebenen <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> festgelegt ist, wird das Attribut in einen CSS-String geparst.

Wenn kein <fallback-value> festgelegt ist, wird der Rückgabewert standardmäßig auf einen leeren String gesetzt, wenn kein <attr-type> festgelegt ist, oder den garantiert ungültigen Wert, wenn ein <attr-type> festgelegt ist.

Die attr() Funktion kann auf Attribute verweisen, die ursprünglich vom Seitenautor nicht für das Styling vorgesehen waren und möglicherweise vertrauliche Informationen enthalten (zum Beispiel ein von Skripten auf der Seite verwendetes Sicherheitstoken). Im Allgemeinen ist dies unbedenklich, kann jedoch zu einem Sicherheitsrisiko werden, wenn es in URLs verwendet wird. Daher können Sie attr() nicht verwenden, um URLs dynamisch zu konstruieren.

<!-- 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()-belastet markiert. Die Verwendung eines attr()-belasteten Wertes als oder in einer <url> macht eine Deklaration "invalid at computed value time" oder IACVT für kurz.

Im Allgemeinen ist die moderne attr()-Syntax abwärtskompatibel, da die alte Methode ohne Angabe eines <attr-type> das gleiche Verhalten wie zuvor beibehält. Die Form attr(data-attr) in Ihrem Code ist gleichbedeutend mit attr(data-attr type(<string>)) oder der einfacheren Variante attr(data-attr string).

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

Im folgenden Snippet verwerfen Browser, die die moderne attr() Syntax nicht unterstützen, die zweite Deklaration, 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. Diese Browser analysieren die zweite Deklaration erfolgreich, aber da es für die content Eigenschaft ein ungültiger Inhalt ist, wird die Deklaration "invalid at computed value time" oder IACVT für kurz.

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

Ein zweiter Sonderfall 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 moderne Syntax zeigen den Text "foo". 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 des Wertes 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, ü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 mit der @supports At-Regel erkennen. Im Test versuchen Sie, eine fortgeschrittene 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 den gleichen 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 das data-browser data-* globale Attribut zum <p> Element hinzu. Wenn das data-browser Attribut beim <p> Element fehlt, fügen wir den Fallback-Wert "Unbekannt" 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 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 unterschiedlichen id Attributen und ein "Shuffle cards" <button>, welches 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;
  }
}

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

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

JavaScript

Wenn das <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 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 geschieht, indem die order-Aktualisierung in einen Aufruf von document.startViewTransition eingebettet 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