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 von dem/den ausgewählten HTML-Element(en) abgerufen werden soll.

Namensräume

Der Attributname kann einen Namensraum enthalten, der das Ansprechen von Elementen auf Markup-Sprachen wie SVG oder MathML ermöglicht.

css

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

Hinweis: Wenn kein Namensraum angegeben ist (nur ein Identifier, wie attr(foo)), wird der Null-Namensraum impliziert. Dies ist normalerweise erwünscht, da benannte Attribute selten sind. Wie bei Attributselektoren hängt die Groß-/Kleinschreibempfindlichkeit von <attr-name> von der Dokumentensprache ab.

<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 (angegeben durch einen <attr-unit>-Identifier) sein. Bei Auslassung ist der Standardwert raw-string.

raw-string

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

css

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

Hinweis: Dieses Schlüsselwort wurde ursprünglich in Chromium-Browsern als string bekannt und unterstützt. Beide Schlüsselwörter werden kurz unterstützt, um die Abwärtskompatibilität sicherzustellen.

type()

Die type()-Funktion nimmt ein <syntax> als Argument, das den zu parsenden Datentyp spezifiziert.

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

<attr-unit>

Der <attr-unit>-Identifier gibt die Einheit an, die ein numerischer Wert haben sollte (falls vorhanden). Es kann das %-Zeichen (Prozent) oder eine CSS-Längeneinheit 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 als CSS-String.

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, ist der Rückgabewert standardmäßig ein leerer String, wenn kein <attr-type> festgelegt ist, oder der garantiert ungültige Wert, wenn ein <attr-type> festgelegt ist.

Beschreibung

Einschränkungen und Sicherheit

Die attr()-Funktion kann auf Attribute verweisen, die nie für Stylingzwecke vorgesehen waren und möglicherweise sensible Informationen enthalten (zum Beispiel ein Sicherheitstoken, das von Skripten auf der Seite verwendet wird). Im Allgemeinen ist dies unbedenklich, kann jedoch ein Sicherheitsrisiko darstellen, wenn sie 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));
}

Diese Einschränkung gilt jedoch nur an Orten, die strikt einen <url>-Typ erfordern. Einige Funktionen — wie image-set() — können einen <string>-Wert akzeptieren, der später als URL interpretiert wird, was es attr() ermöglicht, in diesen Kontexten zu funktionieren, abhängig von der Browserunterstützung:

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

Werte, die attr() verwenden, werden als attr()-kontaminiert markiert. Die Verwendung eines attr()-kontaminierten Wertes als <url> oder darin macht eine Deklaration "ungültig zur Berechnungszeit" oder kurz IACVT.

Abwärtskompatibilität

Im Allgemeinen ist die moderne attr()-Syntax rückwärtskompatibel, da die alte Methode, sie zu verwenden — ohne einen <attr-type> anzugeben — genauso funktioniert wie zuvor. attr(data-attr) im Code zu haben, ist dasselbe wie attr(data-attr type(<string>)) oder das einfachere attr(data-attr string)) zu schreiben.

Es gibt jedoch zwei Sonderfä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 es sich um einen ungültigen Inhalt für die content-Eigenschaft handelt, wird die Deklaration "ungültig zur Berechnungszeit" oder kurz IACVT werden.

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

Das liegt daran, dass attr() — ähnlich wie bei benutzerdefinierten Eigenschaften, die die var()-Funktion verwenden — zur Berechnungszeit 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 dieses Attribut auf #parent nicht existiert. Dieser leere String wird dann vom #child-Element geerbt, was zu einer content: ;-Deklaration führt.

Um solche Situationen zu vermeiden, sollten Sie geerbte attr()-Werte nicht an Kinder weitergeben, es sei denn, dies wird ausdrücklich gewünscht.

Feature-Erkennung

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

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>                                     

<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 den Wert des data-foo data-* globalen Attributs zu den Inhalten des <p>-Elements hinzu.

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 den Wert des data-browser data-* globalen Attributs zum <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 Dimesionseinheiten

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

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 einen <custom-ident> geparst, der das akzeptierte Wertformat von view-transition-name ist.

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 <button> "Shuffle cards", 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;
  }
}

Auf jeder Karte ruft die attr()-Funktion das id-Attribut ab und parst es in einen <custom-ident>, der als Wert für die view-transition-name-Eigenschaft verwendet wird. Wenn keine id für eine 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 der <button> gedrückt wird, werden die Karten gemischt. Dies geschieht durch das Zufällig-Anordnen eines Arrays, das Referenzen zu allen Karten enthält, und das anschließende Aktualisieren der order-Eigenschaft jeder Karte auf ihre neue Array-Indexposition.

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