Интерактивный пример

Блок помещает рядом готовый результат и его исходник. Читатель может переключить вкладку, проверить поведение и скопировать точный вызов.

Общий пример

:badge[Готово]{type=main scheme=success size=1/2}

Параметр label задаёт понятное название вкладки с результатом.

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

У изолированного результата на вкладке «Пример» есть одна кнопка проверки адаптивности. Она открывает режим просмотра, где можно выбрать десктоп 1280 px, планшет 768 px или телефон 390 px. Меняется настоящая ширина iframe, поэтому медиазапросы примера реагируют так же, как в отдельном окне. Кнопка выхода и клавиша Escape возвращают обычную ширину статьи.

Во встроенном результате кнопки нет: сужение внутреннего блока не изменило бы ширину окна браузера и показало бы неверный результат. Если странице нужна проверка размеров, укажите preview=sandbox. На телефоне кнопка скрывается — пример уже занимает доступную мобильную ширину.

<article class="adaptive-card">
  <strong>Карточка товара</strong>
  <span>Цена и действие меняют расположение на телефоне.</span>
  <button type="button">В корзину</button>
</article>

.adaptive-card {
  display: grid;
  grid-template-columns: 1fr auto;
  gap: 1rem;
  align-items: center;
  padding: 1rem;
  border: 1px solid currentColor;
  border-radius: 1rem;
}

.adaptive-card span {
  grid-column: 1;
}

.adaptive-card button {
  grid-column: 2;
  grid-row: 1 / span 2;
}

@media (max-width: 600px) {
  .adaptive-card {
    grid-template-columns: 1fr;
  }

  .adaptive-card button {
    grid-column: 1;
    grid-row: auto;
  }
}

На любой вкладке исходника доступен мягкий перенос длинных строк. Он меняет только отображение через CSS: байты исходника и результат копирования остаются неизменными. Значок показывает следующее действие — включить перенос или вернуться к исходным строкам. Рамка фокуса предназначена для клавиатурной навигации и не появляется после щелчка мышью. Выбор синхронизируется с обычными блоками кода и сохраняется в браузере.

Обе возможности включены встроенными настройками Docara. Их можно отключить для всего сайта, раздела или страницы:

{
  "examples": {
    "fullscreen": false,
    "wrap": false
  }
}

Ближайший уровень имеет приоритет: встроенное значение → docara.json → section.json → <page>.page.json. Конкретный блок может сделать последнее переопределение:

:::example {label="Компактный пример" fullscreen=false wrap=false}
```markdown
Текст примера
```
:::

Параметры управляют наличием кнопок, а не выбранной шириной или состоянием переноса. Название fullscreen сохранено для совместимости конфигурации; оно включает режим проверки адаптивности.

Способ показа

По умолчанию preview="auto": Docara во время сборки выбирает способ показа по исходникам примера. Markdown и безопасный HTML без собственных стилей и сценариев встраиваются прямо в страницу. Пример с CSS, JavaScript или конструкцией, которую нельзя надёжно встроить, открывается в изолированном iframe. Решение детерминировано и не меняется в браузере. Общие примеры из папки examples/ подчиняются тому же правилу, что и примеры, написанные прямо на странице.

Если разметка использует утилиты с префиксом контрольной точки (sm:, md:, lg:, xl:, xxl:) или контейнерного запроса (cq-sm:, cq-md/sidebar:), пример открывается в iframe с причиной responsive_utilities. Такие утилиты зависят от ширины окна или контейнера, а встроенный пример видел бы только ширину страницы документации. В iframe доступна кнопка «Проверить адаптивность» с шириной десктопа, планшета и телефона. Названия контрольных точек Docara берёт из реестра утилит закреплённой версии Framework. Если нужно показать такой пример прямо в странице, укажите preview=inline: эта разметка безопасна, поэтому выбор автора сохраняется.

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

Во встроенном HTML допускаются:

• атрибуты data-*, кроме data-docara-*, которые принадлежат оболочке Docara. Значение атрибута не может начинаться со схем javascript:, vbscript: или data:;
• id в kebab-case хотя бы с одним дефисом, например save-tooltip, и не начинающийся с docara-;
• атрибут slot с простым значением в kebab-case, например content или footer: он только указывает, какую часть Smart-компонента заполняет элемент;
• элемент form без action, method, target, enctype и name. Отправку такой формы Docara отменяет, поэтому кнопка submit не перезагружает страницу документации, а reset работает как обычно;
• у Smart-элементов sf-* — атрибуты, которые lock Framework проекта объявляет для этого тега. Если список пуст, допускаются только общие атрибуты.

Никогда не встраиваются атрибуты on*, href, src, srcdoc, style, action, formaction, атрибут form, autofocus и contenteditable, даже если lock их объявляет, а также элементы script, style, link, iframe, a, img и другие элементы вне списка. Такой пример остаётся в iframe.

id встроенного примера живёт в общем пространстве страницы. Якоря заголовков сами обходят уже занятые id, а любое другое совпадение — со вторым примером, повторным использованием того же общего примера или элементом оболочки — останавливает сборку ошибкой MARKDOWN_EXAMPLE_INLINE_ID_DUPLICATE с именем id, примера и страницы. Переименуйте id или закрепите preview=sandbox.

Способ можно закрепить явно:

:::example {label="Встроенный результат" preview=inline}
```html
<button class="sf-button" type="button">Продолжить</button>
```
:::

:::example {label="Изолированный результат" preview=sandbox}
```html
<strong>Самостоятельный пример</strong>
```
:::

preview=inline не отключает защиту: если пример требует изоляции, сборка остановится с понятной диагностикой. Используйте этот режим для небольших примеров на классах Framework. preview=sandbox нужен, когда важны собственные стили, сценарии или независимое окружение. Выбранный режим и причина записываются в .docara/examples.json и доступны через inspect page.

Общий пример из проекта

Если один и тот же пример нужен на нескольких страницах или во всех локалях, храните его один раз в корневой папке examples/:

examples/
  utilities/
    animation-duration/
      index.html
      index.css
      index.js
      assets/

index.html обязателен. CSS, JavaScript и assets/ добавляются только при необходимости. Путь каталога становится стабильным идентификатором:

:::example {id="utilities/animation-duration" label="Результат"}
:::

Docara автоматически показывает только существующие вкладки, публикует разрешённые assets с учётом base_url и записывает зависимости в .docara/examples.json. Общий пример, у которого есть только index.html и разметка проходит правила встраивания, показывается прямо в странице; пример с index.css или index.js остаётся в iframe, и preview=inline для него завершит сборку ошибкой. У блока должен быть либо id, либо встроенный код — смешивать оба способа нельзя. После изменения общего примера выполните полную сборку: точечная сборка специально остановится, чтобы не оставить другие страницы со старой версией примера.

Sandbox получает тот же заранее собранный Framework CSS, что и страница документации. Если JavaScript добавляет классы, которых нет в начальном HTML, перечислите их семейства на корневом элементе через штатный data-sf-require. Планировщик учитывает это требование только у исполняемого примера; кодовые фрагменты в тексте страницы не расширяют набор ресурсов.

Пример также получает текущую тему, направление письма и безопасный снимок семантических --sf-* токенов основной страницы. Поэтому типографика, интервалы, радиусы и роли цветов соответствуют окружающей документации, даже если ширина iframe попадает в другой адаптивный диапазон. Текст в iframe набирается тем же семейством шрифтов, что и встроенный пример. Файлы шрифтов Docara передаёт в iframe сама, поэтому хостингу не нужны заголовки CORS. При этом передаются только начертания, которые нужны символам примера: для русского и английского текста — латиница и кириллица. Если файл передать не удалось, iframe использует локальный запасной шрифт из того же набора. Каждый файл шрифта передаётся в iframe один раз, а не при каждой смене темы или ширины окна. Шрифты иконок, самые тяжёлые из них, iframe получает, только если пример действительно показывает иконки: в своей разметке или внутри Smart-компонента. Сначала передаётся облегчённый набор частых иконок, а полный шрифт иконок, около 4 МБ, — только если пример показывает иконку, которой в этом наборе нет. Документ iframe получает язык и направление письма страницы, а его заголовок совпадает с подписью примера. Пример без label называется «Пример» — строкой examples.example из lang.json. Внутренняя прокрутка отключена: вкладка «Результат» раскрывает iframe на полную фактическую высоту примера, а прокруткой управляет страница документации. Высота синхронизируется без второй анимации оболочки, поэтому интерактивное содержимое не меняет доступную ширину при раскрытии.

iframe примера загружается, только когда приближается к экрану (за 600 px до видимой области); iframe в скрытой вкладке ждёт, пока вкладку откроют. Поэтому примеры ниже первого экрана не замедляют загрузку страницы. Документ iframe до этого хранится в атрибуте data-docara-srcdoc; браузерная проверка, которая ждёт загрузки всех примеров, должна прокрутить страницу к каждому iframe[loading="lazy"].

HTML, CSS и JavaScript

Для небольшого автономного интерфейса объедините HTML с необязательными CSS и JavaScript. Такой результат автоматически выполняется в изолированном iframe и не получает доступ к странице документации.

<button class="example-button" type="button">Нажмите</button>
<output class="example-result">Готово</output>

:root { color-scheme: light dark; }
body { color: CanvasText; background: Canvas; }
.example-button { padding: .5rem 1rem; }
.example-result { margin-inline-start: 1rem; }

document.querySelector('.example-button').addEventListener('click', () => {
  document.querySelector('.example-result').textContent = 'Выполнено';
});

Вызов

:::example {label="Пример"}
```markdown
:badge[Готово]{type=main scheme=success size=1/2}
```
:::

Markdown-пример использует ровно один исходник. Для интерфейсного примера обязателен HTML; CSS и JavaScript добавляйте только когда они нужны результату. Высота результата и исходников подстраивается при переключении вкладок, поэтому короткий пример не резервирует место под самую длинную вкладку.