Aspose.BarCode FOSS
Python
故障排除 Aspose.BarCode FOSS for Python

故障排除 Aspose.BarCode FOSS for Python

本指南涵盖了使用 Aspose.BarCode FOSS 为 Python 生成条形码时最常见的错误和问题。每个章节描述错误、其原因以及如何解决。

常见错误

InvalidInputError

InvalidInputError 在传递给编码器的数据不符合该符号的字符集或长度要求时被抛出。

****典型原因：:

  • 向仅限数字的符号传递字母字符（EAN-13、EAN-8、UPC-A、UPC-E）
  • 提供的字符串长度不符合符号的固定长度要求（例如，EAN-13 需要恰好 12 或 13 位数字）
  • 包含超出符号集支持范围的字符（例如 Code 39 基础模式仅支持大写字母、数字和少量特殊字符）

修复： 在调用之前验证您的输入数据 BarcodeService.generate(). 检查符号配置文件的 capabilities and known_limitations 属性用于字符集和长度约束。

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# EAN-13 requires exactly 12 or 13 digits
data = "590123412345"  # 12 digits — valid
barcode = service.generate("ean13", data)

EncodingError

当编码器在输入验证通过后遇到内部错误时会抛出 EncodingError。这比 InvalidInputError 少见。

****常见原因::

  • 在初始验证通过但在段编码期间失败的数据（例如 QR Code 数据超出所选错误纠正级别的容量）
  • 冲突的编码选项（例如请求 Code128EncodeMode.CODE_A 时数据包含小写字符）

修复： 审查传递给的编码选项 generate(). 对于 Code 128，使用 Code128EncodeMode.AUTO 让编码器选择最佳子集。对于 QR Code，尝试更低的 QrErrorCorrectionLevel 或缩短数据长度。

from aspose_barcode_foss import BarcodeService, Code128Options, Code128EncodeMode

service = BarcodeService()
options = Code128Options(encode_mode=Code128EncodeMode.AUTO)
barcode = service.generate("code128", "Hello123", encode=options)

SymbologyNotFoundError

SymbologyNotFoundError 在将传递给 BarcodeService.generate() 的符号名称未在 SymbologyRegistry 中注册时被抛出。

****典型原因::

  • 拼写错误的符号名称（例如 "code_128" 而不是 "code128"）
  • 使用库不支持的符号（该库仅支持 Code 128、Code 39、EAN-13、EAN-8、QR Code、UPC-A 和 UPC-E）

修复： 使用七个受支持的符号标识符之一： "code128", "code39", "ean13", "ean8", "qrcode", "upca", "upce". 名称不区分大小写，但必须匹配已注册的标识符。

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Correct symbology names
barcode = service.generate("code128", "ABC-123")
barcode = service.generate("qrcode", "https://example.com")

RenderingError

RenderingError 在渲染器未能从编码符号生成输出时被抛出。

****常见原因：:

  • 无效的 RenderOptions 值（例如负的 scale 或 module_width）
  • 尝试使用 PdfRenderer（在当前版本中，PDF 渲染会引发 NotImplementedError）

修复： 使用 SvgRenderer or PngRenderer 而不是 PdfRenderer. 验证 RenderOptions 属性具有有效的正值。

from aspose_barcode_foss import BarcodeService, RenderOptions
from aspose_barcode_foss.rendering import SvgRenderer

service = BarcodeService()
barcode = service.generate("ean13", "590123412345")

options = RenderOptions(scale=2.0, dpi=300)
result = barcode.render(SvgRenderer(), options)

UnsupportedCapabilityError 和 UnsupportedFeatureError

当符号系统不支持请求的功能时会抛出 UnsupportedCapabilityError（例如符号系统缺乏 GS1 支持时的 GS1 模式）。对于库中未实现的功能会抛出 UnsupportedFeatureError。

修复： 检查符号配置文件的 capabilities 属性以确认哪些功能可用。避免为不支持的符号请求 GS1 模式。

环境问题

Python 版本

Aspose.BarCode FOSS 需要 Python 3.12 或更高版本。如果出现 SyntaxError 或导入失败，请检查您的 Python 版本：

python --version

安装问题

从源码构建该包。

该库是纯 Python，没有本机依赖。如果安装成功但导入失败，请检查是否有名为 aspose_barcode_foss.py 的本地文件遮蔽了该包。

导入错误

正确的导入方式是：

import aspose_barcode_foss

或导入特定类：

from aspose_barcode_foss import BarcodeService, RenderOptions

常见问题

为什么我的 EAN-13 条形码显示的数字与我输入的不同？

EAN-13 自动计算校验位。如果你提供 12 位数字，会在后面追加第 13 位。如果你提供 13 位数字，则会将最后一位作为校验位进行验证。使用 Ean13Options allow_check_digit_input 属性来控制此行为。

为什么 PDF 输出会触发 NotImplementedError？

PdfRenderer.render() 和 Barcode.to_pdf() 尚未实现。请改用 Barcode.to_svg() 或 Barcode.to_png()，或直接使用 SvgRenderer 或 PngRenderer 渲染。

如何调试可用的符号名称？

使用 SymbologyRegistry.get_definition() 检查符号是否已注册。如果抛出 SymbologyNotFoundError，则该符号不可用。支持的七种符号包括：Code 128、Code 39、EAN-13、EAN-8、QR Code、UPC-A 和 UPC-E。

另请参阅

 中文