Aspose.BarCode FOSS
Python
开发者指南
条形码渲染

条形码渲染

条形码渲染

Aspose.BarCode 为 Python 提供的 FOSS 将编码与渲染分离。条形码被编码为 EncodedSymbol 后，Renderer 实现会将模块矩阵转换为可视化输出。该库包含 SvgRenderer 和 PngRenderer。

RenderOptions

RenderOptions 控制所有渲染器的可视化输出。将其传递给任意 Barcode 对象上的 to_svg() 或 to_png()：

import aspose_barcode_foss as barcode
from aspose_barcode_foss import RenderOptions

bc = barcode.code128("Hello World")
svg = bc.to_svg(options=RenderOptions(
    scale=2.0,
    foreground_color="#003366",
    quiet_zone=10.0,
    show_text=True,
))
属性类型描述
scalefloat整个条码的统一缩放倍数
dpiintPNG 输出的分辨率（对 SVG 没有影响）
module_widthfloat用户单位中一个条码模块的宽度
module_heightfloat用户单位中一个条码模块的高度
quiet_zonefloat条码周围的空白填充
foreground_colorstr用于条形和模块的十六进制颜色（例如，"#000000"）
background_colorstr背景的十六进制颜色
transparent_backgroundboolPNG 输出的透明背景
show_textbool在条形码下方显示可读文本
font_familystr可读文本的字体
font_sizefloat人类可读文本的字体大小

ResolvedRenderOptions

ResolvedRenderOptions 是由 OptionsResolver.resolve() 生成的完整合并配置。它将用户提供的 RenderOptions 与 SymbologyProfile 默认值合并。所有属性都有具体数值（没有 None）。

Barcode.default_render_options 属性保存生成时传入的 RenderOptions（如果未提供则为 None）。

SVG 输出

SvgRenderer 生成 SVG 输出。在 Barcode 对象上调用 to_svg()：

bc = barcode.ean13("590123412345")
svg_string = bc.to_svg()

# With custom options
svg_custom = bc.to_svg(options=RenderOptions(
    scale=3.0,
    foreground_color="#1a1a1a",
    show_text=True,
    font_family="Helvetica",
    font_size=12.0,
))

with open("ean13.svg", "w") as f:
    f.write(svg_custom)

to_svg() 返回一个包含完整 SVG 文档的 str。

PNG 输出

PngRenderer 生成 PNG 输出。在 Barcode 对象上调用 to_png()：

bc = barcode.qr("https://example.com")
png_bytes = bc.to_png()

# With custom options
png_custom = bc.to_png(options=RenderOptions(
    scale=4.0,
    dpi=300,
    transparent_background=True,
))

with open("qr.png", "wb") as f:
    f.write(png_custom)

to_png() 返回 bytes，其中包含 PNG 图像数据。

渲染器抽象

Renderer 抽象基类定义了所有渲染器的接口：

class Renderer(ABC):
    def render(self, symbol, layout, options) -> RenderedArtifact: ...

SvgRenderer 和 PngRenderer 都实现了此接口。您可以调用 Barcode.render(renderer, options) 直接使用特定的渲染器：

from aspose_barcode_foss import SvgRenderer, RenderOptions

bc = barcode.code128("DATA")
artifact = bc.render(SvgRenderer(), RenderOptions(scale=2.0))
print(artifact.media_type)  # "image/svg+xml"
print(type(artifact.data))  # <class 'str'>

RenderedArtifact

由 Renderer.render() 返回的 RenderedArtifact 包含：

属性类型描述
data`strbytes`
media_typestrMIME 类型（"image/svg+xml" 或 "image/png"）
backendstr渲染器标识符

文本布局

每种符号都有一个 TextLayoutPolicy，用于决定可读文本在条码下方的放置方式。create_layout(symbol, options) 方法返回一个 TextLayout，其中包含带有位置信息和文本数据的 TextSegment 对象。

QR Code 使用 QrTextLayoutPolicy，它提供了一个无操作布局（QR 代码不显示可读文本）。

提示与最佳实践

  • 使用 scale 实现统一尺寸，使用 module_width/module_height 实现精确尺寸控制——不要同时使用两者。
  • 将 dpi=300 设置为打印质量的 PNG 输出；默认是屏幕分辨率。
  • 使用 transparent_background=True 来生成将在彩色背景上叠加的 PNG 条码。
  • foreground_color 和 background_color 接受标准十六进制颜色字符串（"#RRGGBB"）。
  • SVG 输出是分辨率无关的 — 建议在网页和 PDF 嵌入时优先使用 SVG。

常见问题

问题原因修复
PNG 显示得太小默认缩放比例为 1.0增加 scale 或设置 dpi
文本不可见show_text 默认值为 False设置 show_text=True
QR code 没有文本QR 符号系统不支持人类可读的文本预期行为 — QR 使用无操作文本布局
颜色未应用属性名称拼写错误使用准确的属性名称：foreground_color，background_color

另请参阅

 中文