Справочник блоков

Эта страница документирует каждый тип блока, который поставляется с редактором. У каждого блока есть форма JSON, рендерер и программный путь вставки через editor.blocks.insert.

Все блоки при сериализации используют одну и ту же оболочку: id, type, data и необязательную запись tunes.

Форма блока

Каждый блок сериализуется в одну и ту же JSON-оболочку. id назначается редактором и может быть опущен при программном построении данных.

{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

Выделенный блок-уведомление с 4 вариантами.

{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

Блок аудио. Обрабатывается через колбэк audioUploader в Editor.create.

{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

Интерактивный список флажков с состоянием отметки для каждого элемента.

{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

Блок кода с подсветкой синтаксиса. Поддерживается 50 языков, среди них typescript, python, rust, go, ruby, swift и kotlin.

{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

collapsible

Сворачиваемый раздел с заголовком и вложенными дочерними блоками. Неизвестные типы дочерних блоков сохраняются без изменений, поэтому новые документы переживают старые рендереры.

{
  "type": "collapsible",
  "data": {
    "html": "Details",
    "open": true,
    "children": [{ "type": "paragraph", "data": { "html": "Hidden until opened." } }]
  }
}

collection

Встраивает живое представление коллекции по id. Блок хранит только идентичность коллекции; форма и данные принадлежат серверу.

{
  "type": "collection",
  "data": { "collectionId": "c-42" }
}

columns

Многоколоночный макет из 2–4 колонок, каждая из которых держит собственный список дочерних блоков.

{
  "type": "columns",
  "data": {
    "columns": [
      [{ "type": "paragraph", "data": { "html": "Left" } }],
      [{ "type": "paragraph", "data": { "html": "Right" } }]
    ]
  }
}

date

Календарная дата, хранится без часового пояса, поэтому все соавторы видят одно и то же.

{
  "type": "date",
  "data": { "date": "2026-08-31" }
}

delimiter

Визуальный разделитель между разделами.

{
  "type": "delimiter",
  "data": { "variant": "line" }
}

doc_card

Богатая карточка-ссылка на другой документ. Хранит id целевой страницы и отображаемый снимок, который хосты обновляют при переименовании.

{
  "type": "doc_card",
  "data": { "pageId": "p-7", "title": "Release notes", "icon": "📄" }
}

embed

Встроенная ссылка. Блок хранит URL; провайдер и разметка встраивания выводятся при отображении, а поля предпросмотра служат запасной карточкой.

{
  "type": "embed",
  "data": { "url": "https://www.youtube.com/watch?v=abc123" }
}

file

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

{
  "type": "file",
  "data": { "url": "/files/notes.pdf", "name": "notes.pdf", "size": 2048, "contentType": "application/pdf" }
}

glance

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

{
  "type": "glance",
  "data": {
    "caption": "Facts",
    "rows": [{ "label": "Version", "html": "<b>1.0</b>" }],
    "variant": "plain"
  }
}

header

Заголовки верхнего уровня и разделов (от h1 до h6). Инлайн-инструменты работают внутри html-нагрузки.

{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

Блок изображения с подписью и alt-текстом. Обрабатывается через колбэк imageUploader в Editor.create.

{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

issues

Таблица связанных задач, выводимая при отображении из чипов и карточек задач на странице (задача, название, статус, исполнитель). Собственных данных не хранит.

Этот блок не хранит полей; строки выводятся из чипов и карточек задач на странице при отображении.

{
  "type": "issues",
  "data": {}
}

latex

Математика LaTeX: хранится как исходник и вёрстка выполняется при отображении. Лучший рендерер позже улучшит каждый уже существующий документ.

{
  "type": "latex",
  "data": { "source": "\\frac{a}{b}" }
}

list

Упорядоченный или неупорядоченный список. Каждый элемент: html.

{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

mermaid

Диаграмма Mermaid: хранится как исходник и рисуется при показе, никогда как растровое изображение.

{
  "type": "mermaid",
  "data": { "source": "flowchart TD\n  A --> B" }
}

openapi

Отображает интерактивный справочник API из документа OpenAPI 3.x, встроенного или загруженного по URL, с выбором сервера и фрагментами кода.

{
  "type": "openapi",
  "data": { "url": "/api/openapi.json", "defaultServer": "https://api.example.com" }
}

paragraph

Абзац форматированного текста. Принимает разметку инлайн-инструментов, таких как bold, italic, code, link, marker и tooltip.

{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

Цитата с необязательным указанием автора.

{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

sketch

Рисунок от руки, хранящийся как штрихи, никогда как растр: он остаётся редактируемым и чисто масштабируется.

{
  "type": "sketch",
  "data": { "strokes": [{ "points": [0, 0, 10, 10], "color": "#ff0000", "width": 3 }] }
}

table

Сетка данных. Первую строку можно использовать как заголовок; каждая ячейка: html.

{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

toc

Оглавление, выводимое из заголовков документа при отображении. Собственных данных не хранит.

Этот блок не хранит полей; список выводится из заголовков документа при отображении.

{
  "type": "toc",
  "data": {}
}

updates

Живая лента активности документа. Хранит идентичность, никогда снимок, поэтому продолжает показывать текущую активность.

{
  "type": "updates",
  "data": { "pageId": "p-7" }
}

video

Блок видео. Обрабатывается через колбэк videoUploader в Editor.create.

{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}