Начните отсюда

Проекты документов

Файлы, из которых состоит один документ, за что отвечает каждый и какая конфигурация их окружает.

В workspace на каждый документ приходится один проект документа. Каждый — это каталог в documents/ с единственной точкой входа, так что документ можно перемещать, копировать и ревьюить как одно целое.

Создайте проект

dxcl document new tenancy-renewal --title "Tenancy Renewal"

Запустите команду без аргументов, чтобы имя и заголовок спросили у вас.

documents/tenancy-renewal/
  document.project.ts
  document.tsx
  document-style.ts
  preview-data.ts
  types.ts
  derivers/
    index.ts
  nodes/
    greeting.node.tsx
    intro.node.tsx
    index.ts

Разделение здесь и есть суть. Каждый файл отвечает на один вопрос:

Файл	Что в нём
`types.ts`	Контракт данных — что нужно документу, чтобы быть написанным
`preview-data.ts`	Один экземпляр этого контракта, для предпросмотра
`document.tsx`	Только структура: какие узлы, в каких секциях, в каком порядке
`nodes/`	По компоненту на узел плюс `index.ts`, который их экспортирует
`document-style.ts`	Шрифты, интервалы и поля для собранного `.docx`
`derivers/index.ts`	Именованные функции, которые движок выполняет на каждый документ
`document.project.ts`	Связывает всё перечисленное и даёт документу имя

Точка входа

import { defineDocumentProject } from "docxcelerate/document";
import { derivers } from "./derivers/index.ts";
import { documentTemplate } from "./document.tsx";
import { documentStyle } from "./document-style.ts";
import { previewData } from "./preview-data.ts";
import type { DocumentData } from "./types.ts";

export default defineDocumentProject<DocumentData>({
  id: "tenancy-renewal",
  name: "Tenancy Renewal",
  version: "0.1.0",
  template: documentTemplate,
  previewData,
  derivers,
  style: documentStyle,
  previewOptions: {
    availableTokens: 800,
  },
});

Поле	Что определяет
`id`	Как документ адресуется — в артефактах и со стороны движка
`name`	Что человек видит в приложении предпросмотра
`version`	Проставляется в каждый артефакт, который собирает этот проект
`template`	Дерево, из `document.tsx`
`previewData`	То, на чём разрешает предпросмотр
`derivers`	Значения, вычисляемые на каждый документ, а не на сборку
`style`	Стиль, применяемый при сборке файла
`previewOptions.availableTokens`	Бюджет, о котором сообщает `useAvailableTokens`

Приложение предпросмотра находит проекты глобом по document.project.ts, так что новый документ появляется в списке, как только он существует. Регистрировать его нигде не нужно.

Держите данные предпросмотра честными

preview-data.ts — единственные данные, на которых большая часть документа вообще когда-либо будет собрана, и потому они заслуживают больше внимания, чем им обычно достаётся:

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

export const previewData: DocumentData = {
  recipientName: "Avery",
  city: "Berlin",
};

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

Конфигурация workspace

docxcelerate.config.json лежит наверху workspace и распространяется на каждый документ в нём. Он хранит именованные пресеты поведения сборки и загрузки:

{
  "schemaVersion": "docxcelerate.config/v0",
  "activePreset": "local",
  "presets": {
    "local": {
      "build": { "outDir": "build" },
      "upload": { "endpoint": "", "method": "POST", "headers": {}, "body": "document" }
    }
  }
}

activePreset выбирает, какой из них действует, — так локальная настройка и staging-движок сосуществуют, не заставляя править конфигурацию между запусками. С пустым upload.endpoint всё по-прежнему собирается: вы получаете артефакты на диске вместо готового документа.

Workspace и конфигурация документирует каждое поле, а артефакты сборки рассказывают, что сборка записывает.

Куда дальше

Шаблоны — вычисляемая структура, переиспользуемые части и что меняется при публикации
Движок — опубликовать документ и писать из него
Команды — каждый флаг CLI

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