Документ

Компонент оформляет служебные поверхности технической документации: область примера, исходный код под ней, вводный абзац и фоны для показа прозрачности. Берите его для страниц документации и витрин компонентов; для карточек документов в прикладном интерфейсе нужны обычные поверхности и компоненты действий.

Пример

<div class="sf-doc-example">
  <p class="m-0">Демонстрационная область: здесь показывают результат примера.</p>
</div>

Разметка

Минимальную разметку показывает пример выше: блок sf-doc-example с содержимым примера. Классы компонента независимы, и каждый ставится на свой элемент:

• sf-doc-example — область примера: заливка, граница, радиус поверхности и внутренний отступ. Если перед ней есть содержимое, она получает отступ сверху.
• sf-doc-pair — обёртка пары «пример и исходник»: не даёт содержимому выйти за ширину колонки.
• sf-doc-source — блок исходного кода на тёмной поверхности с прокруткой.
• sf-doc-lead — вводный абзац.
• sf-doc-checkerboard и sf-doc-stripes — служебные фоны.
• sf-doc-code — моноширинный шрифт для встроенного фрагмента кода, как у элемента code.

У компонента нет своего JavaScript: подсветку кода выполняет Highlight, копирование — Clipboard.

Варианты

Вводный текст

sf-doc-lead набирает абзац крупным текстом второстепенного цвета: так выделяют назначение раздела перед подробным содержимым.

<div class="flex flex-col gap-1">
  <p class="sf-doc-lead m-0">Вводный абзац выделяет назначение раздела перед подробным содержимым.</p>
  <code class="text-1/2 color-on-surface-variant">sf-doc-lead</code>
</div>

Результат и исходник

В sf-doc-pair за sf-doc-example следует <pre class="sf-doc-source">: нижние углы примера и верхние углы исходника становятся прямыми, и два блока читаются как одно целое.

<div class="sf-doc-example">Результат выполнения примера</div>

<div class="sf-doc-pair">
  <div class="sf-doc-example">Результат выполнения примера</div>
  <pre class="sf-doc-source"><code>&lt;div class=&quot;sf-doc-example&quot;&gt;Результат выполнения примера&lt;/div&gt;</code></pre>
</div>

Служебный фон

sf-doc-checkerboard — шахматный фон, на котором видна прозрачность изображения или цвета; sf-doc-stripes — полосатый фон, который отмечает служебную или пустую область. Оба фона строятся из ступеней поверхности и читаются в обеих темах.

<div class="grid grid-col-1 md:grid-col-2 gap-3">
  <div class="flex flex-col gap-1">
    <div class="sf-doc-example sf-doc-checkerboard">Шахматный фон показывает прозрачность.</div>
    <code class="text-1/2 color-on-surface-variant">sf-doc-checkerboard</code>
  </div>
  <div class="flex flex-col gap-1">
    <div class="sf-doc-example sf-doc-stripes">Полосатый фон выделяет служебную область.</div>
    <code class="text-1/2 color-on-surface-variant">sf-doc-stripes</code>
  </div>
</div>

Доступность

• Компонент только оформляет: заголовки, подписи и порядок чтения задаёт разметка страницы.
• Длинный исходник прокручивается внутри блока; дайте ему видимую подпись или заголовок, если на странице несколько примеров.
• Служебный фон декоративный: не передавайте им смысл, который нужно прочитать.
• В режиме высокой контрастности области и фоны получают рамку системного цвета текста, а узор заменяется системным фоном.

Классы

Классы и переменные собраны из CSS выпуска и обновляются вместе с ним.

Переменные

Компонент читает свои переменные, а модификаторы задают им значения; таблица показывает, из чего складывается вид. Переменные компонента — его внутренняя проводка, а не поверхность настройки: их имена и устройство могут меняться. Вид проекта меняют общие токены, а глубокий вид Smart-компонента — его шаблон (см. Переменные компонента). Значение по умолчанию — из базового правила блока (.sf-doc); переменную без него задают только модификаторы.

См. также

• Подсветка кода
• Копирование