Код‑блоки в React с react-code-blocks

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

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

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

Создайте React‑приложение (например, через create-react-app) и установите библиотеку react-code-blocks через npm. Откройте терминал, перейдите в корень проекта и выполните:

npm install react-code-blocks

Это добавит react-code-blocks в зависимости проекта.

Важно: библиотека работает на клиенте; если вы используете серверный рендеринг (SSR), проверьте поведение подсветки и отложите рендеринг на клиентской стороне.

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

Импортируйте компонент CodeBlock и используйте его в вашем компоненте:

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

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

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

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

Пример с полным набором пропсов:

import { CodeBlock } from "react-code-blocks";  
  
function MyComponent() {  
  const handleClick = () => {  
    console.log("Code block clicked");  
  };  
  
  return (  
      
  );
}

В этом примере указана тема atom-one-dark, нумерация начинается с 10, lineNumbers выключен через codeBlock, включён перенос строк и добавлен обработчик клика.

Важно: конфликт между showLineNumbers и codeBlock.lineNumbers нужно учитывать — библиотека может отдавать приоритет одному из пропсов; проверяйте поведение в вашей версии.

Темы для код‑блоков

react-code-blocks включает набор встроенных тем (например, GitHub, atom-one-dark, dracula). Вы также можете передать объект темы для полного контроля над цветами.

Пример передачи встроенной темы:

Пример кастомной темы (объект с цветами):

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",  
};

React приложение с код-блоками и кастомной темой

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

Для читаемости выбирайте контрастный фон и текст.
Для печати используйте светлую тему или предоставьте переключатель темы.
Поддерживайте цветовые переменные, если тема должна наследоваться от дизайна приложения.

Добавление CopyBlock для копирования кода

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

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

npm install react-copy-to-clipboard

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

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)}  
/>

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

Рекомендации по UX копирования:

Покажите визуальную обратную связь при копировании (например, короткое уведомление или смена иконки).
Ограничьте частые срабатывания онкопии для минимизации ложных срабатываний.
Для больших фрагментов кода можно копировать только выделенный фрагмент.

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

Ручная подсветка через CSS

Подходит, если вы хотите полный контроль и минимальные зависимости.
Минус: придётся поддерживать правила подсветки и парсинг токенов вручную или использовать статические HTML‑фрагменты.

Библиотеки подсветки

react-syntax-highlighter: простая интеграция, много готовых тем.
prism-react-renderer: фокус на производительности и гибкости рендеринга.
highlight.js: проверенная и распространённая библиотека с большим набором языков.

Выбор зависит от объёма кода, требований к размеру бандла и необходимости SSR.

Когда подход с react-code-blocks не работает

Если требуется серверная подсветка при SSR, поведение может отличаться.
Для экстремально больших фрагментов кода (десятки тысяч строк) производительность клиентской подсветки может быть проблемой.
Если нужен потоковый рендеринг или редактор кода с полнофункциональным автодополнением — лучше использовать редакторы вроде Monaco Editor.

Доступность и международзация

Всегда обеспечивайте альтернативный текст и семантику: оборачивайте код в
/
при необходимости.
Поддерживайте клавиатурный доступ к кнопке копирования (tabIndex, aria-label).
Для локали указывайте текст подсказок и сообщения об успешном копировании на нужном языке.

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

aria-label для кнопки копирования.
уведомление о результате копирования (роль status или aria-live).
хорошая контрастность темы.

Тестирование и критерии приёмки

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

Код отображается с подсветкой в целевых браузерах.
Номера строк корректно соответствуют начальной строке и опциям wrapLines.
Кнопка копирования копирует ожидаемый текст и даёт обратную связь.
Компоненты корректно рендерятся при переключении тем.
Производительность в пределах приемлемого времени загрузки страницы.

Примеры тестов/acceptance:

Юнит: компонент рендерит переданный проп text.
Интеграция: клик на иконку копирования вызывает callback и помещает текст в буфер обмена.
E2E: при большом числе строк страница не зависает при прокрутке и подсветке.

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

Для разработчика:

Установлена зависимость react-code-blocks.
Покрыты кейсы с wrapLines и lineNumbers.
Реализован fallback для SSR.
Добавлен юнит‑тест на копирование.

Для дизайнера:

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

Для продуктового менеджера:

Описан сценарий использования (документация, туториал).
Проверено локализованное сообщение об успешном копировании.

Шпаргалка и шаблоны

Быстрая вставка CodeBlock:

Шаблон кастомной темы:

const theme = {
  backgroundColor: '#fff',
  textColor: '#333',
  keywordColor: '#07f',
  stringColor: '#070',
};

Матрица совместимости и миграции

React 16.8+: подходит (hooks).
SSR (Next.js): проверьте, что подсветка выполняется на клиенте или используйте динамический импорт без SSR.
Размер бандла: если важен вес сборки, сравните с prism-react-renderer и highlight.js по итоговому размеру.

Модель принятия решения

Mermaid диаграмма для выбора решения:

flowchart TD
  A[Нужны код-блоки] --> B{Нужна ли копия кода}
  B -- Да --> C[react-code-blocks + CopyBlock]
  B -- Нет --> D{Нужна ли SSR-совместимость}
  D -- Да --> E[prism + серверная подсветка]
  D -- Нет --> F[prism-react-renderer или react-syntax-highlighter]

Практические рекомендации и лучшие практики

Предлагайте переключатель темы (тёмная/светлая) для удобства пользователей.
Контролируйте длину линий: включайте wrapLines для адаптивности на мобильных устройствах.
Минимизируйте зависимости: если нужен только статический подсвет, отдайте предпочтение лёгким библиотекам.
Обрабатывайте большие блоки кода ленивой загрузкой.

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

Вставляйте компактные демонстрации и ссылку на полный пример в sandboxes (CodeSandbox, StackBlitz).
Для интерактивных примеров используйте iframe или интеграцию с runnable playground.

Итоговая сводка

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

Важно: проверяйте поведение props showLineNumbers и codeBlock.lineNumbers в вашей версии пакета.

Summary:

react-code-blocks удобен для большинства документов и интерфейсов.
Добавление CopyBlock улучшает UX для разработчиков.
Кастомные темы дают контроль над внешним видом, но тестируйте контраст и доступность.

Если нужно, могу подготовить готовый компонент-обёртку с переключателем темы, доступностью и тестами для вашего репозитория.