certflow.widgets package

Submodules

• certflow.widgets.button_row module
  • ActionToolbar
    • ActionToolbar.add_button()
    • ActionToolbar.add_widget()
    • ActionToolbar.add_stretch()
    • ActionToolbar.staticMetaObject
• certflow.widgets.confirm_dialog module
  • ConfirmDialog
    • ConfirmDialog.danger()
• certflow.widgets.data_table module
  • DataTable
    • DataTable.set_columns()
    • DataTable.staticMetaObject
• certflow.widgets.dialog_button_bar module
  • DialogButtonBar
    • DialogButtonBar.accepted
    • DialogButtonBar.rejected
    • DialogButtonBar.applied
    • DialogButtonBar.set_confirm_enabled()
    • DialogButtonBar.staticMetaObject
• certflow.widgets.enhanced_table module
  • EnhancedTable
    • EnhancedTable.column_config_changed
    • EnhancedTable.sort_requested
    • EnhancedTable.keyPressEvent()
    • EnhancedTable.set_header_field()
    • EnhancedTable.header_field()
    • EnhancedTable.update_sort_indicator()
    • EnhancedTable.save_state()
    • EnhancedTable.restore_state()
    • EnhancedTable.staticMetaObject
• certflow.widgets.filter_bar module
  • FilterBar
    • FilterBar.conditions_changed
    • FilterBar.set_columns()
    • FilterBar.add_row()
    • FilterBar.remove_row()
    • FilterBar.clear_rows()
    • FilterBar.ensure_at_least_one_row()
    • FilterBar.rows_data()
    • FilterBar.rows()
    • FilterBar.get_conditions()
    • FilterBar.collect_conditions()
    • FilterBar.find_row_by_field()
    • FilterBar.set_quick_search_items()
    • FilterBar.set_quick_search_placeholder()
    • FilterBar.set_presets()
    • FilterBar.staticMetaObject
    • FilterBar.active_preset()
• certflow.widgets.filter_row module
  • FilterRowWidget
    • FilterRowWidget.value_changed
    • FilterRowWidget.structure_changed
    • FilterRowWidget.remove_requested
    • FilterRowWidget.set_columns()
    • FilterRowWidget.get_condition()
    • FilterRowWidget.to_condition_dict()
    • FilterRowWidget.row_data()
    • FilterRowWidget.staticMetaObject
• certflow.widgets.flow_layout module
  • FlowLayout
    • FlowLayout.addItem()
    • FlowLayout.count()
    • FlowLayout.itemAt()
    • FlowLayout.takeAt()
    • FlowLayout.expandingDirections()
    • FlowLayout.hasHeightForWidth()
    • FlowLayout.heightForWidth()
    • FlowLayout.setGeometry()
    • FlowLayout.sizeHint()
    • FlowLayout.minimumSize()
    • FlowLayout.staticMetaObject
• certflow.widgets.quick_search module
  • QuickSearch
    • QuickSearch.typing
    • QuickSearch.activated
    • QuickSearch.set_items()
    • QuickSearch.staticMetaObject
• certflow.widgets.quick_search_preset module
  • build_quick_search_plan()
  • split_quick_search_text()
  • QuickSearchPresetMixin
    • QuickSearchPresetMixin.setup_quick_search_preset()
    • QuickSearchPresetMixin.get_quick_search_mode()
    • QuickSearchPresetMixin.qsp_on_mode_changed()
    • QuickSearchPresetMixin.qsp_on_preset_changed()
    • QuickSearchPresetMixin.qsp_get_quick_search_items()
    • QuickSearchPresetMixin.qsp_get_field_label()
    • QuickSearchPresetMixin.qsp_on_typing()
    • QuickSearchPresetMixin.qsp_on_quick_search()
• certflow.widgets.section_card module
  • SectionCard
    • SectionCard.content
    • SectionCard.add_field()
    • SectionCard.add_widget()
    • SectionCard.add_layout()
    • SectionCard.staticMetaObject

Module contents

自定义控件包（widgets）。

提供增强表格等 PySide6 自定义窗口部件，以及 UI 重构的共享控件， 避免各窗体重复造轮子：

• EnhancedTable：服务端排序 / 列显隐 / 复制 / 排序指示器。

• SectionCard：统一「Section 卡片」容器（标题 + 内容布局，字段列不拉伸）。

• ActionToolbar：按钮簇工具栏（按内容定宽，不 addStretch 均分）。面向**视图顶部工具条** （「新增/编辑/删除/刷新」之类），与对话框底部按钮栏职责分离。

• DialogButtonBar：确认 / 取消 / 应用 按钮栏。面向**对话框底部**，发出 accepted / rejected / applied 信号，供 BaseDialog 直接接线。

• ConfirmDialog：统一的危险操作二次确认（danger）。供 BaseDialog.confirm_danger 及任意视图复用，集中危险样式与文案，替代手写 QMessageBox.question。

• DataTable：表格初始化封装（列元数据 → 表头 + 选择/编辑行为）。

• FlowLayout：自动换行布局（根治「占整行」）。

• QuickSearch：可编辑模糊匹配快查框（控件及其预设逻辑 mixin QuickSearchPresetMixin 同处本包）。

• FilterBar：筛选条件容器（N 个 FilterRowWidget + 添加按钮 + 可选快查框），汇总为统一条件契约。

• FilterRowWidget：单条筛选行控件（字段/操作符/值栈），数据源无关、可复用。

class certflow.widgets.EnhancedTable(parent=None)

基类：QTableWidget

增强表格控件

功能: - 点击列头触发服务端排序（排序全量数据，非仅当前页） - 右键菜单隐藏/显示列 - Ctrl+C 复制选中单元格 - Ctrl+A 全选 - 交替行颜色 - 排序指示器显示

参数:

parent (QWidget | None)

column_config_changed

sort_requested

keyPressEvent(event)

处理键盘快捷键事件

支持 Ctrl+C 复制选中单元格、Ctrl+A 全选。

参数:

event (QKeyEvent) -- 键盘事件对象

返回类型:

None

set_header_field(column, field)

设置列对应的数据库字段名（用于服务端排序）

参数:

• column (int) -- 列索引

• field (str) -- 对应的数据库字段名

返回类型:

None

header_field(column)

读取列对应的数据库字段名（与 set_header_field 对应）。

参数:

column (int)

返回类型:

str

update_sort_indicator(field, desc)

更新排序指示器（列头箭头）

参数:

• field (str) -- 数据库字段名

• desc (bool) -- True=降序, False=升序

返回类型:

None

save_state()

保存列状态（宽度和可见性）

返回:

包含 widths 和 visible 两个键的状态字典

返回类型:

dict

restore_state(state)

恢复列状态

参数:

state (dict) -- save_state() 返回的状态字典，为空则跳过

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("EnhancedTable" inherits "QTableWidget": Methods:   #110 type=Signal, signature=column_config_changed()   #111 type=Signal, signature=sort_requested(QString,bool), parameters=QString, bool )

class certflow.widgets.SectionCard(title='', icon='', parent=None)

基类：QGroupBox

带标题的内容卡片。

用法:

card = SectionCard("基本配置", icon="⚙️")
card.add_field("工作表:", self.sheet_combo)
card.content.addWidget(self.some_widget)

参数:

• title (str)

• icon (str)

• parent (QWidget | None)

property content: QVBoxLayout

返回内容主布局，调用方往里加控件/子布局。

add_field(label, widget)

追加一行「标签 + 控件」，字段列按 sizeHint 定宽（不拉伸、不占整行）。

参数:

• label (str)

• widget (QWidget)

返回类型:

QWidget

add_widget(widget)

参数:

widget (QWidget)

返回类型:

None

add_layout(layout)

参数:

layout (QVBoxLayout | QFormLayout)

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("SectionCard" inherits "QGroupBox": )

class certflow.widgets.ActionToolbar(parent=None, align='left')

基类：QWidget

一排动作按钮，按内容定宽。

用法:

bar = ActionToolbar()
bar.add_button("➕ 新增", self.on_add)
bar.add_button("🗑️ 删除", self.on_delete, danger=True)
bar.add_stretch()
bar.add_button("🔄 刷新", self.refresh)

参数:

• parent (QWidget | None)

• align (str)

add_button(label, slot=None, tooltip=None, primary=False, danger=False)

追加一个按钮；slot 不为空则连接点击事件。

参数:

• label (str)

• slot (Callable[[], None] | None)

• tooltip (str | None)

• primary (bool)

• danger (bool)

返回类型:

QPushButton

add_widget(widget)

参数:

widget (QWidget)

返回类型:

None

add_stretch()

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("ActionToolbar" inherits "QWidget": )

class certflow.widgets.DialogButtonBar(parent=None, show_apply=False, confirm_text='确认', cancel_text='取消')

基类：QWidget

确认 / 取消 / 应用 按钮栏。

参数:

• parent (QWidget | None)

• show_apply (bool)

• confirm_text (str)

• cancel_text (str)

accepted

rejected

applied

set_confirm_enabled(enabled)

参数:

enabled (bool)

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("DialogButtonBar" inherits "QWidget": Methods:   #33 type=Signal, signature=accepted()   #34 type=Signal, signature=rejected()   #35 type=Signal, signature=applied() )

class certflow.widgets.ConfirmDialog

基类：object

危险操作确认助手（静态方法，不持有状态）。

classmethod danger(parent, title, message, preview=None, ok_text='删除', ok_default=False)

弹出警告级确认框，返回用户是否确认。

参数:

• preview (str | None) -- 可选详细信息（如待删除记录预览），折叠在「显示详情」里。

• ok_text (str) -- 确认按钮文案（默认「删除」）。

• ok_default (bool) -- 确认按钮是否设为默认焦点（危险操作默认 False，聚焦取消）。

• parent (QWidget | None)

• title (str)

• message (str)

返回类型:

bool

class certflow.widgets.DataTable(columns=None, parent=None)

基类：QTableWidget

开箱即用的只读单选表格。

用法:

table = DataTable(["ID", "名称", "状态"])
# 或 table = DataTable([("ID", "id"), ("名称", "name")])

参数:

columns (list[str] | list[tuple[str, str]] | None)

set_columns(columns)

根据列元数据设置表头与默认交互行为。

参数:

columns (list[str] | list[tuple[str, str]])

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("DataTable" inherits "QTableWidget": )

class certflow.widgets.FlowLayout(parent=None, margin=0, spacing=-1)

基类：QLayout

流布局：水平排布子项，超出宽度自动换行。

参数:

• parent (QWidget | None)

• margin (int)

• spacing (int)

addItem(item)

参数:

item (QLayout.Item)

返回类型:

None

count()

返回类型:

int

itemAt(index)

参数:

index (int)

返回类型:

QLayout.Item | None

takeAt(index)

参数:

index (int)

返回类型:

QLayout.Item | None

expandingDirections()

返回类型:

Orientation

hasHeightForWidth()

返回类型:

bool

heightForWidth(width)

参数:

width (int)

返回类型:

int

setGeometry(rect)

参数:

rect (QRect)

返回类型:

None

sizeHint()

返回类型:

QSize

minimumSize()

返回类型:

QSize

staticMetaObject = PySide6.QtCore.QMetaObject("FlowLayout" inherits "QLayout": )

class certflow.widgets.QuickSearch(parent=None, *, placeholder='', min_width=260, filter_mode=<MatchFlag.MatchContains: 1>)

基类：QComboBox

可编辑模糊匹配快查框。

参数:

• placeholder (str)

• min_width (int)

typing

activated

set_items(items)

填充候选项（editable + completer 模糊匹配），并清空当前输入。

参数:

items (list[str])

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("QuickSearch" inherits "QComboBox": Methods:   #46 type=Signal, signature=typing(QString), parameters=QString   #47 type=Signal, signature=activated(QString), parameters=QString )

class certflow.widgets.FilterBar(parent=None, *, columns=None, field_op_map=None, field_choices_map=None, operators=None, is_dark_theme_fn=None, load_combo_values_fn=None, open_date_picker_fn=None, date_button_style_fn=None, grid_cols=2, show_quick_search=False, quick_search_placeholder='', quick_search_callback=None, quick_search_typing_callback=None, show_preset_selector=False, presets=None, preset_changed_callback=None)

基类：QWidget

筛选条件容器。

参数:

• parent (QWidget | None)

• columns (list[dict] | None)

• field_op_map (dict | None)

• field_choices_map (dict | None)

• operators (dict | None)

• grid_cols (int)

• show_quick_search (bool)

• quick_search_placeholder (str)

• show_preset_selector (bool)

• presets (list | None)

conditions_changed

set_columns(columns)

更新可用字段列表（视图切换时调用），并刷新所有行的字段下拉。

参数:

columns (list[dict])

返回类型:

None

add_row(field_name=None, operator=None, value=None)

添加一行筛选条件，返回新建的 FilterRowWidget。

返回类型:

FilterRowWidget

remove_row(widget)

按控件引用删除一行（供宿主视图快筛逻辑调用）。

参数:

widget (QWidget)

返回类型:

None

clear_rows()

清空所有筛选行。

返回类型:

None

ensure_at_least_one_row()

保证至少有一个空筛选行。

返回类型:

None

rows_data()

返回所有行的 row_data 字典列表（迁移期兼容）。

返回类型:

list[dict]

rows()

返回类型:

list[FilterRowWidget]

get_conditions()

汇总为统一条件契约 {field: {value, operator}}。

返回类型:

dict

collect_conditions()

汇总为列表形式 ``[{field, operator, value}, ...]``（保存 / 加载用）。

返回类型:

list[dict]

find_row_by_field(field_name)

查找指定字段的筛选行。

参数:

field_name (str)

返回类型:

FilterRowWidget | None

set_quick_search_items(items)

填充快查框候选项（editable + completer 模糊匹配）。

参数:

items (list[str])

返回类型:

None

set_quick_search_placeholder(text)

设置快查框占位提示（随 active preset 变化）。

参数:

text (str)

返回类型:

None

set_presets(presets)

动态更新预设列表（视图切换时）。

参数:

presets (list)

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("FilterBar" inherits "QWidget": Methods:   #33 type=Signal, signature=conditions_changed() )

active_preset()

返回当前选中的预设 dict（无预设选择器时返回 None）。

返回类型:

dict | None

class certflow.widgets.FilterRowWidget(parent=None, *, columns, field_op_map, operators, field_choices_map=None, is_dark_theme_fn=None, load_combo_values_fn=None, open_date_picker_fn=None, date_button_style_fn=None, field_name=None, operator=None, value=None)

基类：QWidget

单条筛选条件行。

信号：

value_changed：值输入框变化（应触发防抖搜索）。 structure_changed：字段 / 操作符变化（应触发快筛脱离，不触发搜索）。 remove_requested：请求删除本行。

参数:

• parent (QWidget | None)

• columns (list[dict])

• field_op_map (dict)

• operators (dict)

• field_choices_map (dict | None)

• field_name (str | None)

• operator (str | None)

value_changed

structure_changed

remove_requested

set_columns(columns)

更新可用字段列表（视图切换时由 FilterBar 调用），重建字段下拉。

参数:

columns (list[dict])

返回类型:

None

get_condition()

返回标准化条件 {field: {value, operator}}，无效则返回 None。

注意：区间（between）操作符的值存于 value_edit_min/max，单值框为空， 因此 not value 的跳过判定仅适用于非区间、非无值操作符。

返回类型:

dict | None

to_condition_dict()

返回列表形式 ``{field, operator, value}``（供保存 / 加载使用）。

返回类型:

dict | None

row_data()

返回与原 query_view 行字典同键的**持久**字典，便于迁移期最小改动接入。

返回的字典在控件生命周期内保持稳定引用，迁移期 query_view 的快筛/保存逻辑 可直接对其中的 _is_manual / _quick_filter_button 等标记做增删改并持久化。

返回类型:

dict

staticMetaObject = PySide6.QtCore.QMetaObject("FilterRowWidget" inherits "QWidget": Methods:   #33 type=Signal, signature=value_changed()   #34 type=Signal, signature=structure_changed()   #35 type=Signal, signature=remove_requested() )