react-pdf

@json-render/react-pdf

使用 @react-pdf/renderer 根据 JSON 规范生成 PDF 文档的 React PDF 渲染器。

安装

npm install @json-render/core @json-render/react-pdf

快速入门

import { renderToBuffer } from "@json-render/react-pdf";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "doc",
  elements: {
    doc: { type: "Document", props: { title: "Invoice" }, children: ["page"] },
    page: {
      type: "Page",
      props: { size: "A4" },
      children: ["heading", "table"],
    },
    heading: {
      type: "Heading",
      props: { text: "Invoice #1234", level: "h1" },
      children: [],
    },
    table: {
      type: "Table",
      props: {
        columns: [
          { header: "Item", width: "60%" },
          { header: "Price", width: "40%", align: "right" },
        ],
        rows: [
          ["Widget A", "$10.00"],
          ["Widget B", "$25.00"],
        ],
      },
      children: [],
    },
  },
};

const buffer = await renderToBuffer(spec);

渲染 API

import { renderToBuffer, renderToStream, renderToFile } from "@json-render/react-pdf";

// In-memory buffer
const buffer = await renderToBuffer(spec);

// Readable stream (pipe to HTTP response)
const stream = await renderToStream(spec);
stream.pipe(res);

// Direct to file
await renderToFile(spec, "./output.pdf");

所有渲染函数都接受一个可选的第二个参数：{ registry?, state?, handlers? }。

标准组件

组件	描述
Document	PDF 顶层容器（必须是根节点）
Page	包含纸张尺寸（A4、LETTER）、方向和边距的页面
View	通用容器（内边距、外边距、背景、边框）
Row, Column	支持间距、对齐和分布方式的弹性布局
Heading	h1-h4 标题文本
Text	正文文本（字号、颜色、字重、对齐方式）
Image	来自 URL 或 base64 的图像
Link	带文本和 href 的超链接
Table	包含带类型列和行的数据表格
List	有序列表或无序列表
Divider	水平分隔线
Spacer	垂直空白间距
PageNumber	当前页码和总页数

自定义目录

import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry, renderToBuffer } from "@json-render/react-pdf";
import { standardComponentDefinitions } from "@json-render/react-pdf/catalog";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({ label: z.string(), color: z.string().nullable() }),
      slots: [],
      description: "A colored badge label",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Badge: ({ props }) => (
      <View style={{ backgroundColor: props.color ?? "#e5e7eb", padding: 4 }}>
        <Text>{props.label}</Text>
      </View>
    ),
  },
});

const buffer = await renderToBuffer(spec, { registry });

外部存储（受控模式）

传入 StateStore，以全面控制状态：

嵌套列表可在外层循环中将 repeat.statePath 设置为 { "$item": "field" }。

import { createStateStore } from "@json-render/react-pdf";

const store = createStateStore({ invoice: { total: 100 } });
store.set("/invoice/total", 200);

服务端安全导入

导入 schema 和目录，而不引入 React：

import { schema, standardComponentDefinitions } from "@json-render/react-pdf/server";