Подсветка кода в React с react-code-blocks

Ноутбук на столе с открытым редактором кода.

Коротко о назначении: блоки кода помогают демонстрировать сниппеты, повышать читабельность технической документации и повышать вовлечённость пользователей. Этот материал ведёт от установки до продвинутой настройки и тестирования.

Установка библиотеки

Создайте React‑приложение (например, с помощью Create React App или Vite).
Установите пакет react-code-blocks через npm или yarn.

Обычная команда для npm:

npm install react-code-blocks

Если вы предпочитаете yarn:

yarn add react-code-blocks

После установки откройте проект в терминале и убедитесь, что зависимости установлены без ошибок.

Важно: версия Node.js и менеджера пакетов должна соответствовать требованиям вашего проекта. Если в проекте строгие зависимости, используйте lock‑файл (package-lock.json или yarn.lock) для воспроизводимости.

Добавление CodeBlock в проект

Импортируйте компонент CodeBlock и вставьте его в нужный компонент React. Пример импорта:

import { CodeBlock } from "react-code-blocks";

Простейший пример использования:

Пояснение основных пропсов:

text (обязательно): строка с кодом для отображения.
language (обязательно): язык для подсветки (например, ‘javascript’, ‘python’).
showLineNumbers: булево, показывает номера строк (по умолчанию false).
theme: встроенное имя темы или объект с цветами.
startingLineNumber: число, с которого начинаются номера строк (по умолчанию 1).
codeBlock: объект опций (например, { lineNumbers: false, wrapLines: true }).
onClick: функция обработчика клика по блоку.

Полный пример компонента с обработчиком клика:

import { CodeBlock } from "react-code-blocks";

function MyComponent() {
  const handleClick = () => {
    console.log("Code block clicked");
  };

  return (
    
  );
}

В этом примере используются следующие настройки: тема atom‑one‑dark, номера строк начинаются с 10, включено перенесение строк и добавлён обработчик клика.

Темы и пользовательская стилизация

react-code-blocks поставляется с набором встроенных тем. Чтобы применить тему, передайте её имя в проп theme:

Для полной кастомизации можно передать объект темы. Пример структуры объекта темы (параметры — цвета CSS):

const myCustomTheme = {
  lineNumberColor: "#ccc",
  lineNumberBgColor: "#222",
  backgroundColor: "#222",
  textColor: "#ccc",
  substringColor: "#00ff00",
  keywordColor: "#0077ff",
  attributeColor: "#ffaa00",
  selectorTagColor: "#0077ff",
  docTagColor: "#aa00ff",
  nameColor: "#f8f8f8",
  builtInColor: "#0077ff",
  literalColor: "#ffaa00",
  bulletColor: "#ffaa00",
  codeColor: "#ccc",
  additionColor: "#00ff00",
  regexpColor: "#f8f8f8",
  symbolColor: "#ffaa00",
  variableColor: "#ffaa00",
  templateVariableColor: "#ffaa00",
  linkColor: "#aa00ff",
  selectorAttributeColor: "#ffaa00",
  selectorPseudoColor: "#aa00ff",
  typeColor: "#0077ff",
  stringColor: "#00ff00",
  selectorIdColor: "#ffaa00",
  quoteColor: "#f8f8f8",
  templateTagColor: "#ccc",
  deletionColor: "#ff0000",
  titleColor: "#0077ff",
  sectionColor: "#0077ff",
  commentColor: "#777",
  metaKeywordColor: "#f8f8f8",
  metaColor: "#aa00ff",
  functionColor: "#0077ff",
  numberColor: "#ffaa00",
};

Передача объекта темы в компонент:

Советы по теме:

Для соответствия дизайну приложения подготовьте палитру из 4–6 цветов: фон, основной текст, акцент, комментарии и номера строк.
Проверяйте контрастность на соответствие WCAG, особенно если ваша аудитория включает людей с нарушениями зрения.

Приложение React с блоками кода и пользовательской темой.

Компонент CopyBlock: добавление кнопки «Копировать»

Для удобства пользователей можно добавить кнопку копирования. Для этого используйте компонент CopyBlock и пакет react-copy-to-clipboard.

Установка зависимостей:

npm install react-copy-to-clipboard

Импорт и использование CopyBlock:

import { CopyBlock } from 'react-code-blocks';
import { FaCopy } from 'react-icons/fa';
import copy from 'copy-to-clipboard';

const code = 'console.log("Hello, world!");';
const language = 'javascript';

}
  onCopy={() => copy(code)}
/>

CopyBlock предоставляет UI‑элемент с иконкой и обработчиком onCopy. Вы можете заменить иконку, добавить подсказки (tooltip) и логирование событий для аналитики.

Приложение React с кодблоком и кнопкой копирования.

Альтернативные подходы и когда их выбирать

Ниже перечислены альтернативы и краткие руководства, когда их использовать:

Самостоятельная стилизация (CSS/Tailwind): полезно, если нужен строгий контроль над разметкой и нет желания тащить внешнюю библиотеку. Несколько больше работы и требует поддержки правил подсветки.
react-syntax-highlighter: хорош для широкого набора тем и частых языков, поддерживает SSR. Выбор, если важна совместимость с серверной рендерингом.
prism-react-renderer: гибкая библиотека с возможностью создавать свои рендереры и интегрироваться с MDX/статикой.
highlight.js: зрелая библиотека с множеством языков, полезна для простых сайтов без React.

Когда не стоит использовать react-code-blocks:

Если вы хотите минимизировать размер бандла до абсолютного минимума и готовы реализовать подсветку вручную.
Если вам требуется рендеринг на сервере с детальными требованиями по подсветке (проверьте совместимость с SSR).

Проверка совместимости и миграционные заметки

Поддержка SSR: уточните в документации библиотеки текущую поддержку серверного рендеринга. Некоторые темы/функции могут полагаться на DOM.
Версии React: проверьте peerDependencies в package.json пакета.
Совместимость с CSS‑фреймворками: при наложении глобальных стилей (например, Tailwind) может потребоваться дополнительная изоляция стилей (CSS‑модули, shadow DOM или уникальные классы).

Производственные рекомендации и безопасность

Содержимое пропа text должно быть доверенным или пройденным через экранирование, если вы динамически вставляете пользовательский ввод.
Ограничьте доступ к функциям onCopy, если логируете содержимое snippet’ов в аналитике (политика конфиденциальности).
Тестируйте на мобильных устройствах: убедитесь, что перенос строк и размеры шрифта комфортны.

Мини‑методология выбора подхода (шаги)

Определите требования: нужен ли копируемый код, номера строк, тёмная тема, SSR?
Оцените ограничения: размер бандла, требуемые языки, поддержка браузеров.
Выберите базовую библиотеку (react-code-blocks или альтернатива).
Настройте тему и протестируйте контрастность и читаемость.
Напишите тесты (см. ниже) и прописывайте критерии приёмки.
Разверните и мониторьте метрики использования (копирования, кликов).

Чек‑лист по ролям

Разработчик:

Установил пакет и зависимости.
Добавил компонент с требуемыми пропсами.
Проверил работу на основных браузерах.
Покрыл компонент unit‑/integration‑тестами.

Дизайнер:

Согласовал тему (цвета текста, фон, акценты).
Проверил контрастность и масштаб шрифта.
Утвердил иконки и поведение hover/active.

Контент‑редактор / технический писатель:

Убедился, что сниппеты корректны и читаемы.
Обновил инструкции по копированию и лицензии кода, если требуется.

Тест‑кейсы и критерии приёмки

Критерии приёмки:

Компонент отображает код с подсветкой для как минимум трёх языков (JS, Python, CSS).
Номера строк корректно отображаются и принимают значение startingLineNumber.
CopyBlock копирует точный текст и вызывает onCopy.
Темы применяются и переключаются без перезагрузки.
Компонент корректно рендерится на мобильных ширинах и при уменьшенном размере шрифта.

Примеры тест‑кейсов:

Открыть страницу с CodeBlock и проверить, что строка с ключевым словом «function» подсвечивается.
Нажать на кнопку копирования — проверить буфер обмена (e2e) и отсутствие лишних пробелов.
Проверить, что при wrapLines={true} длинные строки перенеслись и не вылезают за контейнер.

Шаблоны и сниппеты (cheat sheet)

Простой шаблон компонента обёртки для повторного использования:

import { CodeBlock } from "react-code-blocks";

export default function Snippet({ code, lang = 'javascript', theme }) {
  return (
    
      
    
  );
}

Паттерн для логирования копирования (без сохранения содержимого):

const handleCopy = (code) => {
  // Аналитика: фиксируем факт копирования, но не содержимое
  analytics.track('code_copied', { length: code.length, language: lang });
};

Отладка и распространённые проблемы

Проблема: номера строк не отображаются — проверьте prop showLineNumbers и свойство codeBlock.lineNumbers.
Проблема: тема не применяется — убедитесь, что theme передаётся либо как строка с поддерживаемым именем, либо как корректный объект.
Проблема: конфликт CSS (шрифты/отступы) — используйте изоляцию стилей (CSS‑модули) или контейнер с собственными стилями.

Краткое резюме

Использование react-code-blocks даёт простую и гибкую основу для отображения блоков кода в React. Библиотека поддерживает встроенные темы, пользовательские темы и компонент CopyBlock для копирования в буфер обмена. Выбор между react-code-blocks и альтернативами зависит от требований по размеру бандла, поддержке SSR и гибкости кастомизации.

Ключевые рекомендации: