pdf-generator

PDF 生成器

何时使用此技能

在以下情况下使用此技能：

• 根据数据或规范以编程方式创建 PDF 文档
• 使用动态数据填写 PDF 表单
• 为现有 PDF 添加水印、印章或叠加层
• 从 PDF 文件中提取文本和元数据
• 将多个 PDF 合并为一个文档
• 分析 PDF 结构和表单字段

在以下情况下不要使用此技能：

• 用户想要打开/查看 PDF（使用原生 PDF 查看器）
• 需要复杂的页面布局和流式文本（考虑使用 HTML 转 PDF 工具）
• 处理受密码保护的 PDF（支持有限）
• 需要对扫描文档进行 OCR

前提条件

• 已安装 Deno（https://deno.land/）
• 用于基于模板的操作的输入 PDF 文件
• 用于从头生成的 JSON 规范

快速入门

两种操作模式

1. 模板模式：修改现有 PDF 模板

   • 填写表单字段（文本、复选框、下拉菜单）
   • 添加叠加层（文本、图像、形状）
   • 合并 PDF

2. 从头生成模式：使用 JSON 规范创建全新的 PDF

说明

模式 1：基于模板生成

步骤 1a：分析模板

从现有 PDF 中提取表单字段和结构：

deno run --allow-read scripts/analyze-template.ts form-template.pdf > inventory.json

输出（inventory.json）：

{
  "filename": "form-template.pdf",
  "pageCount": 2,
  "title": "Application Form",
  "author": "Company Inc",
  "pages": [
    { "pageNumber": 1, "width": 612, "height": 792, "text": "..." }
  ],
  "formFields": [
    { "name": "FullName", "type": "text", "value": "" },
    { "name": "Email", "type": "text", "value": "" },
    { "name": "AgreeToTerms", "type": "checkbox", "value": false }
  ],
  "placeholders": [
    { "tag": "{{DATE}}", "location": "page 1", "pageNumber": 1 }
  ],
  "hasFormFields": true
}

步骤 1b：创建填写规范

创建 form-data.json：

{
  "formFields": [
    { "name": "FullName", "value": "John Smith" },
    { "name": "Email", "value": "[email protected]" },
    { "name": "AgreeToTerms", "value": true }
  ],
  "flattenForm": true
}

步骤 1c：生成已填写的 PDF

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  form-template.pdf form-data.json filled-form.pdf

添加叠加层（水印、印章）

创建 watermark-spec.json：

{
  "overlays": [
    {
      "type": "text",
      "page": 1,
      "x": 200,
      "y": 400,
      "text": "CONFIDENTIAL",
      "fontSize": 48,
      "color": { "r": 1, "g": 0, "b": 0 },
      "rotate": 45
    },
    {
      "type": "image",
      "page": 1,
      "x": 450,
      "y": 700,
      "path": "logo.png",
      "width": 100,
      "height": 50
    }
  ]
}

合并 PDF

创建 merge-spec.json：

{
  "prependPdfs": [
    { "path": "cover-page.pdf" }
  ],
  "appendPdfs": [
    { "path": "appendix-a.pdf", "pages": [1, 2, 3] },
    { "path": "appendix-b.pdf" }
  ],
  "excludePages": [5, 6]
}

模式 2：从头生成

步骤 2a：创建规范

创建 spec.json：

{
  "title": "Quarterly Report",
  "author": "Finance Team",
  "pages": [
    {
      "size": "A4",
      "elements": [
        {
          "type": "text",
          "x": 50,
          "y": 750,
          "text": "Q4 2024 Financial Report",
          "fontSize": 28,
          "font": "HelveticaBold",
          "color": { "r": 0, "g": 0, "b": 0.5 }
        },
        {
          "type": "line",
          "startX": 50,
          "startY": 740,
          "endX": 550,
          "endY": 740,
          "thickness": 2
        },
        {
          "type": "text",
          "x": 50,
          "y": 700,
          "text": "Executive Summary",
          "fontSize": 18,
          "font": "HelveticaBold"
        },
        {
          "type": "text",
          "x": 50,
          "y": 670,
          "text": "This quarter showed strong growth across all divisions...",
          "fontSize": 12,
          "maxWidth": 500,
          "lineHeight": 16
        }
      ]
    }
  ]
}

步骤 2b：生成 PDF

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.pdf

示例

示例 1：填写申请表

场景：自动填写一份求职申请表。

# 1. Analyze form to find field names
deno run --allow-read scripts/analyze-template.ts application.pdf --pretty

# 2. Create form-data.json with applicant info
# 3. Generate filled form
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  application.pdf form-data.json john-smith-application.pdf

示例 2：添加审批印章

场景：在文档中添加“APPROVED”印章。

stamp-spec.json：

{
  "overlays": [
    {
      "type": "rectangle",
      "page": 1,
      "x": 400,
      "y": 700,
      "width": 150,
      "height": 50,
      "color": { "r": 0.9, "g": 1, "b": 0.9 }
    },
    {
      "type": "text",
      "page": 1,
      "x": 410,
      "y": 720,
      "text": "APPROVED",
      "fontSize": 20,
      "font": "HelveticaBold",
      "color": { "r": 0, "g": 0.5, "b": 0 }
    },
    {
      "type": "text",
      "page": 1,
      "x": 410,
      "y": 705,
      "text": "2024-12-15",
      "fontSize": 10
    }
  ]
}

示例 3：创建含表格的报告

场景：生成一份带数据表格的简单报告。

report-spec.json：

{
  "title": "Sales Report",
  "pages": [{
    "size": "Letter",
    "elements": [
      {
        "type": "text",
        "x": 72,
        "y": 720,
        "text": "Monthly Sales Report",
        "fontSize": 24,
        "font": "HelveticaBold"
      },
      {
        "type": "table",
        "x": 72,
        "y": 680,
        "rows": [
          ["Product", "Units", "Revenue"],
          ["Widget A", "150", "$15,000"],
          ["Widget B", "75", "$11,250"],
          ["Widget C", "200", "$8,000"]
        ],
        "columnWidths": [150, 80, 100],
        "rowHeight": 25,
        "headerBackground": { "r": 0.9, "g": 0.9, "b": 0.9 }
      }
    ]
  }]
}

脚本参考

脚本	用途	权限
analyze-template.ts	从 PDF 中提取文本、元数据和表单字段	--allow-read
generate-from-template.ts	填写表单、添加叠加层、合并 PDF	--allow-read --allow-write
generate-scratch.ts	根据 JSON 规范创建 PDF	--allow-read --allow-write

元素类型（从头生成模式）

类型	描述	关键选项
text	文本内容	x、y、text、fontSize、font、color、rotate
image	PNG/JPEG 图像	x、y、path、width、height、opacity
rectangle	填充/描边矩形	x、y、width、height、color、borderColor
line	直线	startX、startY、endX、endY、thickness
circle	填充/描边圆形	x、y、radius、color、borderColor
table	基本表格布局	x、y、rows、columnWidths、rowHeight

可用字体

• Helvetica（默认）
• HelveticaBold
• HelveticaOblique
• TimesRoman
• TimesBold
• Courier
• CourierBold

页面尺寸

• A4（595.28 x 841.89 points）
• Letter（612 x 792 points）
• Legal（612 x 1008 points）
• 自定义：以 points 为单位的 [width, height]

常见问题与解决方案

问题：未找到表单字段

症状：提示字段名称不存在的错误。

解决方案：

1. 运行 analyze-template.ts 获取准确的字段名称
2. 字段名称区分大小写
3. 某些 PDF 中看似表单字段的文本实际上不可填写

问题：文本定位不准确

症状：文本出现在错误的位置。

解决方案：

• PDF 坐标从左下角（0,0）开始
• Y 轴向上递增，X 轴向右递增
• 使用 analyze-template.ts 查看页面尺寸

问题：图片未显示

症状：图片叠加层不可见。

解决方案：

1. 检查文件路径是否相对于 spec.json 所在位置
2. 确认图片格式为 PNG 或 JPEG
3. 确保坐标位于页面范围内

问题：合并后的 PDF 页面顺序错误

症状：页面顺序与预期不符。

解决方案：

• prependPdfs 会在模板前添加页面
• appendPdfs 会在模板后添加页面
• 使用 pages 数组选择特定页面：[1, 3, 5]

限制

• 不内置表格布局：表格需要手动指定列宽
• 仅支持标准字体：暂存模式不支持嵌入自定义字体
• 不支持文本流动：文本不会自动换行到下一页
• 表单字段创建能力有限：可以填写现有表单，但不能创建新字段
• 不支持加密：无法创建受密码保护的 PDF
• 仅支持基本图形：不支持渐变、图案或复杂路径
• 文本提取：可能无法在所有 PDF 上完美运行（取决于 PDF 结构）

相关技能

• pptx-generator：用于创建 PowerPoint 演示文稿
• docx-generator：用于创建 Word 文档
• xlsx-generator：用于创建 Excel 电子表格