# @e-invoice-eu/core 中文文档 规范地址：https://npmcn.com/package/%40e-invoice-eu/core/ 版本：3\.4\.3 npm 元数据更新时间：2026-11-04T16:53:41.519Z 中文译文更新时间：2026-11-13T03:00:42.851Z 软件包许可：WTFPL 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40e-invoice-eu/core 原文对照：https://npmcn.com/package/%40e-invoice-eu/core/?lang=original 项目主页：https://github.com/gflohr/e-invoice-eu/tree/main/packages/core#readme 源码仓库：https://github.com/gflohr/e-invoice-eu ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21.3 MB，48 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：8 个 - 首次发布：2025-03-30T12:15:48.648Z - 最新版本发布：2026-11-04T16:53:41.189Z - 近 30 天下载量：154329（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：43（近 12 个月 22 个） ## 中文简介 从LibreOffice Calc/Excel数据或JSON中生成符合EN16931(Factur-X/ZUGFERD,UBL,CII,XRechnung aka X-Rechnung)的电子发票. ## 安装 ```sh npm install @e-invoice-eu/core ``` 也可以使用：`pnpm add @e-invoice-eu/core`、`yarn add @e-invoice-eu/core`、`bun add @e-invoice-eu/core` ## README ![](https://raw.githubusercontent.com/gflohr/e-invoice-eu/main/assets/e-invoice-eu-logo-2.webp) [![licence](https://img.shields.io/badge/licence-WTFPL-blue)](http://www.wtfpl.net/) [![price](https://img.shields.io/badge/price-FREE-green)](https://github.com/gflohr/e-invoice-eu/blob/main/LICENSE) [![coverage](https://img.shields.io/coverallsCoverage/github/gflohr/e-invoice-eu?branch=main)](https://coveralls.io/github/gflohr/e-invoice-eu?branch=main) [![downloads](https://img.shields.io/npm/dw/%40e-invoice-eu%2Fcore)](https://www.npmjs.com/package/@e-invoice-eu/core) [![documentation](https://img.shields.io/badge/documentation-read-green)](https://gflohr.github.io/e-invoice-eu) [![help](https://img.shields.io/badge/help-ask--a--question-green)](https://notebooklm.google.com/notebook/f5783dde-ebe6-4610-bac1-f181fdf45f94) [![listed on](https://img.shields.io/badge/listed%20on-awesome--europe-ffcc00?logo=europeanunion&logoColor=ffcc00&labelColor=003399)](https://github.com/GeiserX/awesome-europe#readme) [![stand with](https://img.shields.io/badge/stand%20with-Ukraine%F0%9F%87%BA%F0%9F%87%A6-ffc107)](https://www.standwithukraineeurope.com/en/) # 电子发票-欧盟 用于生成符合电子发票的 EN16931 的自由和开源工具链 (Factur-X/ZUGFERD、UBL、CII、XRechnung)来自流行电子表格格式或 贾森. 此软件包包含 `@e-invoice-eu/core`双方 [电子发票- 欧盟命令行工具](https://github.com/gflohr/e-invoice-eu/tree/main/apps/cli) 编辑 [电子发票-欧盟网络服务](https://github.com/gflohr/e-invoice-eu/tree/main/apps/server) 用它作为基础. ## 目录 - [特征](https://npmcn.com/package/%40e-invoice-eu/core/#readme-features) - [文档](https://npmcn.com/package/%40e-invoice-eu/core/#readme-documentation) - [安装](https://npmcn.com/package/%40e-invoice-eu/core/#readme-installation) - [使用量](https://npmcn.com/package/%40e-invoice-eu/core/#readme-usage) - [进口/要求图书馆](https://npmcn.com/package/%40e-invoice-eu/core/#readme-importingrequiring-the-library) - [从电子表格文件创建发票数据](https://npmcn.com/package/%40e-invoice-eu/core/#readme-creating-invoice-data-from-spreadsheet-files) - [从内部格式的数据生成发票](https://npmcn.com/package/%40e-invoice-eu/core/#readme-generating-an-invoice-from-data-in-the-internal-format) - [参数 `format`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-format) - [参数 `lang`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-lang) - [参数 `embedPDF`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-embedpdf) - [参数 `pdf`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-pdf) - [参数 `data`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-data) - [参数 `attachments`](https://npmcn.com/package/%40e-invoice-eu/core/#readme-argument-attachments) - [获得支持的格式](https://npmcn.com/package/%40e-invoice-eu/core/#readme-getting-supported-formats) - [获取 JSON Schema 定义](https://npmcn.com/package/%40e-invoice-eu/core/#readme-getting-the-json-schema-definitions) - [报告错误](https://npmcn.com/package/%40e-invoice-eu/core/#readme-reporting-bugs) - [版权](https://npmcn.com/package/%40e-invoice-eu/core/#readme-copyright) - [免责声明](https://npmcn.com/package/%40e-invoice-eu/core/#readme-disclaimer) ## 特征 库可以以下列格式创建电子发票: 1 - 跨行业发票-CII - 世界商业语言-UBL - Factur-X/ZUGFERD(所有简介,包括XRECHNUNG),配有PDF/A的完整支持 电子发票可直接取自 [电子发票-欧盟内部 格式](https://gflohr.github.io/e-invoice-eu/en/docs/details/internal-format/) 或通过 [绘图定义](https://gflohr.github.io/e-invoice-eu/en/docs/details/mapping/) 从流行的电子表格格式中 `.ods`, (中文(简体) ), `.xlsx`, (中文(简体) ), `.csv`,, , , , , , , , . 库以 TypeScript 执行,并提供完整的类型定义 从盒子里出来。 不需要额外的@ types 软件包 。 所有的数据结构, 包括内部发票格式和制图定义的 完全输入,确保全面的IntelliSense支持. 该库作为ES模块"CommonJS"和"UMD"可供使用,使其成为了 兼容浏览器环境和像Node.js这样的JavaScript运行时间. ## 文档 报告的一般文件 `e-invoice-eu` 可在 [`e-invoice-eu` GitHub 页面](https://github.com/gflohr/e-invoice-eu/tree/main/packages/core)。 。 。 . 参考文献请查看 [API 文档](https://gflohr.github.io/e-invoice-eu/api-docs/)。 。 。 . ## 安装 ```sh npm install @e-invoice-eu/core ``` ## 使用量 ### 进口/要求图书馆 如果你拥有 `import` 关键字 : ```typescript import { InvoiceService, MappingService } from '@e-invoice-eu/core'; ``` 与 `require`数字 : ```javascript const { InvoiceService, MappingService } = require('@e-invoice-eu/core'); ``` 在浏览器中 : ```html ``` ### 从电子表格文件创建发票数据 对于此可选步骤, 您需要两个电子表格文件作为 `Buffer` (单位:千美元) 绘图定义为 [`Mapping`](https://gflohr.github.io/e-invoice-eu/api-docs/interfaces/Mapping.html) 对象 : ```typescript import { MappingService } from '@e-invoice-eu/core'; const mappingService = new MappingService(console); const invoice = mappingService.transform( spreadsheet, // a `Buffer` 'Factur-X-Extended', // see https://gflohr.github.io/e-invoice-eu/en/docs/basics/supported-formats/ mapping, // a `Mapping` ); ``` 回来的 `invoice` 对象是一个 [`Invoice`](https://gflohr.github.io/e-invoice-eu/api-docs/interfaces/Invoice.html) 实例。 它还不是 XML 字符串或 PDF 缓冲器 ! ### 从内部格式的数据生成发票 你可以自己提供发票数据 [`Invoice`](https://gflohr.github.io/e-invoice-eu/api-docs/interfaces/Invoice.html) 实例或您可以通过电子表格数据和映射定义创建它 显示于 [前一节](https://npmcn.com/package/%40e-invoice-eu/core/#readme-creating-invoice-data-from-spreadsheet-files)。 。 。 . ```typescript import { InvoiceService } from '@e-invoice-eu/core'; const invoiceService = new InvoiceService(console); const renderedInvoice = await invoiceService.generate(invoiceData, options); ``` 见本摘要 `options` (可选选项被标记为 问号 `?`: | 名称 | 类型 | 说明 | | --- | --- | --- | | 格式 | `string` | (单位:千美元) [支持的格式](https://gflohr.github.io/e-invoice-eu/en/docs/basics/supported-formats/) | | 朗语 | `string` | 语言标识符类似 `fr-fr` | | 嵌入PDF吗? | `boolean` | 通过 `true` 如果 PDF 版本被嵌入到 XML 输出中 | | pdf吗? | [`FileInfo`](https://gflohr.github.io/e-invoice-eu/api-docs/types/FileInfo.html) | 发票的PDF版本 | | 数据? | [`FileInfo`](https://gflohr.github.io/e-invoice-eu/api-docs/types/FileInfo.html) | 发票电子表格文件 | | 附件吗? | [`FileInfo[]`](https://gflohr.github.io/e-invoice-eu/api-docs/types/FileInfo.html) | 任意的附件数量 | #### 参数 `format` 这里包含了电子发票的格式作为对大小写不敏感字符串. 你个 也可以使用别名. 譬如说, `Factur-X-Comfort` 是用于 `Factur-X-EN16931`。 。 。 . #### 参数 `lang` 语言标识符类似 `fr-fr`。这只用于 Factur-X/ZUGFERD pDF XMP meta数据中某些罐装文本的格式. #### 参数 `embedPDF` 这只用于纯 XML 格式( 所有不是 Factur-X/ZUGFERD). (原始内容存档于2018-09-27). 如果有真实价值, 发票的PDF版本 被嵌入为 XML 中被编码的 Base64 字符串. #### 参数 `pdf` 有两个情况需要这样做: 1. 格式为Factur-X/ZUGFERD格式并 `data` 曾经 **没有** 页:1. 2. 格式是纯 XML 格式, `embedPDF` 已具体说明 `data` 未指定. #### 参数 `data` 发票的电子表格版本。 如果需要PDF, 要么是因为 嵌入式PDF是为纯XML指定的,或者因为格式是Factur-X/ZUGFERD, [自由办公室](https://libreoffice.org/) 在渲染电子表格时引用 作为PDF. 如果在浏览器中使用此特性, 将触发例外 . #### 参数 `attachments` 您可以指定任意附加附件的数量. 在纯 XML 格式中,它们被嵌入为 Base64 编码字符串 在 XML 中。 在Factur-X/ZUGFERD的情况下,它们附在PDF上, 附加于强制性附件 `factur-x.xml`。 。 。 . ### 获得支持的格式 ```typescript import { FormatFactoryService } from '@e-invoice-eu/core'; const factoryService = new FormatFactoryService(); const formats = factoryService.listFormatServices(); ``` 单位 `format` 您将找到一组 [`FormatInfo`](https://gflohr.github.io/e-invoice-eu/api-docs/types/FormatInfo.html) 对象. ### 获取 JSON Schema 定义 ```typescript import { invoiceSchema, mappingSchema } from '@e-invoice-eu/core'; ``` 这些变量包含用于 [`Invoice`](https://gflohr.github.io/e-invoice-eu/api-docs/types/Invoice.html) 财务报告和审定财务报表 [`Mapping`](https://gflohr.github.io/e-invoice-eu/api-docs/types/Mapping.html) 接口。 这些策略可以传递给 Ajv 实例的编译方法的参数,参见 [https://ajv.js.org/api.html#ajv-compile-schema-object-data-any-boolean-promise-any (中文(简体) )](https://ajv.js.org/api.html#ajv-compile-schema-object-data-any-boolean-promise-any) 来了解更多情况! 计划有型 [`JSONSchemaType`](https://ajv.js.org/guide/typescript.html#utility-types-for-schemas) 财务报告和审定财务报表 [`JSONSchemaType`](https://ajv.js.org/guide/typescript.html#utility-types-for-schemas) 页:1. ## 报告错误 请报告错误 [https://github.com/gflohr/e-invoice-eu/ issues (中文(简体) )](https://github.com/gflohr/e-invoice-eu/issues)。 。 。 . ## 版权 版权(C)2024-2026 Guido Flohr [guido.flohr@cantanea.com 页面存档备份,存于互联网档案馆](mailto:guido.flohr@cantanea.com),所有数据 保留的权利. 这是免费软件,可按以下规定使用: [WPFPL (英语)](http://www.wtfpl.net/)。 。 。 . ## 免责声明 这个免费软件是用最谨慎的方式写的,但是.. 它可能包含错误的所有软件。 冒着自己的风险使用! 没有 保证和无责任. ## 常见问题 ### @e-invoice-eu/core 是什么？ 从LibreOffice Calc/Excel数据或JSON中生成符合EN16931\(Factur-X/ZUGFERD,UBL,CII,XRechnung aka X-Rechnung\)的电子发票\. ### 如何安装 @e-invoice-eu/core？ 在项目目录运行 npm install @e-invoice-eu/core，或使用 pnpm add / yarn add / bun add。 ### @e-invoice-eu/core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @e-invoice-eu/core 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @e-invoice-eu/core 可以商用吗？ @e-invoice-eu/core 使用 WTFPL 许可。声明的许可为 WTFPL，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。 ### @e-invoice-eu/core 的下载量有多少？ 根据 npm 官方下载统计，@e-invoice-eu/core 在 2026/10/13 – 2026/11/11 这 30 天内被下载 154,329 次，日均约 5,144 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @e-invoice-eu/core 还在维护吗？ 最新版本 3\.4\.3 发布于 2026/11/05（8 天前）；至今共发布 43 个版本，其中过去 12 个月发布了 22 个；首次发布于 2025/03/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。