certflow.handlers.template_handler module

模板配置管理器

管理合格证打印模板的配置，包括内置模板（全中文/中英文/全英文/俄英文） 和用户自定义模板。提供 templates.xlsx 历史模板数据的读写功能。

从 certificate_printer v2.0 移植，整合到 CertFlow 架构中。

分层说明:

本模块为纯数据处理层（handlers），不依赖 PySide6，可在无 Qt （headless / 无 X11）环境导入。模板切换通知采用普通回调机制 （on_template_changed），由上层 View 自行桥接到 Qt 信号。

class certflow.handlers.template_handler.FieldMapping(source_field, target_cell='', display_name='', show_label=False, x=0, y=0, align='left', font_size=8, is_required=False, default_value='', format_string='')

基类：object

字段映射 — 数据源字段到打印目标位置的映射

参数:

• source_field (str)

• target_cell (str)

• display_name (str)

• show_label (bool)

• x (float)

• y (float)

• align (str)

• font_size (int)

• is_required (bool)

• default_value (str)

• format_string (str)

source_field: str

target_cell: str = ''

display_name: str = ''

show_label: bool = False

x: float = 0

y: float = 0

align: str = 'left'

font_size: int = 8

is_required: bool = False

default_value: str = ''

format_string: str = ''

class certflow.handlers.template_handler.TemplateConfig(name, display_name, template_type='全中文', page_width=60, page_height=100, background_image='', fields=<factory>)

基类：object

合格证打印模板配置

参数:

• name (str)

• display_name (str)

• template_type (str)

• page_width (float)

• page_height (float)

• background_image (str)

• fields (list[FieldMapping])

name: str

display_name: str

template_type: str = '全中文'

page_width: float = 60

page_height: float = 100

background_image: str = ''

fields: list[FieldMapping]

to_dict()

将模板配置序列化为字典

参数:

无

返回:

模板配置字典，包含 name/display_name/fields 等键

返回类型:

dict[str, Any]

classmethod from_dict(data)

从字典反序列化为 TemplateConfig 实例

参数:

data (dict[str, Any]) -- 模板配置字典（含 name/display_name/fields 等键）

返回:

重建的模板配置对象

返回类型:

TemplateConfig

class certflow.handlers.template_handler.TemplateManager(templates_xlsx_path='')

基类：object

模板管理器

管理合格证打印模板的配置，支持内置模板和用户自定义模板。 提供 templates.xlsx 历史模板数据的查询和回填功能。

通知机制:

模板切换时回调 on_template_changed 注册的监听器（携带模板名称）。 本类不依赖 Qt；如需 Qt 信号，由上层 View 注册回调后自行转发。

参数:

templates_xlsx_path (str)

templates: dict[str, TemplateConfig]

current_template: TemplateConfig | None

on_template_changed(callback)

注册模板切换监听回调

参数:

callback (Callable[[str], None]) -- 模板切换时被调用，入参为模板内部名称

返回:

None

返回类型:

None

add_template(template)

添加模板

参数:

template (TemplateConfig) -- 要添加的模板配置对象

返回:

None

返回类型:

None

remove_template(template_name)

删除模板

参数:

template_name (str) -- 要删除的模板内部名称

返回:

None

返回类型:

None

get_template(name)

获取模板

参数:

name (str) -- 模板内部名称

返回:

命中的模板配置，未找到时返回 None

返回类型:

TemplateConfig | None

set_current_template(name)

设置当前模板

参数:

name (str) -- 模板内部名称

返回:

设置成功后回调已注册的模板切换监听器

返回类型:

None

get_template_list()

获取模板名称列表（用户可见）

参数:

无

返回:

各模板的 display_name 列表

返回类型:

list[str]

get_template_names()

获取模板内部名称列表

参数:

无

返回:

各模板的内部 name 列表

返回类型:

list[str]

get_template_by_display_name(display_name)

根据显示名称获取模板

参数:

display_name (str) -- 模板用户可见名称

返回:

命中的模板配置，未找到时返回 None

返回类型:

TemplateConfig | None

export_template(template_name, file_path)

导出模板配置为 JSON

参数:

• template_name (str) -- 要导出的模板内部名称

• file_path (str) -- 目标 JSON 文件路径

返回:

导出成功返回 True，模板不存在时返回 False

返回类型:

bool

import_template(file_path)

从 JSON 导入模板配置

参数:

file_path (str) -- 源 JSON 文件路径

返回:

导入成功的模板配置，异常时为 None

返回类型:

TemplateConfig | None

load_from_xlsx(xlsx_path=None)

从 templates.xlsx 的「数据库」工作表加载历史模板数据

参数:

xlsx_path (str | None) -- xlsx 文件路径，默认使用初始化时指定的路径

返回:

DataFrame 或 None

返回类型:

DataFrame | None

query_by_model(product_model, xlsx_path=None)

按产品型号从 templates.xlsx 查询历史模板

在「数据库」工作表的第4列（产品型号）进行部分匹配。

参数:

• product_model (str) -- 产品型号（支持部分匹配）

• xlsx_path (str | None) -- xlsx 文件路径

返回:

匹配的模板列表，每条包含完整打印参数

返回类型:

list[dict[str, Any]]

writeback_to_xlsx(certificate_data, xlsx_path=None)

打印完成后回填到 templates.xlsx「数据库」表

如果同型号+同编号已有记录则更新，否则新增行。

参数:

• certificate_data (dict[str, Any]) -- 合格证数据字典

• xlsx_path (str | None) -- xlsx 文件路径

返回:

是否回填成功

返回类型:

bool