@bageventjs/pdf-generator

一个用于生成参会者胸卡PDF的工具库。

安装

npm install @bageventjs/pdf-generator

依赖

该工具需要以下依赖：

• pdfkit - PDF生成库
• qrcode - 二维码生成库

快速开始

基本使用

const PDFGenerator = require('@bageventjs/pdf-generator')

// 创建PDFGenerator实例
const pdfGenerator = new PDFGenerator({
  tmpDir: '/tmp', // 临时文件目录，默认为系统临时目录
  fontPaths: {
    bold: '/path/to/bold-font.ttf',      // 粗体字体路径
    regular: '/path/to/regular-font.ttf', // 常规字体路径
    ibmBold: '/path/to/ibm-bold.ttf',    // IBM粗体字体（可选）
    ibmRegular: '/path/to/ibm-regular.ttf' // IBM常规字体（可选）
  },
  userId: 123456, // 用户ID（可选）
  eventId: 'event123', // 活动ID（可选）
  customizedData: { // 自定义数据（可选）
    link_code: 'YES',
    link: 'https://example.com/checkin'
  },
  onPdfGenerated: async (pdfPath, orientation) => {
    // PDF生成完成后的回调
    console.log('PDF已生成:', pdfPath)
    console.log('方向:', orientation)
    // 可以在这里执行打印等操作
  }
})

// 创建单个参会者的PDF
const pdfPath = await pdfGenerator.createPdf(
  attendee,
  badgeItemList,
  badge,
  badgesize
)

API 文档

PDFGenerator 类

构造函数

new PDFGenerator(options)

参数：

• options.tmpDir (string, 可选) - 临时文件存储目录，默认为系统临时目录
• options.fontPaths (object, 可选) - 字体路径配置
  • bold (string, 可选) - 粗体字体路径
  • regular (string, 可选) - 常规字体路径
  • ibmBold (string, 可选) - IBM粗体字体路径
  • ibmRegular (string, 可选) - IBM常规字体路径
• options.userId (number, 可选) - 用户ID
• options.eventId (string, 可选) - 活动ID
• options.customizedData (object, 可选) - 自定义数据对象
• options.onPdfGenerated (function, 可选) - PDF生成完成后的回调函数 (pdfPath, orientation) => void | Promise<void>

方法

createPdf

创建单个参会者的PDF文件。

async createPdf(attendee, badgeItemList, badge, badgesize) => Promise<string>

参数：

• attendee (Object) - 参会者信息对象
  • attendee_id (string, 必需) - 参会者ID
  • name (string, 可选) - 姓名
  • first_name (string, 可选) - 名
  • last_name (string, 可选) - 姓
  • barcode (string, 可选) - 条形码
  • ref_code (string, 可选) - 参考码
  • attendeeMap (Object, 可选) - 参会者字段映射
• badgeItemList (Array) - 胸卡项配置列表
• badge (Object) - 胸卡配置对象
• badgesize (Object) - 胸卡尺寸对象
  • width (number) - 宽度（毫米）
  • height (number) - 高度（毫米）

返回值：

• Promise<string> - PDF文件的完整路径

示例：

const attendee = {
  attendee_id: '12345',
  name: '张三',
  first_name: '三',
  last_name: '张',
  barcode: 'BARCODE123',
  ref_code: 'REF123',
  attendeeMap: {
    'field1': '值1',
    'field2': '值2'
  }
}

const badgeItemList = [
  {
    marginLeft: 10,
    marginRight: 20,
    width: 100,
    height: 30,
    filedType: 9, // 姓名字段
    fontSize: '16px',
    fontCenter: true
  },
  {
    marginLeft: 10,
    marginRight: 60,
    width: 80,
    height: 80,
    filedType: 2 // 二维码
  }
]

const badgesize = {
  width: 90, // mm
  height: 55 // mm
}

const pdfPath = await pdfGenerator.createPdf(
  attendee,
  badgeItemList,
  {},
  badgesize
)

createPdfAttendeeList

创建多个参会者的PDF文件（每个参会者一页）。

async createPdfAttendeeList(
  attendeeList,
  badgeItemList,
  badge,
  badgesize,
  getAttendeeProduct,
  getProduct
) => Promise<string>

参数：

• attendeeList (Array) - 参会者列表
• badgeItemList (Array) - 胸卡项配置列表
• badge (Object) - 胸卡配置对象
• badgesize (Object) - 胸卡尺寸对象
• getAttendeeProduct (Function, 可选) - 获取参会者产品信息的异步函数 (attendeeId, productId) => Promise<any>
• getProduct (Function, 可选) - 获取产品信息的异步函数 (productId) => Promise<any>

返回值：

• Promise<string> - PDF文件的完整路径

示例：

const attendeeList = [
  { attendee_id: '1', name: '张三', ... },
  { attendee_id: '2', name: '李四', ... }
]

// 如果需要获取产品信息
const getAttendeeProduct = async (attendeeId, productId) => {
  // 从数据库或API获取参会者产品信息
  return await db.findAttendeeProduct(attendeeId, productId)
}

const getProduct = async (productId) => {
  // 从数据库或API获取产品信息
  return await db.findProduct(productId)
}

const pdfPath = await pdfGenerator.createPdfAttendeeList(
  attendeeList,
  badgeItemList,
  {},
  badgesize,
  getAttendeeProduct,
  getProduct
)

creatNumPdf

创建指定数量的空白胸卡PDF（用于测试或模板）。

async creatNumPdf(badge, badgeItemList, num, badgesize) => Promise<string>

参数：

• badge (Object) - 胸卡配置对象
• badgeItemList (Array) - 胸卡项配置列表
• num (number) - 要创建的胸卡数量
• badgesize (Object) - 胸卡尺寸对象

返回值：

• Promise<string> - PDF文件的完整路径

示例：

const pdfPath = await pdfGenerator.creatNumPdf(
  {},
  badgeItemList,
  10, // 创建10个空白胸卡
  badgesize
)

createPdfStream

生成PDF文档流（不保存到文件），适用于需要直接处理PDF流的场景。

async createPdfStream(attendee, badgeItemList, badge, badgesize) => Promise<PDFDocument>

参数：

• attendee (Object) - 参会者信息对象
• badgeItemList (Array) - 胸卡项配置列表
• badge (Object) - 胸卡配置对象
• badgesize (Object) - 胸卡尺寸对象

返回值：

• Promise<PDFDocument> - PDF文档流对象

示例：

const doc = await pdfGenerator.createPdfStream(
  attendee,
  badgeItemList,
  {},
  badgesize
)

// 可以将流保存到文件或发送到客户端
doc.pipe(fs.createWriteStream('output.pdf'))

胸卡项配置 (BadgeItem)

胸卡项配置对象包含以下属性：

{
  marginLeft: number,      // 左边距（像素）
  marginRight: number,     // 上边距（像素）
  width: number,           // 宽度（像素）
  height: number,          // 高度（像素）
  filedType: number,       // 字段类型（见下方说明）
  content: string,         // 内容（可选）
  formFieldId: string,     // 表单字段ID（可选）
  relatedId: string,       // 关联ID（可选）
  bold: string,            // 是否粗体：'bold'（可选）
  fontSize: string | number,  // 字体大小（px或数字）
  fontRight: boolean,      // 右对齐（可选）
  fontCenter: boolean      // 居中对齐（可选）
}

字段类型 (filedType) 说明：

• 2 - 条形码/二维码（使用参会者的 barcode 或 ref_code）
• 3 - 静态文本（使用 content 字段）
• 9 - 姓名字段（自动处理中英文姓名格式）
• 33 - 产品别名字段（需要提供 getAttendeeProduct 和 getProduct 函数）
• 34 - 产品名称字段（需要提供 getAttendeeProduct 和 getProduct 函数）
• 51 - 自定义二维码（使用 content 字段作为二维码内容）

使用示例

完整示例

const PDFGenerator = require('@bageventjs/pdf-generator')
const path = require('path')

// 初始化PDF工具
const pdfGenerator = new PDFGenerator({
  tmpDir: path.join(__dirname, 'temp'),
  fontPaths: {
    bold: path.join(__dirname, 'fonts', 'PingFang-Bold.ttf'),
    regular: path.join(__dirname, 'fonts', 'PingFang-Regular.ttf')
  },
  eventId: 'event123',
  customizedData: {
    link_code: 'YES',
    link: 'https://bagevent.com/checkin'
  },
  onPdfGenerated: async (pdfPath, orientation) => {
    console.log(`PDF已生成: ${pdfPath}`)
    // 可以在这里执行打印操作
    // await printPDF(pdfPath, orientation)
  }
})

// 准备数据
const attendee = {
  attendee_id: '12345',
  name: '张三',
  first_name: '三',
  last_name: '张',
  barcode: 'BARCODE123',
  attendeeMap: {
    'company': '示例公司',
    'title': '高级工程师'
  }
}

const badgeItemList = [
  {
    marginLeft: 20,
    marginRight: 20,
    width: 200,
    height: 40,
    filedType: 9, // 姓名
    fontSize: '20px',
    bold: 'bold',
    fontCenter: true
  },
  {
    marginLeft: 20,
    marginRight: 70,
    width: 100,
    height: 100,
    filedType: 2 // 二维码
  },
  {
    marginLeft: 20,
    marginRight: 180,
    width: 200,
    height: 30,
    filedType: 3, // 静态文本
    content: '欢迎参加活动',
    fontSize: '16px',
    fontCenter: true
  }
]

const badgesize = {
  width: 90,  // 90mm
  height: 55  // 55mm
}

// 生成PDF
try {
  const pdfPath = await pdfGenerator.createPdf(
    attendee,
    badgeItemList,
    {},
    badgesize
  )
  console.log('PDF生成成功:', pdfPath)
} catch (error) {
  console.error('生成PDF失败:', error)
}

批量生成PDF

const attendeeList = [
  { attendee_id: '1', name: '张三', ... },
  { attendee_id: '2', name: '李四', ... },
  { attendee_id: '3', name: '王五', ... }
]

const pdfPath = await pdfGenerator.createPdfAttendeeList(
  attendeeList,
  badgeItemList,
  {},
  badgesize
)

console.log('批量PDF已生成:', pdfPath)

注意事项

1. 字体文件：如果需要在PDF中显示中文，必须提供支持中文的字体文件（如 PingFang、思源黑体等）。

2. 临时文件：工具会在临时目录中创建二维码图片等临时文件，生成完成后会自动清理。确保临时目录有写入权限。

3. 二维码链接：如果设置了 customizedData.link_code = 'YES'，条形码类型的字段会自动生成带参数的链接。

4. 字段类型：不同的 filedType 对应不同的内容类型，请根据实际需求选择合适的类型。

5. 异步操作：所有PDF生成方法都是异步的，需要使用 await 或 .then() 来处理。

6. 错误处理：建议使用 try-catch 包裹PDF生成操作，以便处理可能的错误。

许可证

ISC

作者

于兴雷