ФреймворкJavaScript
Blok documentation
Guides, the full API reference, and every built-in block and inline tool. New here? Start with the quick start and have an editor running in five minutes.
Начало работы
- Быстрый стартНачните работу с Blok за несколько простых шагов.
- Создайте первый редакторПодключите Blok, добавьте контент и сохраните его в JSON, который можно хранить и загружать обратно — полный цикл за пять шагов.
- Всё — это блокУ Blok одна основная идея. Поймите её — и остальной API сложится сам собой.
- Создание собственного блок-инструментаСоздайте блок-инструмент с нуля — блок-выноску, которая отрисовывается, редактируется и сохраняется как любой встроенный блок.
Основное
- Класс BlokОсновной класс редактора, который инициализирует и управляет экземпляром редактора Blok.
- КонфигурацияОбъект конфигурации, передаваемый конструктору Blok. Формально он разделён на два типа: `BlokMountOptions` — опции, фиксированные на всё время жизни экземпляра (holder, tools, i18n, колбэки, …) — и `BlokState`, «живые» поля: `readOnly` (включая `hideControls`), `hideToolbar` и `inlineToolbar`. У каждого поля `BlokState` есть документированный runtime-сеттер (`readOnly.set`, `toolbar.setHidden`, `tools.setInlineToolbar`), поэтому его изменение никогда не требует пересоздания редактора — а адаптеры React, Vue и Angular реагируют на эти props/inputs на месте. `BlokConfig = BlokMountOptions & BlokState`, так что существующий код компилируется без изменений.
- БлокиУправление блоками в редакторе — создание, удаление, обновление и переупорядочивание контента.
- BlockAPIИнтерфейс для работы с отдельными блоками. Возвращается методами blocks.getById(), blocks.getBlockByIndex() и blocks.insert().
- СохранениеСохранение и экспорт содержимого редактора.
- View-рендерерПоказывайте сохранённые документы, не платя за редактор. Подпуть @bloklabs/core/view синхронно и без DOM превращает OutputData в семантический HTML или простой текст — он работает в Node, воркерах и React Server Components, — поэтому страницам «только для чтения» (публикации, превью, поисковая индексация, письма) больше не нужны экземпляр редактора, его бандл и асинхронное ожидание готовности. Каждое строчное поле санитизируется по составленному allowlist до подстановки, а политика URL-схем идентична редакторской; используйте функции вместе с defineBlokSchema — и документы отображаются под тем же составом санитизации, который их создал (если набор строчных инструментов меняется на лету через tools.setInlineToolbar, пересоберите схему, чтобы отображение не отстало). Для React пакет @bloklabs/react даёт <BlokView> и useBlokView, заменяющие <BlokEditor readOnly> в местах, где документ только показывается.
Редактирование
- КурсорУправление позицией курсора и выделением внутри редактора.
- ВыделениеРабота с выделением текста внутри редактора.
- МеткиRange-aware операции со строчными метками для инлайн-инструментов форматирования. Там, где selection.findParentTag смотрит только на якорный узел выделения, api.marks работает со ВСЕМ диапазоном: has отвечает «покрыт ли каждый текстовый узел выделения», apply и remove разрезают частично покрытые обёртки на границах диапазона, обновляют полностью покрывающие обёртки на месте и восстанавливают выделение, а apply и remove расширяют диапазон на замыкающий пробел, который браузеры исключают из выделения по двойному клику. Метка описывается декларативно через MarkSpec (tag, aliasTags, className, attributes, style); aliasTags позволяет унаследованным вариантам тега (например, <b> рядом со <strong>, <em> рядом с <i>) считаться ТОЙ ЖЕ меткой, при этом новые обёртки всегда используют канонический тег. Строковые значения статичны и входят в идентичность метки; значения-функции вычисляются из state, переданного в apply/toggle, и сознательно ИСКЛЮЧЕНЫ из идентичности — поэтому палитра цветов это ОДНА метка, обновляющаяся на месте, а не N взаимно отменяющих друг друга. Две спецификации с одинаковыми tag, classNames и статичными атрибутами принадлежат одной семье и компонуются на одном элементе — например, цвет текста и цвет фона на одном <mark>. Каждый метод по умолчанию берёт первый диапазон живого выделения. Экспорт ядра markSanitizerConfig(spec) выводит правило санитайзера для метки: тег попадает в allowlist, необъявленные style-свойства и классы вычищаются, объявленные атрибуты сохраняются, а значения-функции учитываются по имени свойства — динамические значения не теряются при сохранении. createReactInlineTool в React-адаптере применяет тот же вывод автоматически, когда инструмент объявляет спецификацию mark.
- СтилиДоступ к CSS-классам для стилизации пользовательских инструментов и элементов интерфейса.
- ИсторияУправление функциональностью отмены/повтора для операций редактора.
Интерфейс
- Панель инструментовУправление панелью инструментов блока и её состоянием.
- Строчная панельУправление строчной панелью форматирования (жирный, курсив и т.д.).
- ИнтерфейсДоступ к UI-элементам и состоянию Blok.
- УведомленияОтображение уведомлений для пользователей.
- Всплывающие подсказкиОтображение всплывающих подсказок на элементах интерфейса.
Расширение и система
- ИнструментыДоступ и управление инструментами редактора.
- СобытияПодписка и управление событиями жизненного цикла редактора.
- СлушателиУправление пользовательскими обработчиками DOM-событий с автоматической очисткой.
- ОчисткаОчистка HTML-контента для защиты от XSS-атак.
- Только чтениеУправление режимом только для чтения редактора. Переключение происходит на месте: тот же экземпляр редактора меняет режим, сохраняя позицию курсора, историю отмен и прокрутку — поэтому переключатель «редактирование/просмотр» — это `readOnly.set(!isEditing)` на ОДНОМ экземпляре вместо уничтожения одного редактора и создания другого.
- ЛокализацияПоддержка интернационализации для перевода строк интерфейса, а также метод `i18n.update()` для смены языка на лету.
Типы данных
- Выходные данныеСтруктура данных, возвращаемая методом save(). Во входных позициях — опция конфигурации `data`, `render()`, `blocks.render()` и `blocks.insertMany()` — также принимаются нестрогие варианты `LooseOutputData` / `LooseOutputBlockData`, где `data`, `id` и `time` блока могут быть `null`: `null` в `data` становится `{}`, `null`/пустой `id` заменяется сгенерированным. Сохранённый вывод всегда имеет строгую форму.
- Данные блокаСтруктура каждого блока в массиве blocks.
Адаптеры фреймворков
- Компонент BlokEditorКомпонент-редактор «всё в одном», который поставляют адаптеры фреймворков: <BlokEditor> в @bloklabs/react и @bloklabs/vue, <blok-editor> (BlokEditorComponent) в @bloklabs/angular. Он принимает любую опцию конфигурации редактора как проп, пробрасывает неизвестные пропы на контейнерный div и даёт доступ к живому экземпляру Blok через ref/onReady. Пропы ниже описывают специфичную для адаптеров поверхность; остальное совпадает с опциями раздела «Конфигурация».
- useBlocksРеактивный снимок дерева блоков плюс полный API манипуляций от адаптеров фреймворков: хук useBlocks(editor) в @bloklabs/react, composable useBlocks(editor) в @bloklabs/vue и injectBlocks() в @bloklabs/angular. Чтения реактивно перерисовываются при изменении документа; записи атомарны (один шаг отмены) и безопасны до готовности редактора (превращаются в no-op). Возвращаемые объекты BlockNode ({ id, type, parentId, contentIds }) — волатильные свежие снимки: читайте их сразу, не сохраняйте в массивах зависимостей.
- useBlokReadyЖивая готовность редакторов Blok внутри поддерева DOM — булево значение, от которого можно рендерить: хук useBlokReady(options) в @bloklabs/react, composable useBlokReady(options) в @bloklabs/vue (возвращает ref) и injectBlokReady(options) в @bloklabs/angular (возвращает signal). Все три обёртки используют один и тот же реестр ядра за Blok.readyState() и Blok.subscribeReady(), поэтому разойтись не могут. Они отвечают на вопрос, который на самом деле есть у списка комментариев или формы: готовы ли МОИ редакторы? Ограничьте область тем ref, который у вас уже есть на контейнере, — тогда посторонний редактор на странице не сможет держать проверку закрытой. Это живой сигнал, а не одноразовая защёлка: редактор, смонтированный позже, снова закрывает проверку, а с settleOn: 'rendered' — и каждый повторный рендер при смене data. Область без редакторов считается готовой, поэтому пустой список не требует отдельной ветки. Значение начинается с false и впервые читается по-настоящему, когда элемент области примонтирован (React — эффект после монтирования, Vue — onMounted, Angular — afterNextRender); запрошенная, но ещё не разрешённая область даёт false, а не молчаливый откат ко всей странице: лишнее ожидание безопасно, недостаточное является ошибкой.
Блочные инструменты
- ПараграфThe default text block. Supports rich inline formatting (bold, italic, links, colour). Empty paragraphs are excluded from saved output unless `preserveBlank` is enabled.
- ЗаголовокHeading blocks from H1 to H6. Supports multiple toolbox entries (one per heading level), keyboard shortcuts (# ## ### etc.), and optional toggle (collapse/expand children) for H1–H3.
- СписокBulleted, numbered, and to-do (checklist) lists with unlimited nesting. Each list item is a separate block. The toolbox shows three entries by default — one for each style — and items can be converted between styles via the block settings menu.
- ТаблицаA full-featured table block. Each cell contains its own block editor (supporting any block type). Supports heading rows, heading columns, column resizing, cell background/text colours, row/column add and delete controls, copy/paste, and a text density switch (compact or comfortable) in the block settings menu.
- ПереключательA collapsible toggle block with a clickable arrow. Child blocks are nested inside the toggle and hidden when collapsed. Toggling is controlled by clicking the arrow icon. The open/collapsed state is persisted via `isOpen` and restored on reload; toggles default to open.
- CalloutA container block for highlighted content with an emoji icon. Supports customisable text and background colours via a colour picker. Child blocks are nested inside the callout. Useful for tips, warnings, notes, and other call-to-action content.
- DatabaseA multi-view database block supporting board (Kanban), list, table, and gallery views. Stores a schema of typed properties (text, select, multiSelect, date, checkbox, etc.) and view configurations. Rows are stored as child `database-row` blocks. Supports grouping, sorting, filtering, drag-and-drop reordering, inline editing, and an optional backend sync adapter.
- Database RowAn internal block tool that stores a single database row. Not user-insertable — rows are created and managed by the parent Database block. Each row stores property values conforming to the parent database schema and a position string for ordering.
- DividerA horizontal line separator. Renders a semantic `<hr>` element. Has no editable content or settings. Can be inserted via the toolbox or by typing `---` in an empty paragraph.
- SpacerAn adjustable vertical gap. Drag either edge grip — or focus one and press ArrowUp/ArrowDown — to resize. Its main job is lining up content across sibling columns of unequal length, replacing piles of empty paragraphs. Invisible in read-only mode.
- QuoteA blockquote with a left border accent. Supports two sizes (default and large) switchable via the block settings menu. Pasting a `<blockquote>` element automatically creates a quote block.
- CodeA syntax-highlighted code block with a language picker, an optional line-number gutter, and a copy-to-clipboard button. Supports 30+ languages via Prism. LaTeX and Mermaid languages include a live preview tab. Pasting markdown fenced code blocks (```) or `<pre>` elements automatically creates a code block.
- ImageEmbed an image via URL upload or file paste.
- ColumnsA layout block that arranges its children into side-by-side columns. The column list itself holds no content — each column is a child `column` block, and the blocks you write live inside those columns (via `contentIds`). Columns can be created three ways: from the toolbox · by dragging a block beside another · by selecting multiple blocks and choosing "Turn into columns". Column widths are resizable via the separators between columns.
- ColumnA single column inside a column list. Not user-insertable on its own — columns are created and managed by the parent `column_list` block. Child blocks are nested inside the column via `contentIds`. The optional `widthRatio` controls the column’s width relative to its siblings (applied as flex-grow); omit it for equal width.
- EmbedA live interactive iframe for a pasted provider URL (YouTube, Vimeo, Figma, CodePen, and 100+ other services), like Notion’s "Create embed". Pure client-side: the URL is matched against a built-in embed registry and resolved into a provider-sanctioned iframe URL — only registry-matched URLs are ever embedded. Supports resizing (document-style providers such as Google Docs, Sheets, Slides, Forms and Drive also get a bottom handle for adjusting the embed height), alignment (left/center/right), and an optional caption.
- BookmarkA static OpenGraph card for a pasted link, like Notion’s "Create bookmark". Shows the page title, description, preview image, favicon, and domain. Metadata is fetched from a consumer-supplied unfurl endpoint (CORS makes a backend mandatory) — Blok ships only the contract.
- FileAn attachment card for any uploaded file. Shows a type icon, filename, human-readable size, a download action, and an optional caption. Files are sent through a consumer-supplied uploader; when none is provided the tool falls back to a local blob URL (uploadByFile) or the pasted URL itself (uploadByUrl). An optional MIME allowlist and max size can gate what is accepted.
- AudioA music-player style audio block. Renders an uploaded or linked audio file with a custom control bar (play/pause, a waveform scrubber, volume, playback speed, loop), optional cover art, title/artist metadata, and a caption. Waveform peaks and duration are decoded once and cached in the saved data so playback renders instantly on reload. Audio is sent through a consumer-supplied uploader; when none is provided the tool falls back to a local blob URL (uploadByFile) or the pasted URL (uploadByUrl). Share links from Dropbox, OneDrive, GitHub, GitLab, Hugging Face, Google Cloud Storage, and the Internet Archive are rewritten to their direct-content form automatically; Google Drive links additionally require an `uploadByUrl` backend because Drive blocks browser hotlinking. An optional MIME allowlist and max size gate what is accepted.
- VideoA full-featured video player block. Renders an uploaded or linked video with a custom control bar (play/pause, scrubber with buffered range and hover preview, volume, playback speed, loop, picture-in-picture, theater and fullscreen modes), an optional caption, and an ambient glow behind the player. Videos are sent through a consumer-supplied uploader; when none is provided the tool falls back to a local blob URL (uploadByFile) or the pasted URL (uploadByUrl). An optional MIME allowlist and max size gate what is accepted.
Строчные инструменты
- ЖирныйWraps selected text in `<strong>`. Activated with Cmd/Ctrl+B or by clicking the B button in the inline toolbar. Supports nested bold ranges and normalises overlapping markup on paste.
- КурсивWraps selected text in `<i>` (pasted `<em>` is also preserved). Activated with Cmd/Ctrl+I or by clicking the I button in the inline toolbar.
- СсылкаWraps selected text in `<a href="...">`. Activated with Cmd/Ctrl+K. Clicking the button on existing linked text opens the URL input allowing the link to be edited or removed.
- МаркерApplies text colour or background colour to selected text using `<mark style="color:...">` or `<mark style="background-color:...">`. Opens a colour picker with preset text and background swatches plus a Default reset. Activated with Cmd/Ctrl+Shift+H.
- UnderlineWraps selected text in `<u>`. Activated with Cmd/Ctrl+U or by clicking the U button in the inline toolbar.
- StrikethroughWraps selected text in `<s>`. Activated with Cmd/Ctrl+Shift+S or by clicking the S button in the inline toolbar.
- Inline CodeWraps selected text in `<code>`. Activated with Cmd/Ctrl+E or by clicking the code button in the inline toolbar. Useful for marking up variable names, function calls, and short code snippets within text.
- EquationRenders inline math (LaTeX) with KaTeX. Activated with Cmd/Ctrl+Shift+E — wraps the selected text, or a formula typed into the popover input, in a `<span data-latex="...">`. The LaTeX source is kept in the `data-latex` attribute so the formula round-trips through save/load, while the rendered KaTeX markup is regenerated on load.
- Clear FormatRemoves inline formatting (bold, italic, underline, strikethrough, inline code, highlight) from the selected text while keeping links intact. Activated with Cmd/Ctrl+\ or by clicking the Tx button in the inline toolbar.