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 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")

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

<attr-type>

Gibt an, wie der Attributwert in einen CSS-Wert geparst werden soll. Dies kann das raw-string-Schlüsselwort, eine type()-Funktion oder eine CSS-Dimensionseinheit sein (angegeben mit einem <attr-unit>-Bezeichner). Wenn weggelassen, ist dies standardmäßig raw-string.

raw-string

Das raw-string-Schlüsselwort bewirkt, dass der Literalwert des Attributs als Wert eines CSS-Strings behandelt wird, ohne dass eine CSS-Analyse durchgeführt wird (einschließlich CSS-Fluchten, Leerzeichentfernung, Kommentare usw.). Der <fallback-value> wird nur verwendet, wenn das Attribut weggelassen wird; die Angabe 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 benannt und unterstützt. Beide Schlüsselwörter werden zur Rückwärtskompatibilität kurzzeitig unterstützt.

type()

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

Hinweis: Aus Sicherheitsgründen ist <url> als attr()-Datentyp nicht 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-Distanzeinheit 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 diesen 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 als CSS-String geparst.

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

Beschreibung

Einschränkungen und Sicherheit

Die attr()-Funktion kann Attribute referenzieren, die nie für die Stilnutzung vorgesehen waren und möglicherweise sensible Informationen enthalten (zum Beispiel ein von Skripten auf der Seite verwendetes Sicherheitstoken). Im Allgemeinen ist das in Ordnung, aber es kann zu einer Sicherheitsbedrohung 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));
}

Diese Einschränkung gilt jedoch nur für Stellen, 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 attr() in diesen Kontexten je nach Browserunterstützung ermöglicht:

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

Werte, die attr() verwenden, werden als attr()-verunreinigt markiert. Die Verwendung eines attr()-verunreinigten Wertes als oder in einer <url> führt dazu, dass eine Deklaration "invalid at computed value time" oder kurz IACVT wird.

Abwärtskompatibilität

Allgemein gesprochen ist die moderne attr()-Syntax abwärtskompatibel, da die alte Methode, sie zu verwenden – ohne Angabe eines <attr-type> – sich wie zuvor verhält. Das Vorhandensein von attr(data-attr) in Ihrem Code ist dasselbe wie attr(data-attr type(<string>)) oder das einfachere attr(data-attr string) zu schreiben.

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

Im folgenden Beispiel 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 sein. Diese Browser parsen die zweite Deklaration erfolgreich, aber da sie ein ungültiger Inhalt für die content-Eigenschaft ist, wird die Deklaration "invalid at computed value time" oder kurz IACVT .

Um solche Situationen zu verhindern, wird Feature-Erkennung empfohlen.

Ein zweiter Randfall 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 – zur Berechnungswertzeit ersetzt wird. 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 festgelegt wird.

Um diese Art von Situation zu vermeiden, sollten Sie geerbte attr()-Werte nicht an Kinder weitergeben, es sei denn, Sie möchten es ausdrücklich.

Feature-Erkennung

Sie können die Unterstützung für die moderne attr()-Syntax mit der @supports-At-Regel erkennen. Im Test versuchen Sie, einen erweiterten 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 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>                                     

<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 wird der Wert des data-foo-data-* globalen Attributs vor dem Inhalt des <p>-Elements hinzugefügt.

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 im <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

Farbwert

In diesem Beispiel setzen wir den CSS-Wert von background-color auf den Wert des data-background-data-* globalen Attributs des <div>-Elements.

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 Eigenschaft view-transition-name aus dem id-Attribut des Elements abgeleitet. Das Attribut wird in einen <custom-ident> geparst, 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 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;
  }
}

Auf jeder Karte erhält die attr()-Funktion das id-Attribut und parst es in einen <custom-ident>, der als Wert für die view-transition-name-Eigenschaft verwendet wird. Wenn keine id auf einer Karte 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 durch das Zufallswechseln der Reihenfolge eines Arrays mit Verweisen auf alle Karten und anschließendem Aktualisieren der order-Eigenschaft jeder Karte auf deren neuen Array-Indexposition.

Um jede Karte zu ihrem neuen Platz zu animieren, werden View Transitions verwendet. Dies geschieht durch das Einwickeln der order-Aktualisierung in einen Aufruf von document.startViewTransition.

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