@h1dd3nsn1p3r/pdf-invoice

中文文档
1.0.15发布于 2026/02/15MITTypeScriptESM + CJS近 30 天下载 4487

在苍蝇上生成PDF发票的简单而强大的节点JS库.

中文使用文档
文档目录17 节
  1. 安装
  2. 使用
  3. 有效载荷数据
  4. 企业
  5. 发票
  6. 客户
  7. 项目
  8. 收费
  9. QR 代码
  10. 说明
  11. 生成 PDF
  12. 配置
  13. 字符串
  14. 字体
  15. 类型
  16. 更改日志 :
  17. 捐款

PDF Invoice

XQ简单而强大的JavaScript库,它从一个JSON数据生成PDF发票,估计和付款收据. 它可用于任何节点JS/BunJS环境中.

安装

通过 npm :

npm install @h1dd3nsn1p3r/pdf-invoice

通过线条 :

yarn add @h1dd3nsn1p3r/pdf-invoice

通过 pnpm :

pnpm add @h1dd3nsn1p3r/pdf-invoice

使用

安装后,您可以使用 require 或者说 import数字 :

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

或 ES6 导入:

import { PDFInvoice } from "@h1dd3nsn1p3r/pdf-invoice";

PDFInvoice 以有效载荷为论据的类。 有效载荷是您要在发票上显示的数据 。 更多信息请检查 有效载荷数据 实例.

有效载荷数据

有效载荷是您要在发票上显示的数据 。 它是一个具有下列结构的天体:

const payload = {
    company: {
        logo: "<svg>...</svg>", // Optional. SVG logo of your company.
        name: "Festrol Corp.",
        address: "1711 W. El Segundo Blvd, Hawthorne, Canada - 90250",
        phone: "Tel: (+11) 245 543 903",
        email: "Mail: [email protected]",
        website: "Web: https://www.festrolcorp.io",
        taxId: "Tax ID: 1234567890", // Optional.
        bank: "IBAN: 1234567890AC", // Optional.
    },
    customer: {
        name: "John Doe",
        company: "Xero Inc.", // Optional.
        address: "1234 Main Street, New York, NY 10001",
        phone: "Tel: (555) 555-5555",
        email: "Mail: [email protected]",
        taxId: "Tax ID: 1234567890", // Optional.
    },
    invoice: {
        number: 1721, // String or number.
        date: "25/12/2023", // Default is current date.
        dueDate: "25/12/2023", // Default is current date.
        status: "Paid!",
        locale: "es-ES", // BCP 47 language tag. Default is "en-US".
        currency: "EUR", // ISO 4217 currency code. Default is "USD".
        path: "./invoice.pdf", // Required. Path where you would like to generate the PDF file.
        fee: 10, // Amount of fee to be added to the invoice (not percentage)
        orderDiscount: 10, // Amount of order discount (not percentage)
    },
    items: [
        {
            name: "Cloud VPS Server - Starter Plan",
            quantity: 1,
            price: 400,
            discount: 19, // Percentage of discount.
            tax: 0, // Tax percentage. Default is 0.
        },
        {
            name: "Domain Registration - example.com",
            quantity: 1,
            discount: 19, // Percentage of discount.
            price: 20,
            tax: 0, // Tax percentage. Default is 0.
        },
        {
            name: "Maintenance Charge - Yearly",
            quantity: 1,
            discount: 0, // Percentage of discount.
            price: 300,
            tax: 0, // Tax percentage. Default is 0.
        },
    ],
    qr: {
        data: "https://www.festrolcorp.io",
        width: 100, // Default is 50.
    },
    note: {
        text: "Thank you for your business.",
        italic: false, // Default is true.
    },
};

说明: 如果字符串很长, 你可以使用 \n 来打破界限。 例如:

const payload = {
    company: {
        name: "Festrol Corp.",
        address: "1711 W. El Segundo Blvd, Hawthorne, \n Canada - 90250",
        phone: "Tel: (+11) 245 543 903",
        email: "Mail: [email protected]",
    },
};

让我们来了解有效载荷中的每一个场.

企业

这是你的公司的信息。 它是一个具有下列结构的天体:

const company = {
    logo: "<svg>...</svg>", // Optional. SVG logo of your company.
    name: "Festrol Corp.", // Optional or required if logo is not supplied.
    address: "1711 W. El Segundo Blvd, Hawthorne, \n Canada - 90250", // Optional.
    phone: "Tel: (+11) 245 543 903", // Optional.
    email: "[email protected]", // Optional.
    website: "Web: https://www.festrolcorp.io" // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
    bank: "IBAN: 1234567890AC", // Optional.
}

现在,只有 svg 标志 可以使用。 如果您想要使用标识并不想使用公司名称, 请不要通过 name 字段。 其余的田地是可选的.

发票

这是发票的信息。 它是一个具有下列结构的天体:

const invoice = {
    number: 1721, // Required.
    date: "25/12/2023", // Optional. Default is current date.
    dueDate: "25/12/2023", // Optional. Default is current date.
    status: "Paid!", // Optional. Default is "Due pending!".
    locale: "es-ES", // Optional. Default is "en-US".
    currency: "EUR", // Optional. Default is "USD".
    fees: [
        {
            label: "Delivery Charge",
            amount: 10, // Number (not percentage)
            operation: "+",
        },
        {
            label: "Payment Processing",
            amount: 3.2, // Number (not percentage)
            operation: "-",
        },
    ], // Customer and business fees (Optional)
    orderDiscount: 10, // Optional. Total order discount (not percentage).
};

需要发票号码。 也许是 int 用来追踪你的发票 在多数情况下,它是一个独特的数字,可以指: order ID 或数据库中的发票序列号。 其余的田地是可选的.

这个 locale 是 BCP 47 语言标记。 默认是 en-US。 您可以找到语言标签列表 这里编辑 currency 是 ISO 4217 货币代码。 默认是 USD。 您可以找到货币代码列表 这里。关于地方和货币的更多信息,请参见 Mozilla 输入号 文档.

若为 path 在有效载荷中提供,然后在该地生成PDF。 例如:

const file = "invoice" + "-#" + 1729 + "-" + new Date().getTime(); // invoice-#1729-1630480000000
const location = path.join(__dirname, "/invoices/" + file + ".pdf");
const invoice = {
    path: location, // Required.
};

如果有效载荷中不提供路径,那么 PDF 将在当前工作目录中生成名称 invoice.pdf。 。 。 .

客户

这是关于你的客户的信息。 它是一个具有下列结构的天体:

const customer = {
    name: "John Doe", // Required.
    company: "Xero Inc.", // Optional.
    address: "1234 Main Street, New York, \n NY 10001", // Optional.
    phone: "Tel: (555) 555-5555", // Optional.
    email: "[email protected]", // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
};

需要客户的姓名。 其余的田地是可选的.

项目

物品是指您所销售的产品或服务. 这是一个 array a. 具有下列结构的物体:

const items = [
    {
        name: "Cloud VPS Server - Starter Plan", // Required.
        quantity: 1, // Required.
        price: 400, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
    {
        name: "Domain Registration - example.com", // Required.
        quantity: 1, // Required.
        price: 20, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
    {
        name: "Maintenance Charge - Yearly", // Required.
        quantity: 1, // Required.
        price: 300, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
];

这个 name, (中文(简体) ), quantity 财务报告和审定财务报表 price 编号。 其余的田地是可选的. 虽然发票上有单项,但需作为物品通过. 例如:

const items = [
    {
        name: "Cloud VPS Server - Starter Plan", // Required.
        quantity: 1, // Required.
        price: 400, // Required.
        tax: 0, // Optional. Tax percentage. Default is 0.
        discount: 0, // Optional. Item discount percentage. Default is 0.
    },
];

收费

最初在版本中采用了收费办法 1.0.12 信息技术 并作了修订 1.0.15 (中文(简体) )选中此项 讨论#53 更多信息.

收费是可选的,适用于发票分总金额. 这个 operation 字段可以是 + 或者说 -,取决于您是否想要从小计中加减费用。 这个 amount 字段指定收费金额。 这个 label 字段定义了收费标签,该标签将在发票上显示,其金额略低于子总额.

QR 代码

如果您要在发票上添加一个QR代码,那么您可以使用此字段. 它是一个具有下列结构的天体:

const qr = {
    data: "https://www.festrolcorp.io/", // Required. The data that you want to encode in the QR code.
    width: "100", // Optional. Default is 50.
};

这个 data 字段。 您想要在 QR 代码中编码的数据 。 这个 width 字段是可选的。 它是以像素表示的 QR 代码的宽度 。 默认是 50建议的QR宽度为30-100.

说明

如果您要在发票上添加注释, 请使用此字段 。 它是一个有以下结构的字符串:

const note = "Thank you for your business.";

生成 PDF

有效载荷一旦准备好,就可以使用以下代码生成PDF:

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

const handleInvoice = async (): Promise<void> => {
    const payload = {
        // Prepare payload.
    };

    /**
     * Create the invoice.
     */
    const invoice = new PDFInvoice(payload);
    const pdf = await invoice.create(); // Returns promise, await it.

    console.log(pdf); // Full path to the PDF file.
};

handleInvoice();

一旦你打电话给 create 方法,它会回报一个承诺。 你要么用,要么用 async/await 或者说 .then() 来兑现诺言 这个 create 如果 PDF 生成成功, 方法将把路径返回到 PDF 文件。 否则,它就会出错.

配置

如果需要,您可以更改发票的配置。 它是一个具有下列结构的天体:

字符串

发票中使用的所有文字串可以定制. 例如:

const { PDFInvoice } = require("@h1dd3nsn1p3r/pdf-invoice");

const create = async (): Promise<void> => {
    const payload = {
        // ....
    };

    const config = {
        // Custom labels.
        string: {
            invoice: "F A C T U A",
            refNumber: "Referencia",
            date: "Fecha",
            dueDate: "Fecha de vencimiento",
            status: "Estado",
            billTo: "Facturar a",
            item: "Artículo",
            quantity: "Cantidad",
            price: "Precio",
            tax: "Impuesto",
            total: "Total",
            subTotal: "Subtotal",
            grandTotal: "Grand Total", // Added in v1.0.11
        },
    };

    // Create the invoice.
    const invoice = new PDFInvoice(payload, config);
    const pdf = await invoice.create();

    console.log(pdf);
};

字体

以下是库内可用的字体:

  • 螺旋桨
  • 时间
  • 库里尔

所有这三种字体都包括正体,粗体,斜体和粗体-斜体等风格. 您可以在配置对象中使用它们 。 例如:

const config = {
    // ....
    style: {
        font: "Helvetica", // "Helvetica", "Times", "Courier"
        fontSize: 10, // Optional. Default is 10.
        lineHeight: 1.8, // Optional. Default is 1.8.
        color: "#000000", // Optional. Default is black.
    },
};

任意字体都可以使用 font 选项 TTF 文件路径。 例如:

const config = {
    // ....
    font: {
        Noto: {
            normal: path.join(__dirname, "fonts/noto/regular.ttf"),
            italics: path.join(__dirname, "fonts/noto/italic.ttf"),
            bold: path.join(__dirname, "fonts/noto/bold.ttf"),
            bolditalics: path.join(__dirname, "fonts/noto/bold-italic.ttf"),
        },
    },
    style: {
        font: "Noto",
        fontSize: 10, // Optional. Default is 10.
        lineHeight: 1.8, // Optional. Default is 1.8.
        color: "#000000", // Optional. Default is black.
    },
};

如果您需要更多信息, 请检查 实例在例子中,我使用了"Noto"和 TTF 诺托字体的文件包含在 fonts 目录。 如果您有非线性字符,那么您可以使用任何支持字符的自定义字体.

类型

此库用 TypeScript 写成. 如果您需要导入类型, 您可以从 global.d.ts 文档。 参见 全球类型 文档以获取更多信息.

示例

import type {
    CompanyInfo,
    CustomerInfo,
    InvoiceInfo,
    ItemInfo,
    QRInfo,
    InvoicePayLoad,
} from "@h1dd3nsn1p3r/pdf-invoice/global.d.ts";

更改日志 :

参见 释放 用于提供更多信息.

捐款

欢迎提出要求,但请在作出任何修改之前先讨论一个问题.

版本与发布记录

@h1dd3nsn1p3r/pdf-invoice 共发布 15 个版本,首次发布于 2024/01/03;过去 12 个月发布了 3 个版本。

版本发布日期距今
1.0.15latest2026/02/159 个月前
1.0.142026/01/0910 个月前
1.0.132026/01/0710 个月前
1.0.122025/10/141.1 年前
1.0.102025/03/181.7 年前
1.0.92024/11/112 年前

关于 @h1dd3nsn1p3r/pdf-invoice 的常见问题

@h1dd3nsn1p3r/pdf-invoice 是什么?

在苍蝇上生成PDF发票的简单而强大的节点JS库.

如何安装 @h1dd3nsn1p3r/pdf-invoice?

在项目目录运行 npm install @h1dd3nsn1p3r/pdf-invoice,或使用 pnpm add / yarn add / bun add。

@h1dd3nsn1p3r/pdf-invoice 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@h1dd3nsn1p3r/pdf-invoice 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@h1dd3nsn1p3r/pdf-invoice 可以商用吗?

@h1dd3nsn1p3r/pdf-invoice 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@h1dd3nsn1p3r/pdf-invoice 的下载量有多少?

根据 npm 官方下载统计,@h1dd3nsn1p3r/pdf-invoice 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,487 次,日均约 150 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@h1dd3nsn1p3r/pdf-invoice 还在维护吗?

最新版本 1.0.15 发布于 2026/02/15(9 个月前);至今共发布 15 个版本,其中过去 12 个月发布了 3 个;首次发布于 2024/01/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。