Runtime API

MDX Runtime API предоставляет функциональные возможности для работы с документами MDX на этапе выполнения, позволяя динамически рендерить контент, управлять компонентами и интегрировать JSX внутри Markdown. Runtime API работает поверх стандартного процесса компиляции MDX в JavaScript, обеспечивая гибкость и контроль над содержимым в реальном времени.

Функция mdx

mdx — это основная функция Runtime API, которая служит точкой входа для рендеринга MDX-контента. Она позволяет создавать React-элементы из Markdown с включённым JSX.

Сигнатура функции:

import { mdx } from '@mdx-js/react';

const element = mdx('h1', { id: 'title' }, 'Заголовок');
  • Первый аргумент — тип элемента, например 'h1', 'p' или компонент React.
  • Второй аргумент — props элемента, включая стандартные HTML-атрибуты и пользовательские свойства.
  • Третий и последующие аргументы — дети элемента, текст или вложенные элементы.

Ключевое преимущество функции mdx заключается в её универсальности: можно использовать как стандартные HTML-теги, так и произвольные React-компоненты, передавая их напрямую.

Компоненты MDXProvider

MDXProvider позволяет задавать сопоставления между тегами Markdown и пользовательскими React-компонентами. Это критически важно для Runtime API, так как компоненты, переданные через провайдер, используются функцией mdx при рендеринге.

import { MDXProvider } from '@mdx-js/react';

const components = {
  h1: (props) => <h1 style={{ color: 'blue' }} {...props} />,
  a: (props) => <a target="_blank" rel="noopener noreferrer" {...props} />
};

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>
  • Все элементы MDX будут автоматически заменены на компоненты из объекта components.
  • Позволяет задавать единый стиль для документа без изменения исходного MDX-файла.

Работа с контентом через MDXContent

MDXContent — это React-компонент, сгенерированный MDX-компилятором, который использует Runtime API для рендеринга документа.

import MDXContent from './content.mdx';

<MDXContent components={components} />
  • components — объект компонентов, аналогичный использованию в MDXProvider.
  • Позволяет динамически менять рендеринг на лету без перекомпиляции MDX.

Использование функции useMDXComponents

useMDXComponents — хук, предоставляющий доступ к текущему набору компонентов, заданных через MDXProvider. Позволяет переопределять или расширять компоненты на уровне отдельных частей приложения.

import { useMDXComponents } from '@mdx-js/react';

function CustomLink(props) {
  const components = useMDXComponents({ a: MyLink });
  return <components.a {...props} />;
}
  • Аргумент функции — объект с локальными компонентами, который объединяется с глобальными.
  • Полезно для динамической подстановки компонентов внутри сложных приложений.

Динамическая вставка JSX

Runtime API MDX позволяет использовать JSX прямо внутри Markdown-контента, что особенно удобно для интерактивных элементов.

# Пример кнопки

<CustomButton onCl ick={() => alert('Нажато!')}>Кликни меня</CustomButton>
  • JSX обрабатывается функцией mdx на этапе рендеринга.
  • Можно интегрировать любые React-компоненты, включая те, которые зависят от состояния или контекста.

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

MDX Runtime API поддерживает передачу дополнительных пропсов в компоненты через components и MDXContent.

<MDXContent components={{ Button: (props) => <Button color="red" {...props} /> }} />
  • Все MDX-теги заменяются на компоненты с заданными пропсами.
  • Поддерживается использование контекста React для передачи состояния в компоненты MDX.

Обработка динамического контента

Runtime API облегчает работу с контентом, загружаемым на лету. Можно хранить MDX-тексты в базе данных и рендерить их без предварительной компиляции на стороне сервера.

import { mdx } from '@mdx-js/react';
import { createElement } from 'react';

const content = `
# Динамический заголовок
Пример **MDX** текста с JSX:

<CustomButton>Кнопка</CustomButton>
`;

const element = mdx('div', null, createElement('h1', null, 'Динамический заголовок'));
  • Возможность комбинировать статический и динамический контент.
  • Позволяет создавать CMS на базе MDX без необходимости перекомпиляции файлов.

Объект runtime и расширения

Некоторые реализации MDX Runtime API предоставляют объект runtime для глобальных настроек, регистрации плагинов и управления обработкой MDX.

import { runtime } from '@mdx-js/runtime';

runtime.use(pluginExample);
  • Позволяет интегрировать парсеры, трансформеры и плагины.
  • Используется для кастомизации обработки Markdown на лету.

MDX Runtime API обеспечивает полный контроль над рендерингом Markdown с JSX, делает возможным динамическое внедрение компонентов и управляемую интеграцию с React, что открывает широкие возможности для создания интерактивного, настраиваемого контента в приложениях.

Оглавление