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

env() CSS-функцию можно использовать для вставки в CSS значения переменной окружения, определённой пользовательским агентом. Кроме того, env() можно использовать для создания динамических значений во внешних SVG-файлах, обновляемых с помощью CSS-свойства link-parameters.

Синтаксис

/* Without a fallback value */
env(safe-area-inset-top);
env(titlebar-area-width);
env(viewport-segment-right 0 0);

/* With a fallback value */
env(safe-area-inset-right, 1em);
env(titlebar-area-y, 40px);
env(viewport-segment-width 0 0, 40%);

<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
  <path fill="env(--color, black)" d="..." />
</svg>

Параметры

Функция env( <environment-variable> | <dashed-ident>, <fallback> | <declaration-value> ) принимает следующие параметры:

<environment-variable>

<custom-ident>, задающий имя вставляемой переменной окружения. Если указанное имя обозначает переменную окружения, похожую на массив, за именем следуют значения <integer>, указывающие конкретный экземпляр, на который ссылается имя. Имена переменных окружения чувствительны к регистру и могут быть следующими:

safe-area-inset-top, safe-area-inset-right, safe-area-inset-bottom, safe-area-inset-left

Безопасное расстояние от верхнего, правого, нижнего или левого края области просмотра, определяющее, где можно размещать содержимое без риска его обрезания из-за формы дисплея, не являющегося прямоугольным. Эти четыре значения образуют прямоугольник, внутри которого всё содержимое видно. Значения равны 0, если область просмотра прямоугольная и никакие элементы — например, панели инструментов или динамические клавиатуры — не занимают её пространство; в противном случае значение представляет собой px, большее 0.

safe-area-max-inset-top, safe-area-max-inset-right, safe-area-max-inset-bottom, safe-area-max-inset-left

Статические максимальные значения соответствующих динамических переменных safe-area-inset-*, когда все динамические элементы пользовательского интерфейса скрыты. Значения safe-area-inset-* меняются вместе с изменением текущей видимой области содержимого, а значения safe-area-max-inset-* являются константами.

titlebar-area-x, titlebar-area-y, titlebar-area-width, titlebar-area-height

Размеры видимой области titlebar-area-*. Эти переменные доступны при использовании поля манифеста window-controls-overlay display_override. Значения переменных можно использовать, чтобы содержимое не перекрывало кнопки управления окном (то есть сворачивания, разворачивания и закрытия) в прогрессивных веб-приложениях (PWA), установленных на настольных устройствах.

keyboard-inset-top, keyboard-inset-right, keyboard-inset-bottom, keyboard-inset-left, keyboard-inset-width, keyboard-inset-height

Отступы от края области просмотра и размеры экранной виртуальной клавиатуры устройства. Определены в API VirtualKeyboard.

preferred-text-scale

Предпочитаемый пользователем коэффициент масштабирования шрифта — число, заданное в настройках браузера или операционной системы. Его можно использовать, чтобы пропорционально изменять размер содержимого в соответствии с размером шрифта, заданным в браузере или операционной системе.

viewport-segment-width, viewport-segment-height, viewport-segment-top, viewport-segment-right, viewport-segment-bottom, viewport-segment-left

Размеры и позиции смещения конкретных сегментов области просмотра. За ключевым словом viewport-segment-* следуют два разделённых пробелом значения <integer>, указывающие горизонтальную и вертикальную позицию сегмента, то есть его индексы. Ключевые слова сегментов области просмотра определены только тогда, когда область просмотра состоит из двух или более сегментов, как на складных устройствах и устройствах с шарниром.

<dashed-ident>

<dashed-ident> — это пользовательская переменная, которую можно использовать как идентификатор в CSS-функции param() для обновления значения.

<fallback> Необязательный

Резервное значение, которое вставляется, если переменная окружения, указанная в первом аргументе, не существует. Всё, что следует за первой запятой, считается резервным значением. Это может быть одно значение, другая функция env() или список значений, разделённых запятыми.

<declaration_value> Необязательный

<declaration_value> — это значение SVG-атрибута по умолчанию, который задаётся динамически. Если <declaration-value> не указан, он представляет собой пустое значение.

Описание

Функция env() используется для вставки в CSS значения глобальной переменной окружения, определённой пользовательским агентом. Функцию env() можно использовать в качестве значения свойства или вместо любой части значения свойства или дескриптора (например, в правилах медиазапросов).

Первым аргументом функции является <environment-variable>. Это чувствительный к регистру <custom-ident>, совпадающий с именем переменной окружения, которую нужно подставить; при необходимости он также может включать дополнительные значения, разделённые пробелами. Например, env(viewport-segment-width 0 0) вернёт ширину верхнего или левого сегмента устройства с несколькими сегментами области просмотра.

Второй аргумент, если он указан, — это резервное значение, которое используется, если переменная окружения, указанная в первом аргументе, не поддерживается или не существует. Резервным значением может быть другая переменная окружения, даже со своим резервным значением.

Синтаксис резервного значения похож на синтаксис резервного значения функции var(), используемой для вставки пользовательских свойств CSS, поскольку допускает несколько запятых. Всё между первой запятой и концом функции считается резервным значением. Однако если функция env() используется в значении свойства или дескрипторе, не содержащем запятых, резервное значение с запятыми будет недопустимым.

Свойство или дескриптор, содержащие синтаксически корректную функцию env(), считаются допустимыми во время разбора — когда браузер впервые читает и интерпретирует загруженный текст CSS. Проверка синтаксиса выполняется только на этапе вычисления, после того как каждая функция env() заменена значением, предоставленным браузером (или резервным значением, если переменная окружения, переданная первым параметром, не является известным именем переменной окружения). Если значение недопустимо и резервное значение не указано, свойство или дескриптор, содержащие функцию env(), становятся недопустимыми на этапе вычисления значения.

Если подстановка env() недопустима и указано недопустимое резервное значение либо резервное значение отсутствует, объявление не игнорируется. Вместо этого используется начальное или наследуемое значение свойства. Свойству присваивается новое значение, но оно может отличаться от ожидаемого.

Варианты использования

Изначально предоставленные браузером iOS значения safe-area-inset-* позволяют разработчикам размещать содержимое в безопасной области просмотра, чтобы его не перекрывали вырезы в экране или закруглённые углы устройства. Их можно использовать, чтобы содержимое оставалось видимым для пользователей. Позднее возможности этой функции расширили за пределы первоначального назначения, добавив такие сценарии, как предотвращение перекрытия части интерфейса приложения уведомлениями устройства.

Другой вариант использования переменных env() — настольные прогрессивные веб-приложения (PWA), использующие функцию наложения элементов управления окна, чтобы задействовать всю поверхность окна приложения. Используя значения titlebar-area-*, разработчики могут размещать элементы там, где раньше находилась бы строка заголовка, и обеспечивать, чтобы содержимое не перекрывалось кнопками управления окном.

Имена переменных viewport-segment-* можно использовать, чтобы настроить контейнеры и аккуратно разместить их в доступных сегментах устройства с несколькими сегментами области просмотра, например устройства с шарниром или складного устройства. Целые числа после имени viewport-segment-* указывают, на какой из нескольких сегментов ссылается переменная окружения.

Переменную preferred-text-scale можно использовать, чтобы пропорционально изменять размер текста сайта или других элементов интерфейса в соответствии с размером шрифта, заданным в браузере или операционной системе. Например, можно задать размер шрифта основного текста в процентах от масштаба текста, выбранного пользователем:

body {
  font-size: calc(100% * env(preferred-text-scale));
}

Размеры также можно задать пропорционально размеру шрифта, установленному на уровне браузера или операционной системы, добавив <meta name="text-scale" content="scale"> в документ <head>. По возможности вместо env(preferred-text-scale) следует использовать тег <meta>, поскольку тег <meta> поддерживается на большем количестве платформ и проще в использовании.

Имена с последующими целыми числами

Если переменная окружения похожа на массив, то есть её имя может ссылаться более чем на одно значение, как в случае устройств с несколькими сегментами области просмотра, параметр <environment-variable> включает и имя переменной, и индексы конкретного экземпляра переменной, на который ссылается функция. Например, для переменных viewport-segment-* имена переменных передаются функции env() вместе с двумя целыми числами, указывающими индексы сегмента, значение которого нужно вернуть. Оба значения должны быть целыми числами, не меньшими 0. Первое целое число задаёт горизонтальный индекс сегмента, где 0 — самый левый сегмент; второе значение задаёт вертикальный индекс сегмента, где 0 — самый нижний сегмент:

• При горизонтальном расположении сегментов рядом друг с другом левый сегмент обозначается как 0 0, а правый — как 1 0.
• При вертикальном расположении сегментов сверху вниз верхний сегмент обозначается как 0 0, а нижний — как 0 1.
• На устройствах более чем с двумя сегментами числа могут быть больше. Например, на устройстве с тремя горизонтальными сегментами центральный сегмент может обозначаться как 1 0, а правый — как 2 0.

Например, следующий код возвращает ширину правого сегмента на складном устройстве с двумя сегментами, расположенными горизонтально:

env(viewport-segment-width 1 0)

Полностью работающий пример см. в демонстрации API сегментов области просмотра (исходный код). Также ознакомьтесь с руководством «Использование API сегментов области просмотра», в котором подробно объясняется демонстрация.

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

<env()> = 
  env( <custom-ident> , <declaration-value>? )

Примеры

Использование env() для защиты кнопок от перекрытия элементами интерфейса устройства

В следующем примере env() используется, чтобы кнопки закреплённой панели инструментов приложения не перекрывались уведомлениями устройства, появляющимися внизу экрана. На настольных устройствах safe-area-inset-bottom равно 0. Однако на устройствах, отображающих уведомления внизу экрана, например на iOS, оно содержит значение, оставляющее место для уведомления. Это значение можно использовать в padding-bottom, чтобы создать зазор, который будет выглядеть естественно на таком устройстве.

HTML

У нас есть раздел <main> с имитацией приложения и раздел <footer> с двумя элементами <button>:

<main>Main content of app here</main>
<footer>
  <button>Go here</button>
  <button>Or here</button>
</footer>

CSS

Используя гибкую блочную раскладку CSS, мы создаём нижнюю панель высотой, необходимой только для её содержимого, а основной раздел с приложением заполняет оставшуюся часть области просмотра:

body {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
  font: 1em system-ui;
}

main {
  flex: 1;
  background-color: #eeeeee;
  padding: 1em;
}

footer {
  flex: none;
  display: flex;
  gap: 1em;
  justify-content: space-evenly;
  background: black;
}

button {
  padding: 1em;
  background: white;
  color: black;
  margin: 0;
  width: 100%;
  border: none;
  font: 1em system-ui;
}

Мы задаём position: sticky, чтобы закрепить нижнюю панель у нижнего края области просмотра. Затем используем сокращённое свойство padding, чтобы добавить отступы для нижней панели. К исходному значению 1em нижнего отступа мы добавляем значение переменной окружения safe-area-inset-bottom. На устройствах с положительным значением этой переменной появится более крупная чёрная область, благодаря которой кнопки в нижней панели никогда не будут перекрыты.

footer {
  position: sticky;
  bottom: 0;

  padding: 1em 1em calc(1em + env(safe-area-inset-bottom));
}

Результат

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

В этом примере используется необязательный второй параметр функции env(), который задаёт резервное значение на случай, если переменная окружения недоступна.

HTML

Добавим абзац текста:

<p>
  If the <code>env()</code> function is supported in your browser, this
  paragraph's text will have 50px of padding between it and the left border —
  but not the top, right and bottom. This is because the accompanying CSS is the
  equivalent of <code>padding: 0 0 0 50px</code>, because, unlike other CSS
  properties, user agent property names are case-sensitive.
</p>

CSS

Мы задаём width равную 300px и border. Затем добавляем padding, используя функцию env() с резервным значением для размера отступа с каждой стороны. Для левого отступа мы намеренно задаём недопустимое значение (помните, что имена переменных окружения чувствительны к регистру), чтобы показать использование резервного значения.

p {
  width: 300px;
  border: 2px solid red;
  padding: env(safe-area-inset-top, 50px) env(safe-area-inset-right, 50px)
    env(safe-area-inset-bottom, 50px) env(SAFE-AREA-INSET-LEFT, 50px);
}

Результат

Использование env() для защиты содержимого от перекрытия кнопками управления окном в настольных PWA

В следующем примере env() гарантирует, что содержимое настольного прогрессивного веб-приложения, использующего API наложения элементов управления окном, не будет перекрыто кнопками управления окном операционной системы. Значения titlebar-area-* задают прямоугольник, в котором обычно отображалась бы строка заголовка. На устройствах, не поддерживающих функцию наложения элементов управления окном, например на мобильных устройствах, используются резервные значения.

Обычно PWA, установленное на настольном устройстве, выглядит так:

При включённой функции наложения элементов управления окном веб-содержимое занимает всю поверхность окна приложения, а элементы управления окном и кнопки PWA отображаются поверх него:

<header>Title of the app here</header>
<main>Main content of app here</main>

header {
  position: fixed;
  left: env(titlebar-area-x);
  top: env(titlebar-area-y);
  width: env(titlebar-area-width);
  height: env(titlebar-area-height);
}

main {
  margin-top: env(titlebar-area-height);
}

Сегменты области просмотра

Демонстрация API сегментов области просмотра и руководство «Использование API сегментов области просмотра» содержат пример и объяснение использования функции env() с переменными окружения viewport-segments-*.

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

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

См. также

• Использование переменных окружения
• Модуль переменных окружения CSS
• var()
• Модуль пользовательских свойств CSS для каскадных переменных
• Пользовательские свойства (--*): переменные CSS
• <meta name="text-scale">
• Использование пользовательских свойств CSS (переменных)
• API сегментов области просмотра
• Настройка наложения элементов управления окном в строке заголовка вашего PWA
• Отображение содержимого в строке заголовка
• Выход за рамки