
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";
更改日志 :
参见 释放 用于提供更多信息.
捐款
欢迎提出要求,但请在作出任何修改之前先讨论一个问题.