---
title: "Title API — заголовок страницы и значок"
description: "Чтение и установка заголовка страницы и его значка, перенос их в ваш элемент и запись без шага отмены."
source: https://blokeditor.com/ru/docs/title-api/
lastmod: 2026-10-08
---

Фреймворк JavaScript

Интерфейс Заголовок

На этой странице title.get()

# Title API: заголовок страницы и значок

Чтение и изменение заголовка страницы и его значка. Они стоят над первым блоком или в вашем собственном элементе. Заголовок это одна строка простого текста. Оба хранятся в документе и сохраняются в OutputData как `title` и `icon`.

Включается опцией `pageTitle`. `editor.title` доступен сразу после `new Blok()`, а вызовы до `isReady` повторяются, когда редактор готов. Исключение составляет `title.focus()`: до `isReady` он ничего не делает.

Опция `title: true` переносит заголовок через преобразования. Без неё каждое преобразование работает как раньше.

- `blocksToHtml` записывает его первым как `<h1>`, перед которым стоит значок.
- `blocksToMarkdown`, `blocksToMarkdownWithReport` и `blocks.exportMarkdown` записывают его как заголовок `#`. Значок-картинка не записывается.
- `blocksToPlainText` записывает его первой строкой.
- `markdownToBlocksWithReport` и `htmlToBlocksWithReport` вынимают из блоков ведущий заголовок `#` или `<h1>`. Они возвращают его как `title` и `icon`. Заголовок, который начинается с эмодзи и пробела, возвращается как значок и заголовок.
  - Заголовок страницы это простой текст, поэтому форматирование в том заголовке теряется. Оба отчёта добавляют об этом предупреждение `heading`.
  - `markdownToBlocks` и `htmlToBlocks` с этой опцией только убирают заголовок.
- `blocks.importMarkdown` берёт заголовок и значок редактора из этого заголовка. Заголовок без эмодзи очищает значок, а отсутствие заголовка очищает оба.
- `extractTexts` ставит заголовок первым в списке, а `injectTexts` записывает его обратно оттуда. Все остальные индексы сдвигаются на один. Пустой перевод убирает заголовок.

Известны такие ограничения.

- Восстановление версии, сохранённой до того, как сервер начал хранить заголовки страниц, очищает текущий заголовок.
- Совместный редактор, открытый без сети, показывает последние известные блоки, но без заголовка.
- Хост не может задать заголовок через эндпоинт сервера `/edit`.
- Когда двое печатают в заголовке одновременно, побеждает последняя запись.

Обновлено 8 окт. 2026 г. [Редактировать на GitHub](https://github.com/JackUait/blok/blob/main/docs/src/components/api/api-data.ts)

### Как получить экземпляр редактора

Методы ниже вызываются на редакторе, созданном через new Blok(). Они доступны после того, как разрешится editor.isReady.

TypeScript

```
// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');
```

## Методы

### title.get()

string

Текущий заголовок. Если его нет, это `''`.

TypeScript

```
console.log(editor.title.get()); // 'Roadmap'
```

### title.set(text, options?)

void

Заменяет заголовок. Делает один шаг отмены и вызывает `onChange` с источником `api`. Если заголовок уже такой, ничего не происходит.

Передайте `{ record: false }` для записи без шага отмены, например для переименования из вашего бэкенда. Участники всё равно получают запись, а `onChange` получает `{ source: 'api', record: false }`.

- Отмена не уходит дальше этого значения до следующего записанного изменения заголовка. После него отмена может вернуть заголовок, который был до этого значения.
- Чтобы значение стало нижней границей, вызовите `history.clear()` сразу после записи.
- Набор текста, который продолжается после этого, остаётся одним шагом отмены. Отмена возвращает записанное вами значение, а не то, что было до набора.

Параметры

| Параметр | Тип | Обязательный | По умолчанию | Описание |
| --- | --- | --- | --- | --- |
| `text` | `string` | Обязательный | — | Новый заголовок. `''` очищает его. |
| `options.record` | `boolean` | — | `true` | `false`: без шага отмены. Участники всё равно получают запись. |

TypeScript

```
editor.title.set('Roadmap 2027');

// A rename from your backend: no undo step
editor.title.set(serverTitle, { record: false });
```

### title.focus(position?)

void

Ставит каретку в заголовок, по умолчанию в конец. Передайте `'start'` для начала. Ничего не делает, когда заголовок выключен, и до `isReady`.

TypeScript

```
editor.title.focus('start');
```

### title.mount(holder)

void

Переносит заголовок и значок в `holder`, элемент или селектор. Фокус и каретка сохраняются. `null` возвращает заголовок над первым блоком.

После `isReady` селектор, который ничего не находит, бросает ошибку. До `isReady` вызов ждёт редактор. Плохой селектор тогда пишется в лог, а заголовок остаётся на месте.

Чтобы выровнять ваш собственный раздел между заголовком и редактором, повторите разметку заголовка. Его переменная `--blok-content-column` задана на собственном элементе заголовка, поэтому соседний раздел её не видит.

- Задайте разделу отступ в начале, равный полю редактора. По умолчанию это `56px`.
  - Оно равно `0` при `hideToolbar: true` или `readOnly: { hideControls: true }`.
  - `toolbarPosition: 'right'` переносит его в конец.
- Внутри задайте содержимому `box-sizing: border-box`, `max-width: var(--blok-content-max-width, 720px)` и `padding-inline: var(--blok-block-padding-inline, 2px)`.
- В ширине `full` используйте `none` вместо `720px`.
- Выравнивайте его так, как задаёт `style.contentAlign`.
  - Значению по умолчанию `'left'` отступ не нужен.
  - `'center'` требует `margin-inline: auto`.
  - `'right'` требует `margin-inline-start: auto`.

Раздел читает эти переменные только у своих предков. Blok применяет `style.tokens` только к своим элементам, поэтому раздел рядом с заголовком их не видит.

- Если вы задаёте `--blok-content-max-width`, объявите её на элементе, который содержит и раздел, и редактор.
- Иначе раздел возьмёт запасные `720px` и съедет относительно заголовка.

С полем всё иначе. Blok объявляет `--blok-editor-gutter-start` на собственном элементе редактора, поэтому значение на предке до редактора не доходит. `style.tokens` пропускает переменные поля с предупреждением.

- Меняйте поле CSS-правилом на редакторе, например `[data-blok-interface] { --blok-editor-gutter-start: 20px; }`.
- Раздел это правило не видит. Задайте ему то же значение сами: числом или той же переменной на одном из его собственных предков.

TypeScript

```
editor.title.mount('#page-title');

// A section of your own between the title and the editor
// .page-meta { box-sizing: border-box; padding-inline-start: 56px; }
// .page-meta > div {
//   box-sizing: border-box;
//   max-width: var(--blok-content-max-width, 720px);
//   padding-inline: var(--blok-block-padding-inline, 2px);
// }

// Back above the first block
editor.title.mount(null);
```

### title.icon.get()

PageIcon | null

Текущий значок: `{ type: 'emoji', value }` или `{ type: 'image', url }`. Если значка нет, это `null`.

TypeScript

```
const icon = editor.title.icon.get(); // { type: 'emoji', value: '🗺️' }
```

### title.icon.set(icon, options?)

void

Задаёт значок или убирает его при `null`. Делает один шаг отмены и вызывает `onIconChange` с источником `api`. `{ record: false }` работает так же, как у `title.set`.

TypeScript

```
editor.title.icon.set({ type: 'emoji', value: '🚀' });
editor.title.icon.set(null);
```

TypeScript

```
import { Blok } from '@bloklabs/core';

const editor = new Blok({
  holder: 'editor',
  pageTitle: {
    placeholder: 'Untitled',
    onChange: (title, change) => {
      if (change.source !== 'remote') {
        saveTitle(title);
      }
    },
  },
  data: { title: 'Roadmap', icon: { type: 'emoji', value: '🗺️' }, blocks: [] },
});

editor.title.get(); // 'Roadmap'

const saved = await editor.save();
// saved.title === 'Roadmap'
```

## Title API

| Свойство | Описание |
| --- | --- |
| `holder` | `HTMLElement | string` | Элемент или селектор, в котором рисуется заголовок. Без него заголовок стоит над первым блоком. |
| `placeholder` | `string` | Показывается, пока заголовок пуст. По умолчанию это локализованное сообщение `title.placeholder`. |
| `icon` | `boolean` | `false` скрывает значок и кнопку добавления значка. |
| `onChange` | `(title: string, change: TitleChange) => void` | Вызывается при каждом изменении заголовка, из любого источника. `change.source` равен `user`, `undo`, `redo`, `remote` или `api`. Сохраняйте при `user`, `undo`, `redo` и `api`. `change.record` равен `false` только для записи с `{ record: false }`. Иначе этого ключа нет. |
| `onIconChange` | `(icon: PageIcon | null, change: TitleChange) => void` | Вызывается при каждом изменении значка, из любого источника. `null` значит, что значок убран. `change` такой же, как у `onChange`. |