attr()

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

/* 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 Name des Attributs, dessen Wert von dem ausgewählten HTML-Element oder den ausgewählten HTML-Elementen abgerufen werden soll.

<attr-type>

Gibt an, wie der Attributswert in einen CSS-Wert geparst wird. Dies kann das Schlüsselwort raw-string, eine type()-Funktion oder eine CSS-Dimensionseinheit sein (spezifiziert durch ein <attr-unit>-Identifier). Wenn weggelassen, ist raw-string der Standardwert.

raw-string

Das Schlüsselwort raw-string bewirkt, dass der wörtliche Wert des Attributs als Wert eines CSS-Strings behandelt wird, ohne dass eine CSS-Parsing durchgeführt wird (einschließlich CSS-Escapes, Leerzeichen-Entfernung, Kommentare usw.). Der <fallback-value> wird nur verwendet, wenn das Attribut fehlt; die Angabe eines leeren Wertes 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 bereitgestellt und unterstützt. Beide Schlüsselwörter werden vorübergehend unterstützt, um die Rückwärtskompatibilität zu gewährleisten.

type()

Die type()-Funktion nimmt ein <syntax> als Argument, das den Datentyp angibt, in den der Wert geparst werden soll.

Hinweis: Aus Sicherheitsgründen ist <url> als attr()-Datentyp nicht erlaubt.

<attr-unit>

Der <attr-unit>-Identifier gibt an, welche Einheit ein numerischer Wert haben soll (falls vorhanden). Es kann das %-Zeichen (Prozent) 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.

Rückgabewert

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

Wenn ein <attr-type> festgelegt ist, versucht attr(), das Attribut in den angegebenen <attr-type> zu parsen und gibt diesen zurück. 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> festgelegt ist, wird der Rückgabewert standardmäßig ein leerer String sein, wenn kein <attr-type> festgelegt ist, oder der garantiert ungültige Wert sein, wenn ein <attr-type> festgelegt ist.

Beschreibung

Einschränkungen und Sicherheit

Die attr()-Funktion kann auf Attribute zugreifen, die nie für technischen Einsatz angedacht 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 ein Sicherheitsrisiko darstellen, 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()-verunreinigt markiert. Die Verwendung eines attr()-verunreinigten Wertes als <url> oder in einem <url> macht eine Deklaration "ungültig zur berechneten Zeit" oder kurz IACVT.

Rückwärtskompatibilität

Im Allgemeinen ist die moderne attr()-Syntax rückwärtskompatibel, da die alte Verwendung — ohne Angabe eines <attr-type> — sich wie früher verhält. Der Code attr(data-attr) entspricht 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 Ausschnitt wird die zweite Deklaration in Browsern, die die moderne attr()-Syntax nicht unterstützen, ignoriert, da sie nicht geparst werden kann. 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 werden die zweite Deklaration erfolgreich parsen, aber da es sich um ungültigen Inhalt für die content-Eigenschaft handelt, wird die Deklaration "ungültig zur berechneten Zeit" oder kurz IACVT.

Um solche Situationen zu vermeiden, wird Feature-Erkennung 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". In Browsern mit moderner attr()-Unterstützung gibt es keine Ausgabe.

Das liegt daran, dass attr() — ähnlich wie benutzerdefinierte Eigenschaften, die die var()-Funktion verwenden — zum berechneten Zeitpunkt des Wertes ersetzt wird. Mit dem modernen Verhalten versucht --x zuerst, das Attribut data-attr 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 an Kind-Elemente weitergeben, es sei denn, dies ist explizit gewünscht.

Feature-Erkennung

Sie können die Unterstützung für die moderne attr()-Syntax mit der @supports-Regel zum Erkennen von Funktionen detektieren. Im Test versuchen Sie, eine erweiterte attr() einer (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 */
}

Formale Syntax

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

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

<attr-type> = 
  type( <syntax> )  |
  raw-string        |
  number            |
  <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-* globalen Attributs dem Inhalt des <p>-Elements voran.

HTML

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

CSS

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

Ergebnis

Verwendung eines Fallback-Wertes

In diesem Beispiel fügen wir den Wert des data-browser data-* globalen Attributs dem <p>-Element hinzu. Wenn das data-browser-Attribut beim <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

Farbwert

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

Verwendung von Dimensions-Einheiten

In diesem Beispiel wird das data-rotation-Attribut in eine deg-Einheit geparst, die die Rotation 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

attr()-Werte als <custom-ident>-Werte parsen

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 als Wert für view-transition-name 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 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>
    Your 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 #cccccc;
    background: rgb(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 ein 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 der Fallback-Wert none stattdessen 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 Referenzen zu allen Karten zufällig geändert 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 gemacht, indem das order-Update in einen Aufruf von document.startViewTransition eingewickelt 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

Spezifikationen

Browser-Kompatibilität

Weitere Informationen

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