Table of contents — Docxcelerate

Nodes

Ein Marker für ein Inhaltsverzeichnis, den Renderern voraus, die eines bauen.

The kind is part of the document schema and both renderers accept it. What is missing is downstream rather than in the authoring: the element places the marker and carries its title, and building the entries from the surrounding section titles is a renderer's job.

Helper: TableOfContents
Node-Art: tableOfContents
Kategorie: Struktur
Wird aufgelöst: By the renderer
Kinder: None. The entries would come from the sections beside it.

Option	Typ	Was sie bewirkt
`id`	`string`	Stable address for the node. Engines target it and build artifacts diff on it, so treat a rename as a breaking change. Optional: a node without one takes an id from where it sits, which is what keeps branches and loops from forcing you to invent names. Two nodes claiming one id is an error rather than a race.
`title`	`string`	Heading for the list. Renderers fall back to their own wording.
`derivers`	`DeriverInvocation[]`	Values the engine computes before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`. These survive publishing and run per document — use them for anything computed from request data. `useDeriver` runs one during the build instead.

Eine schreiben

import { TableOfContents } from "docxcelerate/template";

export const Contents: TableOfContents = () => (
  <TableOfContents id="contents" title="What is in this document" />
);

Sie lässt sich wie jeder andere Node komponieren und löst sich in Vorschau-Builds, Engine-Builds und Tests gleich auf. Direkt in einem Template platziert braucht sie gar keine eigene Komponente — <TableOfContents id="contents" title="…" /> ist bereits alles.

Was fehlt, liegt weiter hinten

Das Element setzt den Marker und trägt seinen Titel. Die Einträge aus den umgebenden Abschnittstiteln zu bauen ist Sache eines Renderers, und weder die Browser-Vorschau noch der DOCX-Packer tut das bislang — beide drucken den Titel und hören auf.

Warum jetzt schon eine platzieren

Es kostet eine Zeile, und sie beginnt an dem Tag Einträge zu drucken, an dem die Renderer sie bauen. Die Alternative — eine von Hand gepflegte Liste von Abschnittstiteln in einem Absatz — ist binnen zweier Releases falsch.

Wenn Sie lieber keinen Node ausliefern wollen, der nur eine Überschrift druckt, lassen Sie ihn weg. Ihn später zu ergänzen ist genauso billig.

Varianten

A titled marker

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

The element, and the title it carries into the document.

import { TableOfContents } from "docxcelerate/template";

/**
 * A heading standing in for the contents of the document around it.
 *
 * The shipped renderers print the title and stop — the entries themselves are
 * a renderer's job, and neither the browser preview nor the DOCX packer builds
 * them yet.
 */
export const Contents: TableOfContents = () => (
  <TableOfContents id="contents" title="What is in this letter" />
);

table of contents · a titled marker Open ↗

Wozu es aufgelöst wird

Der Node, wie er im DocumentModel erscheint: das JSON, das ein Renderer bekommt. Kein Styling, kein Layout.

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

Anmerkungen

Der Node hat keine Kinder und liest zur Build-Zeit nichts.
title ist optional; Renderer greifen auf ihre eigene Formulierung zurück.

Diese Seite auf GitHub bearbeiten ↗ Diese Seite als Markdown lesen