Nodos
Section
El único nodo que contiene otros nodos, y el encabezado en que se convierte su título.
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
- Clase de nodo
- section
- Categoría
- Estructura
- Se resuelve
- Locally
- Hijos
- Any node, including other sections. No depth limit.
| Opción | Tipo | Qué hace |
|---|---|---|
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 obligatorio | 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. |
Escribir una
Una sección recibe sus opciones y sus hijos — componentes de nodo, los mismos valores que colocarías en el nivel superior de un documento:
import { section } from "docxcelerate";
export const Opening = section<MemberData>({ id: "opening", title: "Your renewal" }, [
Greeting,
PriceChange,
]);En TSX la misma llamada se lee como marcado:
<Section id="opening" title="Your renewal">
<Greeting />
<PriceChange />
</Section>Ambas producen el mismo árbol. Plantillas explica cuándo merece la pena cada forma.
Los hijos pueden ser cualquier cosa
Párrafos, imágenes, gráficos, un marcador de índice o más secciones. Ningún otro nodo tiene hijos, así que la profundidad de un documento es la profundidad de sus secciones.
Nada cambia en un nodo por haberse metido dentro de una sección: se resuelve igual a cualquier profundidad, y su id no gana ningún prefijo.
Los títulos pasan al esquema
title es obligatorio, y no es decoración — se convierte en el encabezado sobre
los hijos y en la entrada a partir de la cual se construye un índice. Un grupo
que no quiere encabezado no quiere sección; pon los nodos directamente en el
documento.
Variantes
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>
);En qué se resuelve
El nodo tal como aparece en el DocumentModel: el JSON que recibe un renderizador. Sin estilos, sin maquetación.
{
"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>
);En qué se resuelve
El nodo tal como aparece en el DocumentModel: el JSON que recibe un renderizador. Sin estilos, sin maquetación.
{
"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."
}
]
}
]
}Notas
- La profundidad está en el árbol, no en los encabezados. Los dos
renderizadores incluidos imprimen todos los títulos de sección en un solo nivel
—
<h2>en el navegador, Título 1 en el DOCX — por muy hondo que anide. El JSON sí anida correctamente, así que es una limitación del renderizador, pero un documento de tres niveles todavía no parecerá de tres niveles. - No existe la sección dinámica. Un endpoint rellena nodos; no decide qué contiene el documento.
- Una sección vacía se renderiza como un encabezado suelto. Si los hijos vienen de un filtro que puede quedarse sin nada, compruébalo aguas arriba.