Справочник директив шаблонов

Директивы шаблонов — это специальный вид HTML-атрибутов, доступных внутри любого шаблона компонента Astro (.astro), а некоторые из них также можно использовать в файлах .mdx.

Директивы используются для управления поведением элемента или компонента. Директива может включать функции компилятора, упрощающие разработку (например, использование class:list вместо class), или указывать компилятору Astro на необходимость особого обращения с компонентом (например, гидратация с помощью client:load).

На этой странице описаны все доступные директивы шаблонов в Astro и принцип их работы.

Правила

Чтобы директива была валидной, она должна:

• Содержать двоеточие : в названии, имея форму X:Y (например, client:load).
• Быть видимой для компилятора (например, <X {...attr}> не сработает, если attr содержит директиву).

Некоторые директивы принимают значения:

• <X client:load /> (не принимает значение)
• <X class:list={['some-css-class']} /> (принимает массив)

Директивы никогда не включаются напрямую в итоговый HTML-вывод компонента.

Общие директивы

class:list

class:list={...} принимает массив значений и преобразует их в строку классов. Это работает на базе популярной библиотеки clsx.

Директива принимает массив различных типов значений:

• string: добавляется в class элемента.
• Object: все ключи с истинными (truthy) значениями добавляются в class.
• Array: разворачивается (flattened).
• false, null или undefined: игнорируются.

<!-- Исходный код -->
<span class:list={[ 'hello goodbye', { world: true }, [ 'friend' ] ]} />
<!-- Результат -->
<span class="hello goodbye world friend"></span>

set:html

set:html={string} вставляет строку HTML внутрь элемента, аналогично свойству el.innerHTML.

Astro не экранирует значение автоматически! Убедитесь, что вы доверяете источнику данных, или экранируйте их вручную. Это предотвратит XSS-атаки.

---
const rawHTMLString = "Привет, <strong>Мир</strong>"
---
<h1>{rawHTMLString}</h1>
  <!-- Вывод: <h1>Привет, &lt;strong&gt;Мир&lt;/strong&gt;</h1> -->
<h1 set:html={rawHTMLString} />
  <!-- Вывод: <h1>Привет, <strong>Мир</strong></h1> -->

set:text

set:text={string} вставляет текстовую строку в элемент, аналогично el.innerText. В отличие от set:html, значение автоматически экранируется.

Это эквивалентно прямой вставке переменной в фигурных скобках (<div>{someText}</div>), поэтому данная директива используется редко.

Клиентские директивы

Эти директивы управляют процессом гидратации компонентов UI-фреймворков на странице.

По умолчанию компоненты не гидрируются на клиенте. Если директива client:* не указана, их HTML рендерится без JavaScript.

client:load

• Приоритет: Высокий
• Применение: Срочно видимые элементы, которые должны стать интерактивными как можно скорее.

Загружает и гидрирует JavaScript компонента сразу при загрузке страницы.

<BuyButton client:load />

client:idle

• Приоритет: Средний
• Применение: Второстепенные элементы, не требующие немедленной интерактивности.

Загружает и гидрирует JavaScript компонента после завершения первоначальной загрузки страницы и срабатывания события requestIdleCallback.

<ShowHideButton client:idle />

client:visible

• Приоритет: Низкий
• Применение: Элементы, находящиеся глубоко внизу страницы («ниже сгиба»), или ресурсоемкие компоненты, которые лучше не загружать совсем, если пользователь их не увидит.

Загружает JavaScript только тогда, когда компонент попадает в область видимости пользователя (viewport).

<HeavyImageCarousel client:visible />

client:media

• Приоритет: Низкий
• Применение: Боковые панели (sidebars) или другие элементы, видимые только на определенных размерах экрана.

client:media={string} загружает JavaScript компонента при выполнении указанного CSS медиа-запроса.

<SidebarToggle client:media="(max-width: 50em)" />

client:only

client:only={string} пропускает рендеринг HTML на сервере и рендерит компонент только на клиенте.

Вы должны явно указать фреймворк!

<SomeReactComponent client:only="react" />
<SomeSvelteComponent client:only="svelte" />

Серверные директивы

server:defer

Превращает компонент в серверный островок, заставляя его рендериться по запросу, отдельно от остальной части страницы.

<Avatar server:defer />

Директивы для скриптов и стилей

is:global

По умолчанию Astro изолирует (scopes) стили внутри компонента. Директива is:global отменяет это поведение, делая стили глобальными для всей страницы.

<style is:global>
  body a { color: red; }
</style>

is:inline

Указывает Astro оставить тег <script> или <style> «как есть» в итоговом HTML без обработки, оптимизации или сборки (bundling).

<script is:inline>
  console.log('Я вставлен прямо здесь в итоговом HTML.');
</script>

define:vars

define:vars={...} позволяет передавать серверные переменные из метаданных компонента в клиентские теги <script> или <style>.

---
const color = "red";
---
<style define:vars={{ color }}>
  h1 { color: var(--color); }
</style>

Продвинутые директивы

is:raw

Указывает компилятору Astro воспринимать дочерние элементы как обычный текст, игнорируя любой синтаксис шаблонов Astro.

<style is:raw>
  { Это не будет интерпретировано как переменная }
</style>