Подсветка кода

Подсветка кода раскрашивает синтаксис в блоках pre code и оформляет их поверхностью с панелью: название языка и кнопка копирования. Берите её для примеров кода в документации и интерфейсах разработчика; короткий идентификатор в тексте оставляйте обычным элементом code.

Пример

<button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1">
  <span class="sf-button-text-container">Сохранить</span>
</button>

<pre><code data-lang="html">&lt;button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1"&gt;
  &lt;span class="sf-button-text-container"&gt;Сохранить&lt;/span&gt;
&lt;/button&gt;</code></pre>

Разметка

Минимальную разметку показывает пример выше: <pre><code data-lang="html"> с текстом кода. Скрипт сам строит вокруг него оболочку sf-highlight sf-code-surface, панель и прокрутку; писать их вручную не нужно.

• Язык задаёт data-lang или класс language-* на code. В наборе: xml (он же html), css, scss, javascript (js), typescript (ts), json, bash (sh, shell), php, python, sql, yaml (yml), markdown (md), blade, dotenv (env), 1c и plaintext (text).
• Пробелы и пустые строки в начале и в конце кода скрипт убирает.
• Код внутри code экранируйте: < вместо <.
• Блок прокручивается по горизонтали и не переносит длинные строки; код всегда идёт слева направо, даже на странице с письмом справа налево.

Варианты

Панель

data-chrome на code или на оболочке задаёт панель над кодом: auto (по умолчанию) — название языка и кнопка копирования; none — только код, для коротких фрагментов внутри текста; static — без панели и без обёртки прокрутки, когда страница строит их сама.

.card {
  padding: var(--sf-space-2);
}

.card {
  padding: var(--sf-space-2);
}

<div class="grid grid-col-1 gap-3">
  <div class="flex flex-col gap-1">
    <pre><code data-lang="css">.card {
  padding: var(--sf-space-2);
}</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-chrome="auto" — по умолчанию</code>
  </div>
  <div class="flex flex-col gap-1">
    <pre><code data-lang="css" data-chrome="none">.card {
  padding: var(--sf-space-2);
}</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-chrome="none"</code>
  </div>
</div>

Номера строк

data-lines на code нумерует строки: каждая строка становится рядом, где номер стоит в своей колонке, а код — рядом с ним. data-lines="false" выключает нумерацию. Нумерация начинается с единицы; data-start задаёт номер первой строки, чтобы отрывок из длинного файла показывал его настоящие номера. Номера не выделяются вместе с кодом: выделенный и скопированный фрагмент содержит только код.

.card {
  padding: var(--sf-space-2);
  border-radius: var(--sf-radius-1);
}

export function total(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

<div class="grid grid-col-1 gap-3">
  <div class="flex flex-col gap-1">
    <pre><code data-lang="css" data-lines>.card {
  padding: var(--sf-space-2);
  border-radius: var(--sf-radius-1);
}</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-lines — номера строк с единицы</code>
  </div>
  <div class="flex flex-col gap-1">
    <pre><code data-lang="js" data-lines data-start="41">export function total(items) {
  return items.reduce((sum, item) =&gt; sum + item.price, 0);
}</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-lines data-start="41" — отрывок с 41-й строки файла</code>
  </div>
</div>

Язык

Язык из набора подсвечивается его грамматикой. Если языка нет в наборе или он не указан, код выводится обычным текстом без подсветки, а панель показывает имя, которое указано в data-lang. Атрибут data-highlight-state на оболочке принимает значения ready и unsupported.

const total = items.reduce((sum, item) => sum + item.price, 0);

total := price * count

<div class="grid grid-col-1 gap-3">
  <div class="flex flex-col gap-1">
    <pre><code data-lang="js">const total = items.reduce((sum, item) =&gt; sum + item.price, 0);</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-lang="js" — язык из набора</code>
  </div>
  <div class="flex flex-col gap-1">
    <pre><code data-lang="go">total := price * count</code></pre>
    <code class="text-1/2 color-on-surface-variant">data-lang="go" — языка нет в наборе: обычный текст</code>
  </div>
</div>

Доступность

• Кнопка копирования получает имя «Копировать код» на языке страницы, а результат зачитывает скрытая область статуса. Свои слова задают data-copy-label и data-copy-success на code или на оболочке.
• Область прокрутки получает фокус с клавиатуры: длинную строку можно прочитать стрелками.
• Номера строк скрыты от вспомогательных технологий: код зачитывается без них.
• Не передавайте смысл только цветом подсветки: код читается и без неё.
• В режиме высокой контрастности поверхность получает рамку системного цвета текста.

JavaScript

Скрипт подсвечивает блоки pre code при загрузке страницы и блоки, добавленные позже. Объект SF.Highlight даёт две функции:

• SF.Highlight.highlight(code) — подсвечивает один элемент code, если он ещё не подсвечен; возвращает обещание с true.
• SF.Highlight.refresh(target, source) — подсвечивает заново все блоки внутри target; если передана строка source, она становится новым текстом кода. Возвращает обещание со списком блоков.

const block = document.querySelector('#snippet');
await SF.Highlight.refresh(block, 'const total = price * count;');

Событий компонент не отправляет. Движок подсветки доступен как window.hljs; компонент регистрирует его под именем hljs, и SF.Loader.ready('hljs', callback) вызывает функцию, когда он зарегистрирован. SF.Loader появляется к событию sf-loader-init на window.

Классы

sf-highlight

sf-code-surface

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

Переменные

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

См. также

• Копирование
• Документ