# @axenda/zatca 中文文档
规范地址：https://npmcn.com/package/%40axenda/zatca/
版本：1\.0\.4
npm 元数据更新时间：2022-04-04T17:09:23.155Z
中文译文更新时间：2026-11-07T14:47:15.332Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40axenda/zatca
原文对照：https://npmcn.com/package/%40axenda/zatca/?lang=original
项目主页：https://github.com/axenda/zatca#readme
源码仓库：https://github.com/axenda/zatca
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：19.1 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-11-18T21:23:01.347Z
- 最新版本发布：2021-11-19T23:16:00.010Z
- 近 30 天下载量：15202（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）
## 中文简介
[](https://npmjs.org/package/@axenda/zatca)
## 安装
```sh
npm install @axenda/zatca
```
也可以使用：`pnpm add @axenda/zatca`、`yarn add @axenda/zatca`、`bun add @axenda/zatca`
## README
# ZATCA (法图拉) QR- Code 执行
[](https://npmjs.org/package/@axenda/zatca)
 [](https://codecov.io/gh/axenda/zatca) [](https://raw.githubusercontent.com/user/project/master/LICENSE)
一个非官方的软件包,帮助开发人员执行方便的ZATCA(Fatoora)QR代码,电子发票在其中需要该代码 沙特阿拉伯.
> 在前端和后端的节点项目中都可以使用.
> ✅已验证为自2021年11月18日起与ZATCA的SDK相同出品.
## 安装
要启动, 请安装软件包 :
```bash
npm i --save @axenda/zatca
```
## 使用量
### 内容提要
简单,你只需要生成一个QR代码就是:
```typescript
import { Invoice } from '@axenda/zatca';
const invoice = new Invoice({
sellerName: 'Axenda',
vatRegistrationNumber: '1234567891',
invoiceTimestamp: '2021-12-04T00:00:00Z',
invoiceTotal: '100.00',
invoiceVatTotal: '15.00',
});
const imageData = await invoice.render();
// Read the following sections for more details.
```
### 导入
首先,进口发票类或Tag类,代表发票QR代码:
```typescript
import { Invoice } from '@axenda/zatca';
// or
import { Tag } from '@axenda/zatca';
```
### 代表发票QR代码
第二,创建发票实例或一系列 Tag 类:
```typescript
const invoice = new Invoice({
sellerName: 'Axenda',
vatRegistrationNumber: '1234567891',
invoiceTimestamp: '2021-12-04T00:00:00Z',
invoiceTotal: '100.00',
invoiceVatTotal: '15.00',
});
// or
const tags: Tag[] = [
new Tag(1, 'Axenda'),
new Tag(2, '1234567891'),
new Tag(3, '2021-12-04T00:00:00Z'),
new Tag(4, '100.00'),
new Tag(5, '15.00'),
];
```
### 生成 TLV
现在可以从发票或标签阵列中生成 TLV 字符串 :
```typescript
invoice.toTlv();
// or using tags array
import { toTlv } from '@axenda/zatca';
toTlv(tags)
```
### 生成 Base64
您从发票或标签阵列生成 Base64 字符串 :
```typescript
invoice.toBase64();
// or using tags array
import { tagsToBase64 } from '@axenda/zatca';
tagsToBase64(tags);
```
### 渲染QR 代码
您可以从 Base64 字符串中生成图像数据( png)并在浏览器中渲染:
```typescript
await invoice.render();
// or using tags array
import { renderTags } from '@axenda/zatca';
await renderTags(tags);
```
### 使用 QR 代码图像数据
使用图像数据在浏览器中显示 QR 代码 :
```html
![]()
```
## 测试
要运行测试套件,首先安装依赖关系,然后运行 `npm test`数字 :
```bash
npm install
npm test
```
## 一揽子路线图
- [x] 支持 ZATCA 发票 QR 编码阶段 1
- [ ] 审查软件包 API 一致性
- [ ] 支持 ZATCA 发票 QR 编码阶段 2
## 捐款
欢迎 [捐款](https://github.com/axenda/zatca/graphs/contributors) 任何种类的人。 请拿一个 时间来回顾 [提交文件的准则](https://npmcn.com/package/%40axenda/zatca/CONTRIBUTING.md)。 。 。 .
- [错误报告](https://github.com/axenda/zatca/issues/new)
- [特性请求](https://npmcn.com/package/%40axenda/zatca/CONTRIBUTING.md#-feature-requests)
- [调取请求](https://npmcn.com/package/%40axenda/zatca/CONTRIBUTING.md#-pull-requests)
## 许可证
麻省理工学院许可证(MIT). 请看 [许可证文件](https://npmcn.com/package/%40axenda/zatca/LICENSE) 更多信息.
## 常见问题
### 如何安装 @axenda/zatca？
在项目目录运行 npm install @axenda/zatca，或使用 pnpm add / yarn add / bun add。
### @axenda/zatca 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @axenda/zatca 支持 ESM 还是 CommonJS？
以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。
### @axenda/zatca 可以商用吗？
@axenda/zatca 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @axenda/zatca 的下载量有多少？
根据 npm 官方下载统计，@axenda/zatca 在 2026/10/08 – 2026/11/06 这 30 天内被下载 15,202 次，日均约 507 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @axenda/zatca 还在维护吗？
最新版本 1\.0\.4 发布于 2021/11/20（4 年前）；至今共发布 5 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/11/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。