CSS-функция `attr()`

attr() — CSS-функция, которая извлекает значение атрибута выбранного элемента и использует его в значении свойства, подобно тому, как функция var() подставляет значение пользовательского свойства. Её также можно использовать с псевдоэлементами; в этом случае возвращается значение атрибута элемента, породившего псевдоэлемент.

Попробуйте

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>

Синтаксис

/* 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)

Параметры

Синтаксис функции attr() выглядит следующим образом:

attr(<attr-name> <attr-type>? , <fallback-value>?)

Параметры:

<attr-name>

Имя атрибута, значение которого требуется получить у выбранного HTML-элемента или элементов.

Пространства имён

Имя атрибута может содержать namespace, позволяющее выбирать элементы языков разметки на основе XML, таких как SVG или MathML.

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

Примечание: Если пространство имён не указано (задано только имя, например attr(foo)), подразумевается пространство имён null. Обычно это именно то, что нужно, поскольку атрибуты с пространствами имён встречаются редко. Как и в случае с селекторами атрибутов, чувствительность <attr-name> к регистру зависит от языка документа.

<attr-type>

Задаёт способ преобразования значения атрибута в значение CSS. Это может быть ключевое слово raw-string, функция type() или единица измерения CSS (задаётся с помощью идентификатора <attr-unit>). Если параметр не указан, по умолчанию используется raw-string.

raw-string

Ключевое слово raw-string приводит к тому, что буквальное значение атрибута рассматривается как значение CSS-строки без обработки CSS (включая CSS-экранирование, удаление пробелов, комментарии и т. д.). Значение <fallback-value> используется только в том случае, если атрибут отсутствует; указание пустого значения не активирует резервное значение.

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

Примечание: Изначально это ключевое слово называлось string и поддерживалось в браузерах Chromium. Оба ключевых слова будут поддерживаться в течение короткого времени для обратной совместимости.

type()

Функция type() принимает в качестве аргумента <syntax>, который задаёт тип данных для преобразования значения.

Примечание: По соображениям безопасности <url> не допускается в качестве типа данных attr().

<attr-unit>

Идентификатор <attr-unit> задаёт единицу измерения (если она нужна) для числового значения. Это может быть символ % (процент) или единица расстояния CSS, например px, rem, deg, s и т. д.

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

<fallback-value>

Значение, используемое, если указанный атрибут отсутствует или содержит недопустимое значение.

Возвращаемое значение

Функция attr() возвращает значение HTML-атрибута с именем <attr-name>, преобразованное в указанный <attr-type> или в строку CSS.

Если задан <attr-type>, функция attr() попытается преобразовать атрибут в указанный <attr-type> и вернуть его. Если атрибут нельзя преобразовать в заданный <attr-type>, вместо него будет возвращён <fallback-value>. Если <attr-type> не задан, атрибут будет преобразован в строку CSS.

Если <fallback-value> не задан, возвращаемым значением будет пустая строка, когда не задан <attr-type>, или гарантированно недопустимое значение, когда задан <attr-type>.

Описание

Ограничения и безопасность

Функция attr() может обращаться к атрибутам, которые изначально не предназначались для использования при стилизации и могут содержать конфиденциальную информацию (например, токен безопасности, используемый скриптами на странице). Как правило, это не проблема, но при использовании в URL-адресах может возникнуть угроза безопасности.

По этой причине нельзя использовать attr() для динамического создания URL-адресов:

<!-- 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));
}

Это ограничение также применяется к любому контексту, который потенциально может привести к значению <url>. Значения, в которых используется attr(), помечаются как загрязнённые attr(), а их использование в качестве <url> или внутри него делает объявление «недопустимым на этапе вычисления значения» (IACVT).

Поэтому не работают и такие функции, как image-set(), принимающие значения, которые разрешаются в <url>:

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

Обратная совместимость

В целом современный синтаксис attr() обратно совместим, поскольку старый способ его использования — без указания <attr-type> — работает так же, как и раньше. Запись attr(data-attr) в коде равнозначна attr(data-attr type(<string>)) или более краткой записи attr(data-attr string)).

Однако есть два исключительных случая, когда современный синтаксис attr() ведёт себя не так, как старый.

В следующем фрагменте браузеры, не поддерживающие современный синтаксис attr(), отбросят второе объявление, потому что не смогут его разобрать. В этих браузерах результатом будет "Hello World".

<div text="Hello"></div>

div::before {
  content: attr(text) " World";
}
div::before {
  content: attr(text) 1px;
}

В браузерах с поддержкой современного синтаксиса результатом будет… ничего. Такие браузеры успешно разберут второе объявление, но, поскольку его содержимое недопустимо для свойства content, объявление станет «недопустимым на этапе вычисления значения», или IACVT.

Чтобы избежать такой ситуации, рекомендуется использовать проверку поддержки функции.

Второй исключительный случай:

<div id="parent"><div id="child" data-attr="foo"></div></div>

#parent {
  --x: attr(data-attr);
}
#child::before {
  content: var(--x);
}

Браузеры без поддержки современного синтаксиса отображают текст "foo". В браузерах с поддержкой современного синтаксиса attr() ничего не отображается.

Это происходит потому, что attr() — подобно пользовательским свойствам, в которых используется функция var(), — подставляется на этапе вычисления значения. При современном поведении --x сначала пытается прочитать атрибут data-attr у элемента #parent, что возвращает пустую строку, поскольку у #parent нет такого атрибута. Затем эта пустая строка наследуется элементом #child, в результате чего задаётся объявление content: ;.

Чтобы избежать подобных ситуаций, не передавайте наследуемые значения attr() дочерним элементам, если только это не является вашей целью.

Проверка поддержки функции

Поддержку современного синтаксиса attr() можно проверить с помощью директивы @supports. В проверке попробуйте присвоить расширенное значение attr() (не пользовательскому) свойству CSS.

Например:

@supports (x: attr(x type(*))) {
  /* Browser has modern attr() support */
}

@supports not (x: attr(x type(*))) {
  /* Browser does not have modern attr() support */
}

Такую же проверку можно выполнить в JavaScript с помощью CSS.supports():

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

Формальный синтаксис

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

<attr-type> = 
  type( <syntax> ) |
  raw-string |
  number |
  <attr-unit>

Примеры

Свойство content

В этом примере мы добавляем значение атрибута data-foo data-* глобального атрибута перед содержимым элемента <p>.

HTML

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

CSS

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

Результат

Использование резервного значения

В этом примере мы добавляем значение атрибута data-browser data-* глобального атрибута после элемента <p>. Если у элемента <p> отсутствует атрибут data-browser, мы добавляем резервное значение «Неизвестно».

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;
}

Результат

Значение цвета

В этом примере мы задаём для CSS-свойства background-color значение атрибута data-background data-* глобального атрибута, назначенного элементу <div>.

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);
}

Результат

Использование единиц измерения

В этом примере атрибут data-rotation преобразуется в единицу deg, задающую поворот элемента.

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);
}

Результат

Преобразование значений attr() в <custom-ident>

В этом примере значения свойства view-transition-name определяются атрибутом id элемента. Атрибут преобразуется в <custom-ident>, который и принимает в качестве значения свойство view-transition-name.

В результате для свойства view-transition-name получаются значения card-1, card-2, card-3 и т. д.

HTML

HTML содержит четыре карточки с разными атрибутами id и кнопку «Перемешать карточки» <button>, которая перемешивает карточки.

<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

Карточки размещены во flex-контейнере:

.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;
  }
}

Для каждой карточки функция attr() получает атрибут id и преобразует его в <custom-ident>, который используется как значение свойства view-transition-name. Если у карточки не задан id, вместо него используется резервное значение none.

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

JavaScript

При нажатии кнопки <button> карточки перемешиваются. Для этого случайным образом меняется порядок массива, содержащего ссылки на все карточки, а затем свойству order каждой карточки присваивается её новая позиция в массиве.

Для анимации перемещения каждой карточки на новую позицию используется API переходов между представлениями. Для этого обновление order оборачивается в вызов 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);
    });
  });
});

Результат

Спецификации

Совместимость с браузерами

См. также

• Селекторы атрибутов
• Атрибуты HTML data-*
• Атрибуты SVG data-*