Nodes

Section

De enige node die andere nodes bevat, en de kop die zijn titel wordt.

The only construct that nests today. Its title carries into the document outline, so the structure you write is the structure the reader sees.

Helpers: Section
Nodesoort: section
Categorie: Structuur
Wordt opgelost: Locally
Children: Any node, including other sections. No depth limit.

Optie	Type	Wat het doet
`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` verplicht	`string`	The heading printed above the children, and the outline entry.
`children`	`Yield`	The children, as JSX children of `<Section>`. Components, elements, arrays and conditionals all count; anything falsy is skipped.
`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.

Er een schrijven

Een sectie krijgt zijn opties en zijn kinderen — nodecomponenten, dezelfde waarden die je op het hoogste niveau van een document zou plaatsen:

import { section } from "docxcelerate";

export const Opening = section<MemberData>({ id: "opening", title: "Your renewal" }, [
  Greeting,
  PriceChange,
]);

In TSX leest dezelfde aanroep als markup:

<Section id="opening" title="Your renewal">
  <Greeting />
  <PriceChange />
</Section>

Beide leveren dezelfde boom op. Templates behandelt wanneer welke vorm zijn plek verdient.

Kinderen kunnen van alles zijn

Alinea’s, afbeeldingen, grafieken, een inhoudsopgavemarkering, of verdere secties. Geen enkele andere node heeft kinderen, dus de diepte van een document is de diepte van zijn secties.

Er verandert niets aan een node doordat hij in een sectie terechtkomt: hij lost op elke diepte hetzelfde op, en zijn id krijgt er geen voorvoegsel bij.

Titels lopen door in de structuur

title is verplicht, en het is geen versiering — het wordt de kop boven de kinderen en de regel waaruit een inhoudsopgave wordt opgebouwd. Een groep die geen kop wil, wil geen sectie; zet de nodes dan rechtstreeks in het document.

Varianten

A titled group

src/nodes/section/basic.node.tsx

Two paragraphs under one heading — the common case.

import { Section } from "docxcelerate/template";
import { PriceChange } from "../paragraph/conditional.node.tsx";
import { Greeting } from "../paragraph/static.node.tsx";

/**
 * A section takes an id, a title and its children. The children are the same
 * components you would place at the top level.
 */
export const Opening: Section = () => (
  <Section id="opening" title="Your renewal">
    <Greeting />
    <PriceChange />
  </Section>
);

section · a titled group Open ↗

Waartoe het wordt opgelost

De node zoals hij in het DocumentModel verschijnt: de JSON die een renderer aangereikt krijgt. Geen opmaak, geen lay-out.

{
  "id": "opening",
  "kind": "section",
  "title": "Your renewal",
  "children": [
    {
      "id": "greeting",
      "kind": "paragraph",
      "mode": "static",
      "text": "Dear Adaeze Nkemelu,"
    },
    {
      "id": "price-change",
      "kind": "paragraph",
      "mode": "static",
      "text": "Your Peak Anytime membership is rising by 5.1%, from £468 to £492 a year. That is £41 a month from 1 October 2026."
    }
  ]
}

Mixed and nested children

src/nodes/section/nested.node.tsx

A graph, then a nested section holding a graph and a dynamic paragraph.

import { Section } from "docxcelerate/template";
import { ClassMix } from "../graph/pie.node.tsx";
import { VisitsByMonth } from "../graph/bar.node.tsx";
import { NextSteps } from "../paragraph/dynamic.node.tsx";

/**
 * Children can be of any kind, including another section — the one place a
 * document tree gains depth. The resolved document nests exactly as this reads.
 */
export const YourYear: Section = () => (
  <Section id="your-year" title="Your year here">
    <VisitsByMonth />
    <Section id="activity-mix" title="Where the time went">
      <ClassMix />
      <NextSteps />
    </Section>
  </Section>
);

section · mixed and nested children Open ↗

Waartoe het wordt opgelost

De node zoals hij in het DocumentModel verschijnt: de JSON die een renderer aangereikt krijgt. Geen opmaak, geen lay-out.

{
  "id": "your-year",
  "kind": "section",
  "title": "Your year here",
  "children": [
    {
      "id": "visits-by-month",
      "kind": "graph",
      "mode": "static",
      "graphType": "bar",
      "title": "Visits to Riverside Leisure Centre",
      "valueAxisTitle": "Visits",
      "data": {
        "categories": [
          "Apr",
          "May",
          "Jun",
          "Jul",
          "Aug",
          "Sep"
        ],
        "series": [
          {
            "label": "Visits",
            "values": [
              11,
              14,
              9,
              16,
              18,
              12
            ]
          }
        ]
      },
      "caption": "Your visits to Riverside Leisure Centre, last six months"
    },
    {
      "id": "activity-mix",
      "kind": "section",
      "title": "Where the time went",
      "children": [
        {
          "id": "class-mix",
          "kind": "graph",
          "mode": "static",
          "graphType": "pie",
          "title": "Share of visits",
          "dataLabels": true,
          "data": {
            "categories": [
              "Swim",
              "Strength",
              "Classes"
            ],
            "series": [
              {
                "label": "Share of visits",
                "values": [
                  42,
                  33,
                  25
                ]
              }
            ]
          },
          "caption": "How you used the centre, by activity"
        },
        {
          "id": "next-steps",
          "kind": "paragraph",
          "mode": "dynamic",
          "text": "Your membership renews automatically on 1 October 2026. Nothing is needed from you unless you want to change plan."
        }
      ]
    }
  ]
}

Aantekeningen

De diepte zit in de boom, niet in de koppen. Beide meegeleverde renderers printen elke sectietitel op één niveau — <h2> in de browser, Kop 1 in de DOCX — hoe diep hij ook genesteld is. De JSON nestelt wel correct, dus dit is een beperking van de renderer, maar een document van drie lagen diep ziet er nog niet drie lagen diep uit.
Er is geen dynamische sectie. Een endpoint vult nodes in; het bepaalt niet wat het document bevat.
Een lege sectie rendert als een losse kop. Als de kinderen uit een filter komen dat leeg kan raken, controleer dat dan stroomopwaarts.

Deze pagina bewerken op GitHub ↗ Deze pagina als Markdown lezen