Руководство по интеграции интерактивных диаграмм русалки

Last updated on Jun 24, 2026 01:48

Введение

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

Вместо того, чтобы полагаться на тяжелые статические файлы изображений, недоступные для поиска, или медленные сторонние CDN, которые увеличивают задержку страницы и ухудшают конфиденциальность, PolyCMS интегрирует собственный конвейер рендеринга Self-Hosted Mermaid.js. В этом руководстве рассказывается, как динамически компилируются диаграммы, знакомится с элементом интерактивного визуального редактора TipTap и демонстрируются четыре примера диаграмм, начиная от простых потоков и заканчивая общей архитектурой PolyCMS.

Техническая архитектура и автономная стратегия

PolyCMS создан для скорости и абсолютной независимости. Основной модуль рендеринга динамически анализирует необработанные элементы блока. Когда блок помечен как диаграмма:

Обнаружение парсера: динамический механизм PHP (helpers.php) сканирует стандартные блоки Markdown, начинающиеся с <pre><code class="language-mermaid">.
Безопасное декодирование объектов: безопасно декодирует объекты HTML (e.g. преобразует --> обратно в необработанный синтаксис -->, готовый к синтаксическому анализатору.
Автономные ресурсы: вместо запроса jsDelivr или cdnjs PolyCMS разрешает скрипт локально через помощник Laravel asset('assets/vendor/mermaid-10.x/mermaid.min.js').
Переменные темы, вдохновленные Vercel: как визуальный редактор администратора, так и общедоступный интерфейс отображают диаграммы с помощью пользовательских базовых переменных, подобных Vercel, обеспечивая высококонтрастную, чистую минималистскую эстетику как в светлом, так и в темном режимах.

Предварительные настройки и примеры диаграмм

Ниже приведены четыре классические реализации диаграмм, работающие в PolyCMS.

1. Простая блок-схема: жизненный цикл аутентификации пользователя (горизонтальный — LR)

Простая блок-схема слева направо, показывающая, как стандартные входные данные на стороне клиента анализируются и аутентифицируются защитой сеанса.

graph LR A[Ввод учетных данных] --> B{Поля пусты?} B -->|Да| C[Показать ошибку валидации] B -->|Нет| D[Аутентификация через Sanctum] D --> E{Успешно?} E -->|Да| F[Перенаправление в панель администрирования] E -->|Нет| G[Показать ошибку неверных учетных данных]

2. Диаграмма состояний: жизненный цикл транзакции электронной коммерции (StateDiagram-v2)

Диаграмма состояний, изображающая возможные переходы состояний транзакции онлайн-покупки через платежные шлюзы PayPal или SePay.

stateDiagram-v2 [*] --> Новый Новый --> В_ожидании : Покупатель оформляет заказ В_ожидании --> Завершено : Оплата подтверждена В_ожидании --> Ошибка : Тайм-аут оплаты / Ошибка Ошибка --> В_ожидании : Повторная попытка покупателя Завершено --> [*]

3. Промежуточная диаграмма последовательности: безопасный поток запросов REST API

Диаграмма последовательности, демонстрирующая безопасное двустороннее взаимодействие между Клиентом, веб-клиентом, шлюзом API и базой данных для обслуживания контента с аутентификацией по токену.

sequenceDiagram participant User as Разработчик или Пользователь participant App as API-клиент participant Auth as API-шлюз participant DB as Основная база данных User->>App: Отправка API-запроса с токеном Bearer App->>Auth: GET /api/v1/posts (Auth Header) Auth->>Auth: Проверка подписи и областей действия токена Auth->>DB: Запрос постов (фильтрация по таксономии) DB-->>Auth: Eloquent collection retrieved Auth-->>App: JSON Response (200 OK + Data) App-->>User: Вывод отформатированного массива данных

Основной архитектурный рабочий процесс PolyCMS (сложный - TD)

Чтобы продемонстрировать сложную вертикальную компоновку, вот полный технический архитектурный конвейер PolyCMS. В нем описывается, как сообщение перемещается из базы данных, проходит через компилятор динамических блоков, анализирует шорткоды/теги Mermaid, применяет крючки/фильтры в стиле WordPress и, наконец, выводит HTML-представления премиум-класса в стиле Vercel.

graph TD %% Define Node Shapes DB[(MySQL or PostgreSQL Database)] Engine[ContentRenderer Core Engine] JsonParser{Parse block JSON content_raw?} HtmlFallback[Fallback to content_html] TiptapParse[TipTap NodeView Reconstitution] Helper[app/helpers.php Processing Pipeline] HookAction[Phase 1: Filter content.render.html] ModalOverlay[Phase 2: Extract Modal Links & YT Sliders] MermaidParse[Phase 3: Decode Mermaid Graph syntax] AssetLoader[Inject Dynamic Self-Hosted Assets] VercelTheme[Apply Premium Vercel CSS themeVariables] FinalView[Итоговый HTML веб-страницы] %% Flow lines DB -->|Получение данных поста| Engine Engine --> JsonParser JsonParser -->|Да - Не пусто| TiptapParse JsonParser -->|Нет - Пусто| HtmlFallback TiptapParse --> Helper HtmlFallback --> Helper Helper --> HookAction HookAction --> ModalOverlay ModalOverlay --> MermaidParse MermaidParse --> AssetLoader AssetLoader --> VercelTheme VercelTheme --> FinalView %% Style highlights style DB fill:#0a0a0a,stroke:#333333,stroke-width:2px,color:#ffffff style Engine fill:#000000,stroke:#333333,stroke-width:2px,color:#ffffff style Helper fill:#000000,stroke:#10b981,stroke-width:2px,color:#ffffff style FinalView fill:#111111,stroke:#10b981,stroke-width:3px,color:#ffffff

Интерактивный редактор блоков диаграмм TipTap

Как автору панели администратора PolyCMS, вам не нужно запоминать синтаксис Mermaid, чтобы создавать эту прекрасную графику. В редакторе блоков:

Нажмите кнопку Диаграмма русалки на панели инструментов редактора.
Элегантный визуальный контейнер мгновенно визуализируется в режиме онлайн.
Перейдите на вкладку Редактировать код, чтобы написать синтаксис с помощью вспомогательных кнопок (--> Стрелка, [Узел], {Decision}.
Используйте раскрывающийся список Шаблоны, чтобы мгновенно загружать стандартные настройки (блок-схемы, последовательности, состояния) и изменять их на лету.
Если ваш синтаксис неверен, встроенный компилятор выделяет строку и показывает полезный баннер ошибки, не прерывая процесс черчения!