Шапка работает только внутри CdsLayout — вне макета она ничего не отрисует и предупредит об этом в консоли. Содержимое шапки раскладывает CdsToolbar, а нижнюю панель приложения собирает CdsFooter.

Вариации

Разделитель

Шапка перекрывает прокручиваемый контент, поэтому её край стоит обозначить: bordered рисует границу, elevated — тень. Тень заметнее и лучше подходит длинным спискам, граница — спокойным страницам.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const separator = ref('bordered');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="separator" direction="horizontal" hide-details>
      <CdsRadio value="none" label="Без разделителя" />
      <CdsRadio value="bordered" label="Граница" />
      <CdsRadio value="elevated" label="Тень" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bordered="separator === 'bordered'" :elevated="separator === 'elevated'">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="flex flex-col gap-2">
              <div v-for="n in 6" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Блок {{ n }}
              </div>
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Высота

Высоту задаёт содержимое: макет замеряет шапку и резервирует ровно столько места, сколько она занимает. Свойство height — начальная оценка до первого замера: укажите ожидаемую высоту, чтобы контент не подпрыгивал при монтировании.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const size = ref(56);
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="size" direction="horizontal" hide-details>
      <CdsRadio :value="40" label="40 px" />
      <CdsRadio :value="56" label="56 px" />
      <CdsRadio :value="80" label="80 px" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader bordered :height="size">
          <CdsToolbar :style="{ height: size + 'px' }">
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Контент начинается ровно под шапкой: макет замерил её и зарезервировал {{ size }} px.
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Цвет

Свойство bg-color красит фон шапки алиасом палитры, color — текст и иконки внутри. Если задан только фон, цвет текста подбирается контрастным автоматически.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="teal" label="teal" />
      <CdsRadio value="neutral" label="neutral" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bg-color="bgColor === 'default' ? undefined : bgColor">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Плавающий режим

Свойство reveal прячет шапку при прокрутке вниз и возвращает при прокрутке вверх — на длинных списках это отдаёт экран контенту. Свойство reveal-offset задаёт зону у начала страницы, где шапка остаётся на месте. Событие @reveal сообщает о смене видимости, а фокус с клавиатуры внутри скрытой шапки показывает её обратно.

Sandbox Storybook

<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
import { ref } from 'vue';

const revealed = ref(true);
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader reveal elevated :reveal-offset="120" @reveal="revealed = $event">
        <CdsToolbar>
          <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 text-content-secondary">Шапка сейчас {{ revealed ? 'видна' : 'скрыта' }}</div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 20" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Блок {{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

Видимость

Свойство model-value убирает шапку целиком: макет перестаёт резервировать под неё место, и контент занимает освободившуюся высоту. Так удобно прятать шапку в полноэкранных режимах — просмотре документа, презентации.

Sandbox Storybook

<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
</script>

<template>
  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Шапка видна</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Контент страницы</div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">:model-value="false"</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader :model-value="false" bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Шапка скрыта — контент поднялся на её место
              </div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>
  </div>
</template>

Рекомендации

Storybook

Сценарии использования

Шапка приложения

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

Sandbox Storybook

<script setup lang="ts">
import {
  CdsAvatar,
  CdsBadge,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="64">
        <CdsToolbar class="h-[64px]">
          <CdsFunctionalButton icon="menu" class="mr-2" aria-label="Открыть навигацию" />
          <CdsAvatar icon="company" class="mr-2" />
          <CdsToolbarTitle>Портал закупок</CdsToolbarTitle>

          <CdsFunctionalButton icon="search" aria-label="Поиск" />
          <CdsBadge :content="3">
            <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
          </CdsBadge>
          <CdsAvatar icon="user" class="ml-2" />
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

Шапка с вкладками

Два CdsToolbar подряд превращают шапку в двухуровневую: сверху название раздела, снизу CdsTabs с подразделами. Вкладки остаются на экране вместе с шапкой, поэтому переключаться можно из любой точки списка.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsTab,
  CdsTabs,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('active');
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="96">
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
        </CdsToolbar>
        <CdsToolbar no-gutter="start">
          <CdsTabs v-model="tab">
            <CdsTab value="active">Активные</CdsTab>
            <CdsTab value="draft">Черновики</CdsTab>
            <CdsTab value="archive">Архив</CdsTab>
          </CdsTabs>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Вкладка: {{ tab }}</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
bgColor	string | undefined	—	Цвет фона компонента
bordered	boolean | undefined	false	Отображение границы.
color	string | undefined	—	Цвет компонента
elevated	boolean | undefined	false	Отображение тени.
height	string | number | undefined	50	Высота элемента.
modelValue	boolean | undefined	true	Видимость элемента в макете.
reveal	boolean | undefined	false	Плавающий режим: элемент появляется/скрывается при скролле.
revealOffset	number | undefined	250	Порог скролла (px), до которого плавающий элемент остаётся видимым.
theme	string | undefined	—	Тема компонента

События

Имя	Тип	Описание
focusin	[event: FocusEvent]	Фокус внутри шапки.
reveal	[value: boolean]	Изменение видимости плавающей шапки.

Слоты

Имя	Тип	Описание
default	any	Содержимое шапки (CdsToolbar и др.).