Table of contents — Docxcelerate

Узлы

Вид из схемы, у которого пока нет хелпера — как его разместить и что он делает сегодня.

The kind is part of the letter schema and both renderers accept it, but no authoring helper is exported yet. Writing the component by hand works — a node component is a function returning a definition, and the helpers are conveniences over exactly that shape. Хелпера пока нет

Хелперы: Нет — пишется вручную
Вид узла: tableOfContents
Категория: Структура
Разрешается: By the renderer
Дочерние узлы: None. The entries would come from the sections beside it.

Опция	Тип	Что делает
`id` обязательно	`string`	Stable address for the node. Generation endpoints target it and build artifacts diff on it, so treat a rename as a breaking change.
`title`	`string`	Heading for the list. Renderers fall back to their own wording.
`derivers`	`DeriverInvocation[]`	Values computed before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`.

Как написать его без хелпера

Хелперы — это удобство, а не пропускной пункт. Компонент узла — это функция, которая принимает ваши данные и возвращает определение, поэтому любой вид из схемы доступен: достаточно написать такую функцию:

import type { NodeComponent } from "docxcelerate";

export const Contents: NodeComponent<MemberData> = () => ({
  kind: "tableOfContents",
  id: "contents",
  title: "What is in this document",
});

Он компонуется как любой другой узел и одинаково разрешается в сборках предпросмотра, сборках движка и тестах.

Зачем размещать его уже сейчас

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

Если не хочется выпускать узел, печатающий один только заголовок, не включайте его. Добавить позже будет так же дёшево.

Варианты

Written by hand

src/nodes/table-of-contents/basic.node.ts

The definition shape the helpers would produce.

import type { NodeComponent } from "docxcelerate";
import type { SampleData } from "../sample-data.ts";

/**
 * No helper ships for this kind yet. A node component is only a function
 * returning a definition, so writing it out reaches the same place.
 *
 * The shipped renderers print the title and stop.
 */
export const Contents: NodeComponent<SampleData> = () => ({
  kind: "tableOfContents",
  id: "contents",
  title: "What is in this letter",
});

table of contents · written by hand Open ↗

Во что это разрешается

Узел в том виде, в каком он попадает в DocumentModel: JSON, который получает рендерер. Без стилей и без вёрстки.

{
  "id": "contents",
  "kind": "tableOfContents",
  "title": "What is in this letter"
}

Примечания

Со временем ожидается хелпер tableOfContents, принимающий тот же { id, title }, что и здесь. Если написать так, как выше, переход будет правкой в одну строку.
Узел не содержит потомков и ничего не читает во время сборки.

Изменить эту страницу на GitHub ↗