Основы

Документы и узлы

Документ — это дерево типизированных компонентов, разрешённое на ваших данных.

Документ — это шаблон плюс тип данных. Шаблон представляет собой дерево узлов; разрешение его на данных даёт DocumentModel — чистый JSON, ничего не предполагающий о том, как всё это будет отрисовано.

Хелперы узлов

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

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

Идентификаторы важны: именно по ним эндпоинт генерации адресует отдельные узлы и именно благодаря им артефакты сборки остаются сравнимыми между запусками. Держите их неизменными.

Узел — это функция от ваших данных

import { paragraph } from "docxcelerate";
import type { DocumentData } from "../types.ts";

export const Greeting = paragraph<DocumentData>({
  id: "greeting",
  render: (data) => `Dear ${data.residentName},`,
});

render получает ваши типизированные данные и бюджет availableTokens, а возвращает строку. Языка шаблонов здесь нет — доступно всё, что выражается на TypeScript: условия, вспомогательные функции форматирования, импорты.

Разделы вкладываются, узлы — нет

section — единственная конструкция, допускающая вложенность. Её заголовок попадает в структуру документа:

import { section } from "docxcelerate";

section({ id: "opening", title: "Opening" }, [Greeting, Offer]);

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

<Section id="opening" title="Opening">
  <Greeting />
  <Offer />
</Section>

Оба варианта дают одно и то же дерево. О том, когда какая форма уместна, см. Шаблоны, а о том, что раздел может содержать и на какую глубину, — Раздел.

Сборка документа

import { buildDocument } from "docxcelerate";

const doc = await buildDocument(documentTemplate, data);

Результат — DocumentModel: schemaVersion, id, title и массив nodes. Ни стилей, ни вёрстки он не содержит — их позже применяет тот рендерер, который его получит.

Для проекта документа, описанного через defineDocumentProject, лучше использовать buildProjectPreviewDocument: он применяет стиль проекта и разрешает динамические узлы в их заполнители:

import { buildProjectPreviewDocument } from "docxcelerate";

const doc = await buildProjectPreviewDocument(project);

Именно это вызывает приложение предпросмотра, так что собранное в коде совпадает с тем, что вы видели в браузере.

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