Перейти к содержимому
ФреймворкJavaScript

Страница: ссылки на подстраницы

Владеющий блок page сохраняет только data.pageId; тело, название, значок и права доступа хранит ваше приложение. Блок page-link и встроенная ссылка <a data-blok-page-id="p1">Page</a> не владеют страницей. Они не сохраняют название, значок, URL или решение о доступе.

Используйте resolve для разрешённых метаданных и subscribe, чтобы обновлять их после изменения у хоста. Хост отправляет уведомления в той же вкладке после локальных правок и удалённых изменений. null означает отсутствие страницы, undefined оставляет нейтральное состояние, а { access: 'none' } означает отказ. Недоступная страница скрывает название, показывает замок и объясняет «Нет доступа» при клике или Enter.

Через search предлагайте только доступные страницы для вставки через @ и [[. Глобальный поиск и экран обратных ссылок принадлежат хосту. Обычные упоминания URL остаются ссылками на URL. Зарегистрируйте Page и PageLink с одной конфигурацией PageConfig; только Page вызывает create для новой владеющей страницы.

Для статичного HTML вызовите blocksToHtml(data, { pageInfo, pageHref }). pageInfo должен синхронно отдавать разрешённые метаданные. Отсутствующие, закрытые и неразрешённые страницы не получают URL от pageHref.

href строит URL из непрозрачного ID без названия. open обрабатывает обычный клик и Enter; клик с модификатором следует браузерной ссылке. Blok не загружает и не сохраняет тело страницы.

Импорт

TypeScript
import { Page } from '@bloklabs/core/tools';

Конфигурация

ОпцияТипПо умолчаниюОписание
href(pageId: string) => stringundefined

Строит URL страницы по её id. Blok ставит его на ссылку, поэтому Cmd/Ctrl-клик или клик средней кнопкой открывает страницу в новой вкладке. Без него у ссылки нет URL. Небезопасные схемы вроде javascript: отбрасываются.

pageIdFromHref(href: string) => string | null | undefinedundefined

Превращает URL обратно в id страницы или возвращает null, если это не ссылка на страницу. Blok передаёт абсолютный URL. С ним при вставке ссылки на страницу появляется пункт «Упомянуть»: он вставляет встроенную ссылку на страницу, а не обычную ссылку.

open(pageId: string, ctx: { event?: MouseEvent | KeyboardEvent }) => voidundefined

Открывает страницу. Blok вызывает его при обычном клике левой кнопкой. Без него клик ведёт на href.

Enter открывает страницу и тогда, когда блок выбран с клавиатуры (Escape, затем стрелки). В этом случае ctx.event это нажатие клавиши.

Ещё Blok вызывает его один раз сразу после того, как пользователь вставил новую страницу из тулбокса. В этом случае ctx.event пуст. Он не вызывается для страницы, вставленной через API, и когда create выбросил ошибку.

resolve(pageId: string) => PageInfo | null | undefined | Promise<…>undefined

Возвращает текущие разрешённые метаданные страницы. null означает, что страницы нет; { access: 'none' } скрывает название и значок и показывает «Нет доступа»; undefined оставляет нейтральную подпись. Возвращённые название и значок видны, но не сохраняются в блоке.

Хост должен проверить права перед выдачей метаданных. subscribe запускает новый запрос при изменении доступа или метаданных.

create(init: { pageId: string; document?: OutputData; title?: string; parentId?: string }) => void | { pageId: string } | Promise<…>undefined

Создаёт страницу в вашем приложении. Blok вызывает его один раз на каждую новую страницу и передаёт id, который сгенерировал сам. Он никогда не вызывается при загрузке, вставке из буфера обмена, отмене, повторе, изменении от соавтора и в режиме только для чтения.

Когда пользователь выбирает «Страница» в тулбоксе, Blok ждёт ответа. На пункте меню крутится спиннер, а блок появляется, когда промис разрешится. Верните { pageId }, чтобы использовать id вашего бэкенда вместо id Blok. Если он выбросит ошибку, блок не вставится; покажите ошибку сами. Закрытое во время ожидания меню вставку не отменяет.

Когда ваш код вставляет страницу через API без pageId, блок появляется сразу с id Blok. Другой возвращённый id игнорируется с предупреждением, поэтому передайте свой pageId в insert. Если он выбросит ошибку, блок показывает «Страница не найдена». Blok всё равно спрашивает resolve, так что страница, которую ваше приложение всё-таки создало, появится.

init.document, если передан, это начальное содержимое новой страницы. Сохраните его как документ страницы. «База данных - на всю страницу» передаёт один блок database с fullPage: true. База данных заканчивает настройку, когда страница открывается.

С createFromMention его вызывает и меню @. Тогда init.title это набранный текст, а init.parentId это страница, которую выбрал пользователь. Без parentId страница создаётся внутри той, что открыта в редакторе. Blok вставляет упоминание новой страницы и не открывает её.

databasePagesbooleanfalse

Добавляет «База данных - на всю страницу» в раздел «База данных» тулбокса. Пункт создаёт подстраницу с новой базой данных и открывает её. Ссылка показывает значок таблицы, пока у страницы нет своего значка.

Включайте его, только если create сохраняет document как содержимое новой страницы и инструмент database зарегистрирован.

createFromMentionbooleanfalse

Добавляет раздел «Новая страница» в меню @. В нём два пункта: подстраница текущей страницы и страница внутри той, которую выберет пользователь. Каждый создаёт страницу с набранным текстом в названии и вставляет её упоминание.

Включайте его, только если create сохраняет title и parentId.

search(query: string) => Promise<readonly PageSearchResult[]>undefined

Предлагает доступные страницы для встроенных ссылок через @ и [[. Перед возвратом отфильтруйте результаты по правам текущего пользователя; глобальный поиск принадлежит хосту.

Меню @ открывается сразу после символа «@» и спрашивает пустой запрос. Верните на него недавние страницы. Пока идёт поиск, меню показывает спиннер и строки-заглушки.

Раздел «Ссылка на страницу» показывает результаты. В строке видны значок, название и path: названия страниц над ней. status: 'draft' показывает метку «Черновик». Сначала видны шесть строк, затем строка «ещё результаты» раскрывает список.

С resolve Blok проверяет каждый результат и берёт из него название, значок, путь и статус. «Ничего не найдено» появляется, только когда все разделы пусты.

subscribe(pageId: string, onChange: () => void) => (() => void) | voidundefined

Вызывает onChange, когда меняются метаданные страницы или права доступа. Blok снова запускает resolve и вызывает возвращённую функцию при прекращении подписки.

preview(pageId: string) => OutputBlockData[] | null | undefined | Promise<…>undefined

Возвращает разрешённые начальные блоки для предпросмотра при наведении. Blok запрашивает их только для доступной страницы.

Формат данных

TypeScript
interface PageData {
  pageId: string;
  kind?: 'database';  // Set by "Database - Full page"
}
JSON
{
  "id": "pg001",
  "type": "page",
  "data": { "pageId": "p1" }
}

Пример использования

TypeScript
import { Blok } from '@bloklabs/core';
import { Page, PageLink } from '@bloklabs/core/tools';
import { blocksToHtml } from '@bloklabs/core/view';

const pageUrl = (pageId) => `/pages/${pageId}`;
const pageConfig = {
  href: pageUrl,
  open: (pageId) => router.push(pageUrl(pageId)),
  resolve: (pageId) => myApi.getAuthorizedPageInfo(pageId),
  search: (query) => myApi.searchAccessiblePages(query),
  subscribe: (pageId, onChange) => myApi.subscribePage(pageId, onChange),
};

const editor = new Blok({
  holder: 'editor',
  tools: {
    page: {
      class: Page,
      config: {
        ...pageConfig,
        // Return { pageId } to use your backend's id instead of Blok's.
        create: async ({ pageId }) => ({ pageId: (await myApi.createPage(pageId)).id }),
      },
    },
    'page-link': { class: PageLink, config: pageConfig },
  },
});

const authorizedPageInfo = myApi.getAuthorizedPageInfoSnapshot();
const html = blocksToHtml(savedData, {
  pageInfo: (pageId) => authorizedPageInfo.get(pageId),
  pageHref: pageUrl,
});