# @h1dd3nsn1p3r/pdf-invoice 中文文档

规范地址：https://npmcn.com/package/%40h1dd3nsn1p3r/pdf-invoice/

版本：1\.0\.15
npm 元数据更新时间：2026-02-14T16:37:16.762Z
中文译文更新时间：2026-11-17T19:23:40.126Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40h1dd3nsn1p3r/pdf-invoice
原文对照：https://npmcn.com/package/%40h1dd3nsn1p3r/pdf-invoice/?lang=original
项目主页：https://github.com/h1dd3nsn1p3r/pdf-invoice
源码仓库：https://github.com/h1dd3nsn1p3r/pdf-invoice

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：211 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-01-03T06:02:40.152Z
- 最新版本发布：2026-02-14T16:37:16.648Z
- 近 30 天下载量：4487（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 3 个）

## 中文简介

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

## 安装

```sh
npm install @h1dd3nsn1p3r/pdf-invoice
```

也可以使用：`pnpm add @h1dd3nsn1p3r/pdf-invoice`、`yarn add @h1dd3nsn1p3r/pdf-invoice`、`bun add @h1dd3nsn1p3r/pdf-invoice`

## README

![PDF Invoice](https://github.com/h1dd3nsn1p3r/pdf-invoice/blob/development/examples/hero.png)

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

## 安装

通过 npm :

```bash
npm install @h1dd3nsn1p3r/pdf-invoice
```

通过线条 :

```bash
yarn add @h1dd3nsn1p3r/pdf-invoice
```

通过 pnpm :

```bash
pnpm add @h1dd3nsn1p3r/pdf-invoice
```

## 使用

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

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

或 ES6 导入:

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

`PDFInvoice` 以有效载荷为论据的类。 有效载荷是您要在发票上显示的数据 。 更多信息请检查 [有效载荷数据](https://github.com/h1dd3nsn1p3r/pdf-invoice/blob/stable/examples/example.ts) 实例.

## 有效载荷数据

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

```js
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: hello@festrol.io",
        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: joe@example.com",
        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` 来打破界限。 例如:

```js
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@yourcompany.com",
    },
};
```

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

### 企业

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

```js
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: "hello@company.com", // Optional.
    website: "Web: https://www.festrolcorp.io" // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
    bank: "IBAN: 1234567890AC", // Optional.
}
```

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

### 发票

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

```js
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`。 您可以找到语言标签列表 [这里](http://4umi.com/web/html/languagecodes.php)编辑 `currency` 是 ISO 4217 货币代码。 默认是 `USD`。 您可以找到货币代码列表 [这里](https://www.iban.com/currency-codes)。关于地方和货币的更多信息,请参见 [Mozilla 输入号](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) 文档.

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

```js
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`。 。 。 .

### 客户

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

```js
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: "joedeo@example.com", // Optional.
    taxId: "Tax ID: 1234567890", // Optional.
};
```

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

### 项目

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

```js
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` 编号。 其余的田地是可选的. 虽然发票上有单项,但需作为物品通过. 例如:

```js
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 信息技术](https://github.com/h1dd3nsn1p3r/pdf-invoice/releases/tag/v1.0.12) 并作了修订 [1.0.15 (中文(简体) )](https://github.com/h1dd3nsn1p3r/pdf-invoice/releases/tag/v1.0.15)选中此项 [讨论#53](https://github.com/h1dd3nsn1p3r/pdf-invoice/issues/53) 更多信息.

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

### QR 代码

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

```js
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.

### 说明

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

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

## 生成 PDF

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

```js
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 文件。 否则,它就会出错.

## 配置

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

### 字符串

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

```js
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);
};
```

### 字体

以下是库内可用的字体:

-   螺旋桨
-   时间
-   库里尔

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

```js
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` 文件路径。 例如:

```js
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.
    },
};
```

如果您需要更多信息, 请检查 [实例](https://github.com/h1dd3nsn1p3r/pdf-invoice/blob/development/examples/example.ts)在例子中,我使用了"Noto"和 `TTF` 诺托字体的文件包含在 `fonts` 目录。 如果您有非线性字符,那么您可以使用任何支持字符的自定义字体.

## 类型

此库用 TypeScript 写成. 如果您需要导入类型, 您可以从 `global.d.ts` 文档。 参见 [全球类型](https://github.com/h1dd3nsn1p3r/pdf-invoice/blob/stable/global.d.ts) 文档以获取更多信息.

示例

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

## 更改日志 :

参见 [释放](https://github.com/h1dd3nsn1p3r/pdf-invoice/releases) 用于提供更多信息.

## 捐款

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

## 常见问题

### @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 和提交记录判断。

