certflow.handlers.excel_styler module

Excel 样式处理器模块

提供单元格颜色、字体、批注等格式信息的读取功能。

class certflow.handlers.excel_styler.ExcelStyler

基类：object

Excel 样式处理器

负责读取 Excel 单元格的格式信息： - 背景色 - 字体色 - 批注内容 - 其他样式属性

classmethod get_status_from_color(color, color_type='bg')

根据颜色获取对应的业务状态（配置驱动）

参数:

• color (str) -- 原始颜色值（如 "FF0000"、"00B050" 或 "THEME_1"），可为空

• color_type (str) -- 颜色类型，"font" 表示字体色，"bg" 表示背景色

返回:

对应的业务状态文本（如 "已开票"、"已发货"），无匹配时返回 None

返回类型:

str | None

static open_workbook(file_path, data_only=True)

打开工作簿的上下文管理器

使用上下文管理器自动管理Excel工作簿的打开和关闭， 确保资源正确释放。

参数:

• file_path (Path) -- Excel文件路径

• data_only (bool) -- 是否只读取数据值(不读取公式)，默认为True

生成器:

Workbook -- openpyxl工作簿对象

返回类型:

Iterator[Workbook]

示例

>>> with ExcelStyler.open_workbook(Path("data.xlsx")) as wb:
...     ws = wb.active
...     cell = ws["A1"]
...     print(cell.value)

static get_cell_color(cell, color_type='bg')

获取单元格颜色

支持获取背景色和字体色，返回标准化的颜色值。

参数:

• cell (Cell)

• color_type (str)

返回类型:

str | None

static get_cell_comment(cell)

获取单元格批注内容

参数:

cell (Cell) -- openpyxl单元格对象

返回:

批注文本内容，没有批注时返回None

返回类型:

Optional[str]

示例

>>> with ExcelStyler.open_workbook(Path("data.xlsx")) as wb:
...     ws = wb.active
...     comment = ExcelStyler.get_cell_comment(ws["A1"])
...     if comment:
...         print(f"批注内容: {comment}")

static get_cell_style_info(cell)

获取单元格完整样式信息

一次性获取单元格的值、背景色、字体色、状态、批注和字体属性。

参数:

cell (Cell) -- openpyxl单元格对象

返回:

包含以下键的字典:

• value: 单元格值

• bg_color: 背景色

• font_color: 字体色

• status: 根据颜色推断的业务状态

• comment: 批注内容

• font_name: 字体名称

• font_size: 字体大小

• bold: 是否粗体

• italic: 是否斜体

返回类型:

Dict[str, Any]

示例

>>> with ExcelStyler.open_workbook(Path("data.xlsx")) as wb:
...     ws = wb.active
...     info = ExcelStyler.get_cell_style_info(ws["A1"])
...     print(f"值: {info['value']}, 状态: {info['status']}")

static read_with_styles(file_path, sheet_name=0, include_styles=True, include_comments=True)

读取 Excel 并返回数据和样式信息

同时读取单元格的值和样式信息，返回多个DataFrame。

参数:

• file_path (Path) -- Excel文件路径

• sheet_name (str | int) -- 工作表名称或索引，默认为0(第一个工作表)

• include_styles (bool) -- 是否包含样式信息(背景色、字体色)，默认为True

• include_comments (bool) -- 是否包含批注信息，默认为True

返回:

包含5个元素的元组:

• df_data: 数据值DataFrame

• bg_colors: 背景色DataFrame(可选)

• font_colors: 字体色DataFrame(可选)

• comments: 批注DataFrame(可选)

• statuses: 状态DataFrame(可选)

返回类型:

Tuple

示例

>>> data, bg, font, comments, status = ExcelStyler.read_with_styles(
...     Path("data.xlsx"),
...     sheet_name="Sheet1"
... )
>>> print(f"数据形状: {data.shape}")
>>> print(f"状态统计: {status.iloc[0, 0]}")

static get_comments_summary(file_path)

获取批注汇总表

扫描整个工作簿，返回所有批注的结构化摘要。

参数:

file_path (Path) -- Excel文件路径

返回:

包含以下列的DataFrame:

• 工作表: 批注所在工作表名称

• 单元格: 批注所在单元格坐标(如"A1")

• 批注内容: 批注的文本内容

返回类型:

pd.DataFrame

示例

>>> summary = ExcelStyler.get_comments_summary(Path("data.xlsx"))
>>> print(summary)
>>> # 输出示例:
>>> #   工作表   单元格        批注内容
>>> # 0  Sheet1   A1   请注意此单元格
>>> # 1  Sheet1   B5   需要审核

static get_all_comments(file_path)

获取整个工作簿的所有批注

遍历所有工作表和单元格，收集所有批注信息。

参数:

file_path (Path) -- Excel文件路径

返回:

嵌套字典结构

外层键为工作表名称，内层键为单元格坐标，值为批注内容

返回类型:

Dict[str, Dict[str, str]]

示例

>>> all_comments = ExcelStyler.get_all_comments(Path("data.xlsx"))
>>> for sheet, cells in all_comments.items():
...     print(f"工作表: {sheet}")
...     for cell, comment in cells.items():
...         print(f"  {cell}: {comment}")

static get_comment_at(file_path, sheet_name, row, col)

获取指定单元格的批注内容

参数:

• file_path (Path) -- Excel 文件路径

• sheet_name (str | int) -- 工作表名称或索引

• row (int) -- 行号（1 基）

• col (int) -- 列号（1 基）

返回:

批注文本，无批注时返回 None

返回类型:

Optional[str]

static get_comments_in_column(file_path, sheet_name, column)

获取指定列的所有批注

参数:

• file_path (Path) -- Excel 文件路径

• sheet_name (str | int) -- 工作表名称或索引

• column (int) -- 列号（1 基）

返回:

键为行号（1 基），值为批注文本； 工作表不存在时返回空字典。

返回类型:

Dict[int, str]

static find_comments_by_keyword(file_path, keyword)

按关键词搜索批注

参数:

• file_path (Path) -- Excel 文件路径

• keyword (str) -- 搜索关键词

返回:

包含 工作表/单元格/批注内容 三列，仅保留 批注内容中包含关键词的行。

返回类型:

pd.DataFrame

static read_with_comments_merged(file_path, sheet_name=0, comment_column=None)

读取数据并将指定列的批注合并为新列

参数:

• file_path (Path) -- Excel 文件路径

• sheet_name (str | int) -- 工作表名称或索引，默认为 0

• comment_column (int | None) -- 批注所在列号（1 基）；为 None 时汇总所有批注

返回:

数据 DataFrame，额外包含 comment 列

返回类型:

pd.DataFrame

static get_cell_border(cell)

获取单元格四边边框信息

参数:

cell (Cell) -- openpyxl 单元格对象

返回:

包含 top/bottom/left/right 的字典，每条边为 {"style": ..., "color": ...}；无任何边框时返回 None

返回类型:

Optional[Dict]

static set_cell_border(cell, style='thin', color='000000')

为单元格四边设置统一边框

参数:

• cell (Cell) -- openpyxl 单元格对象

• style (str) -- 边框样式（如 thin/medium/thick）

• color (str) -- 边框颜色（ARGB 或 RGB 十六进制）

返回类型:

None

static add_border_to_range(ws, min_row, min_col, max_row, max_col, style='thin', color='000000')

为矩形区域的所有单元格添加统一边框

参数:

• ws (Any) -- openpyxl 工作表对象

• min_row (int) -- 起始行（1 基）

• min_col (int) -- 起始列（1 基）

• max_row (int) -- 结束行（1 基）

• max_col (int) -- 结束列（1 基）

• style (str) -- 边框样式

• color (str) -- 边框颜色

返回类型:

None

static get_range_borders(ws, min_row, min_col, max_row, max_col)

获取矩形区域内所有单元格的边框信息

参数:

• ws (Any) -- openpyxl 工作表对象

• min_row (int) -- 起始行（1 基）

• min_col (int) -- 起始列（1 基）

• max_row (int) -- 结束行（1 基）

• max_col (int) -- 结束列（1 基）

返回:

键为单元格坐标（如 "A1"），值为 get_cell_border 返回的四边边框信息（含 None 边）。

返回类型:

Dict[str, Dict]

static get_cell_hyperlink(cell)

获取单元格超链接目标地址

参数:

cell (Cell) -- openpyxl 单元格对象

返回:

超链接地址，无超链接时返回 None

返回类型:

Optional[str]

static get_style_dataframe(file_path, sheet_name=0)

读取并返回单元格样式 DataFrame

逐行读取背景色、字体色与批注，组成与数据等形的 DataFrame。

参数:

• file_path (Path) -- Excel 文件路径

• sheet_name (str | int) -- 工作表名称或索引，默认为 0

返回:

包含 bg_color / font_color / comment 等列的样式表

返回类型:

pd.DataFrame