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.

Namespaces

Der Attributname kann einen Namespace enthalten, der es erlaubt, Elemente von XML-basierten Markupsprachen wie SVG oder MathML anzusprechen.

css

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

Hinweis: Wenn kein Namespace angegeben wird (nur ein Bezeichner wie attr(foo)), wird der Null-Namespace angenommen. Dies ist in der Regel gewünscht, da namensbasierte Attribute selten sind. Wie bei Attributselektoren hängt die Groß- und Kleinschreibung von <attr-name> von der Dokumentensprache ab.

<attr-type>

Gibt an, wie der Attributwert in einen CSS-Wert analysiert wird. Dies kann das raw-string-Schlüsselwort, eine type()-Funktion oder eine CSS-Dimensionseinheit sein, die mit einem <attr-unit>-Bezeichner angegeben wird. Wird sie weggelassen, wird raw-string als Standard verwendet.

raw-string

Das raw-string-Schlüsselwort bewirkt, dass der Literalwert des Attributs als Wert eines CSS-Strings behandelt wird, ohne CSS-Parsing (einschließlich CSS-Escapes, Leerzeichenentfernung, Kommentare usw.). Der <fallback-value> wird nur verwendet, wenn das Attribut fehlt; die Angabe eines leeren Werts löst die Rückfalllösung nicht 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 kurzzeitig aus Gründen der Abwärtskompatibilität unterstützt.

type()

Die type()-Funktion nimmt ein <syntax> als Argument an, das angibt, in welchen Datentyp der Wert analysiert 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 sollte (falls vorhanden). Es kann sich um das %-Zeichen (Prozentsatz) oder um eine CSS-Distanzeinheit wie px, rem, deg, s usw. handeln.

css

attr(data-size rem)
attr(data-width px, inherit)
attr(data-rotation deg)

<fallback-value>

Der Wert, der verwendet wird, 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, analysiert als der angegebene <attr-type> oder analysiert als CSS-String.

Wenn ein <attr-type> festgelegt ist, versucht attr(), das Attribut in diesen angegebenen <attr-type> zu analysieren und zurückzugeben. Wenn das Attribut nicht in den angegebenen <attr-type> analysiert werden kann, wird stattdessen der <fallback-value> zurückgegeben. Wenn kein <attr-type> festgelegt ist, wird das Attribut in einen CSS-String analysiert.

Wenn kein <fallback-value> festgelegt ist, wird 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 zur Verwendung in der Gestaltung gedacht waren und möglicherweise sensible Informationen enthalten (z. B. ein Sicherheitstoken, das von Skripten auf der Seite verwendet wird). Im Allgemeinen ist dies in Ordnung, kann jedoch ein Sicherheitsrisiko werden, wenn es in URLs verwendet wird. Daher kann attr() nicht verwendet werden, 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 streng einen <url>-Typ erfordern. Einige Funktionen – wie image-set() – können einen <string>-Wert akzeptieren, der später als URL interpretiert wird, sodass attr() je nach Browser-Unterstützung in diesen Kontexten funktioniert:

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 oder in einer <url> führt dazu, dass eine Deklaration "invalid at computed value time" oder IACVT für kurze Zeit" wird.

Abwärtskompatibilität

Im Allgemeinen ist die moderne attr()-Syntax abwärtskompatibel, da die alte Verwendungsmethode – ohne Angabe eines <attr-type> – genauso funktioniert wie zuvor. Wenn Sie attr(data-attr) in Ihrem Code haben, ist dies dasselbe wie attr(data-attr type(<string>)) oder das einfachere attr(data-attr string) zu schreiben.

Es gibt jedoch zwei Grenzfälle, in denen sich die moderne attr()-Syntax von der alten Syntax unterscheidet.

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

Um diese Art von 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 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 benutzerdefinierte Eigenschaften, die die var()-Funktion verwenden – zur berechneten Wertzeit 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 kein solches Attribut auf #parent vorhanden ist. Dieser leere String wird dann vom #child-Element geerbt, was zu einer content: ;-Deklaration führt.

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

Feature-Erkennung

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

Die gleiche Überprüfung kann in JavaScript mit CSS.supports() durchgeführt werden:

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 vor dem Inhalt des <p>-Elements hinzu.

HTML

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

CSS

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

Ergebnis

Verwendung eines Rückfallwerts

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 "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, 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 Attribut data-rotation in eine deg-Einheit analysiert, 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

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

In diesem Beispiel leiten sich die Werte für die view-transition-name-Eigenschaft aus dem id-Attribut des Elements ab. Das Attribut wird in ein <custom-ident> analysiert, 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 ruft die attr()-Funktion das id-Attribut ab und analysiert 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 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, indem die Reihenfolge eines Arrays, das Verweise auf alle Karten enthält, zufällig bestimmt wird und anschließend 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 das order-Update 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

Spezifikationen

Browser-Kompatibilität

Siehe auch

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