attr() CSS-Funktion

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 is working to put control of the internet back in the hands of the
  people using it.
</blockquote>

<blockquote cite="https://web.dev/about/">
  Build beautiful, accessible, fast, and secure websites that work
  cross-browser.
</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")

/* With namespace */
attr(color|myAttr type(*), red)

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 aus dem ausgewählten HTML-Element abgerufen werden soll.

Namensräume

Der Attributname kann einen namespace enthalten, der es ermöglicht, Elemente von auf XML basierenden Auszeichnungssprachen wie SVG oder MathML gezielt anzusprechen.

css

@namespace svg url("http://www.w3.org/2000/svg");
a {
  fill: attr(svg|myAttr type(*), green);
}

Hinweis: Wenn kein Namensraum angegeben wird (nur ein Bezeichner wie attr(foo) gegeben ist), wird der null Namensraum impliziert. Dies ist normalerweise erwünscht, da namensraum-spezifische Attribute selten sind. Wie bei Attributselektoren hängt die Groß-/Kleinschreibung von <attr-name> von der Dokumentsprache ab.

<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 (angegeben durch einen <attr-unit> Bezeichner) sein. Wenn er weggelassen wird, ist der Standard raw-string.

raw-string

Das raw-string Schlüsselwort bewirkt, dass der wörtliche Wert des Attributs als Wert einer CSS-Zeichenkette behandelt wird, ohne dass eine CSS-Analyse erfolgt (einschließlich CSS-Escapes, Leerzeichenentfernung, Kommentare usw.). Der <fallback-value> wird nur verwendet, wenn das Attribut fehlt; die Angabe eines leeren Werts löst keinen Rückfall 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 unterstützt, um die Abwärtskompatibilität zu gewährleisten.

type()

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

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

<attr-unit>

Der <attr-unit> Bezeichner gibt die Einheit an, die ein numerischer Wert haben soll (falls vorhanden). Es kann das %-Zeichen (Prozentsatz) oder eine CSS-Distanz-Einheit 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 eine CSS-Zeichenkette.

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

Wenn kein <fallback-value> gesetzt ist, wird der Rückgabewert standardmäßig eine leere Zeichenkette, 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 nie zum Styling gedacht waren und möglicherweise sensible Informationen enthalten (zum Beispiel ein von Skripten auf der Seite verwendetes Sicherheitstoken). Im Allgemeinen ist dies in Ordnung, aber es kann zu einem Sicherheitsrisiko werden, wenn es in URLs verwendet wird.

Aus diesem Grund 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));
}

Diese Einschränkung gilt auch für jeden Kontext, der möglicherweise zu einem <url>-Wert führen könnte. Werte, die attr() verwenden, werden als attr()-verunreinigt markiert, und deren Verwendung als oder in einem <url> lässt eine Deklaration "bei der Berechnungszeit des Werts ungültig" (IACVT) werden.

Daher funktionieren beispielsweise Funktionen wie image-set(), die Werte annehmen, die zu <url> auflösen, ebenfalls nicht:

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

Abwärtskompatibilität

Im Allgemeinen ist die moderne attr()-Syntax abwärtskompatibel, da die alte Verwendungsmethode — ohne Angabe eines <attr-type> — sich genauso verhält wie zuvor. Das Schreiben von attr(data-attr) im Code entspricht dem Schreiben von attr(data-attr type(<string>)) oder der einfacheren attr(data-attr string).

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

Im folgenden Schnipsel verwerfen Browser, die die moderne attr()-Syntax nicht unterstützen, die zweite Deklaration, da 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 parsen die zweite Deklaration erfolgreich, aber da es sich um ungültigen Inhalt für die content-Eigenschaft handelt, wird die Deklaration "bei der Berechnungszeit des Werts ungültig" 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" an. In Browsern mit modernem attr()-Support gibt es keine Ausgabe.

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

Um solche Situationen zu vermeiden, sollten vererbte attr()-Werte nicht an Kinder weitergegeben werden, 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 zur Feature-Erkennung überprüfen. Testen Sie im Test die Zuweisung eines erweiterten attr() zu einer (nicht-benutzerdefinierten) CSS-Eigenschaft.

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

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>                                     

<attr-unit> = 
  <custom-ident>  

<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 dem Inhalt des <p>-Elements den Wert des data-foo data-* globalen Attributs voran.

HTML

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

CSS

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

Ergebnis

Verwendung eines Fallback-Werts

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

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

color-Wert

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 Dimensionseinheiten

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

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

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, welches 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 eine "Karten mischen" <button>, die 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;
  }
}

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

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

JavaScript

Wenn die <button> gedrückt wird, werden die Karten gemischt. Dies geschieht, indem die Reihenfolge eines Arrays, das Verweise auf alle Karten enthält, randomisiert 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 eingebunden 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

Siehe auch

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