Узлы

Section

Единственный узел, содержащий другие узлы, и заголовок, которым становится его название.

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

Хелперы: Section
Вид узла: section
Категория: Структура
Разрешается: Locally
Дочерние узлы: Any node, including other sections. No depth limit.

Опция	Тип	Что делает
`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`	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.

Как его написать

Раздел принимает свои опции и своих потомков — компоненты узлов, те же значения, которые вы поместили бы на верхнем уровне документа:

import { section } from "docxcelerate";

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

В TSX тот же вызов читается как разметка:

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

Оба варианта дают одно дерево. О том, когда какая форма себя оправдывает, — в Шаблонах.

Потомками может быть что угодно

Абзацы, изображения, графики, отметка оглавления или другие разделы. Больше ни у одного узла потомков нет, поэтому глубина документа — это глубина его разделов.

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

Заголовки попадают в структуру

title обязателен, и это не украшение: он становится заголовком над потомками и той строкой, из которой строится оглавление. Группе, которой заголовок не нужен, не нужен и раздел — поместите узлы прямо в документ.

Варианты

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 ↗

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

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

{
  "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 ↗

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

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

{
  "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."
        }
      ]
    }
  ]
}

Примечания

Глубина — в дереве, а не в заголовках. Оба поставляемых рендерера печатают заголовок любого раздела на одном уровне — <h2> в браузере и «Заголовок 1» в DOCX — как бы глубоко он ни был вложен. JSON вкладывается правильно, так что это ограничение рендерера, но документ с тремя уровнями пока не будет выглядеть трёхуровневым.
Динамического раздела не существует. Эндпоинт заполняет узлы; он не решает, что входит в документ.
Пустой раздел отрисуется как одинокий заголовок. Если потомки приходят из фильтра, который может опустеть, проверьте это выше по течению.

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