Excel hscredit.excel

ExcelWriter 上下文管理器与 dataframe2excel 等工具，支持写入数据表、插入图片/ 超链接、条件格式、单元格样式、数字格式、冻结窗格、列宽调整与模板化输出。

大数据集保样式快速写入

dataframe2excel 的 speed 默认是 "auto"，会根据 DataFrame 的大小和维数 自动选择写入路径。满足以下任一条件时使用快速路径：数据行数不少于 500、有效列数 （包含写出的索引层级）不少于 50，或有效单元格数不少于 10000。其余情况使用普通路径。

无论选择哪条路径，都会保留标题、表头、内容填充、边框、合并、数字格式、条件格式、 图片、筛选和自动列宽，不会生成无样式 Excel。通常直接使用默认设置即可：

from hscredit.excel import dataframe2excel

dataframe2excel(
    df,
    "特征明细.xlsx",
    sheet_name="特征明细",
    auto_width=True,
)

需要固定写入路径时，可显式指定 speed="normal" 或 speed="fast"，显式设置会 覆盖自动判断：

dataframe2excel(df, "兼容模式.xlsx", speed="normal")
dataframe2excel(df, "快速模式.xlsx", speed="fast")

浮点值精度使用与 ScoreCard 一致的 decimal 参数。默认 decimal=4 保持历史 行为；传入 decimal=None 时不主动舍入 DataFrame 浮点值：

dataframe2excel(df, "原始精度.xlsx", speed="fast", decimal=None)

对于包含多个工作表或多张表格的报告，应复用同一个 ExcelWriter，全部写入完成后只 保存一次。大表的自动列宽会在数据写完后统一处理，不再逐单元格重复扫描。

Excel报告生成模块.

提供专业的Excel报告生成功能，支持丰富的样式和格式化选项。

核心功能: - ExcelWriter: Excel写入器，支持DataFrame、图片、超链接等 - dataframe2excel: 快速将DataFrame写入Excel的便捷函数 - DataFrame.save(): pandas DataFrame的save方法扩展（在utils.pandas_extensions中统一注册） - Series.save(): pandas Series的save方法扩展（在utils.pandas_extensions中统一注册） - register_pivot_aggregation: 注册数据透视表聚合方式别名

使用示例:

>>> import pandas as pd
>>> from hscredit.excel import ExcelWriter
>>>
>>> # DataFrame直接保存
>>> df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
>>> df.save("report.xlsx", sheet_name="数据", title="统计表")
>>>
>>> # Series直接保存（自动转为DataFrame）
>>> s = pd.Series([1, 2, 3], name='数值')
>>> s.save("series_report.xlsx", title="序列数据")
>>>
>>> # 写入已有的ExcelWriter
>>> writer = ExcelWriter()
>>> worksheet = writer.get_sheet_by_name("Sheet1")
>>> df.save(writer, worksheet=worksheet)
>>> writer.save("report.xlsx")

class hscredit.excel.ExcelWriter(style_excel=None, style_sheet_name='初始化', mode='replace', fontsize=10, font=None, theme_color='2639E9', opacity=0.85, system=None, condition_color='F76E6C')

基类：object

Excel写入器，提供专业的Excel报告生成功能。

支持DataFrame数据写入、图片插入、超链接等功能。 支持上下文管理器（with语句）自动保存。

参数:

• style_excel (str | None) -- 样式模板或已有Excel文件路径，默认使用包内的template.xlsx

• style_sheet_name (str) -- 模板文件内初始样式sheet名称，默认为"初始化"；已有Excel中不存在该 Sheet时保留全部业务Sheet，后续工作表直接创建为空白Sheet

• mode (str) -- 写入模式，可选'replace'或'append'，默认为'replace' - replace: 替换已有文件 - append: 在已有文件基础上追加内容

• fontsize (int) -- 字体大小，默认为10

• font (str | None) -- 字体名称，默认为"阿里妈妈方圆体 VF Medium"；安装不可用时回退为"楷体"

• theme_color (str) -- 主题颜色（不包含#），默认为"2639E9"

• opacity (float) -- 颜色填充的透明度，默认为0.85

• system (str | None) -- 操作系统类型，可选'mac'、'windows'、'linux'，默认自动检测

• condition_color (str) -- 条件格式颜色（不包含#），默认为副主题色"F76E6C"

参考样例

>>> import pandas as pd
>>> from hscredit.excel import ExcelWriter
>>>
>>> # 方法1：使用with语句（推荐，自动保存）
>>> with ExcelWriter(theme_color='3f1dba').set_filename("report.xlsx") as writer:
...     worksheet = writer.get_sheet_by_name("模型报告")
...     writer.insert_value2sheet(worksheet, "B2", value="模型报告", style="header")
...     df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
...     writer.insert_df2sheet(worksheet, df, "B4")
>>> # 文件在退出with块时自动保存
>>>
>>> # 方法2：手动调用save（原有方式）
>>> writer = ExcelWriter(theme_color='3f1dba')
>>> worksheet = writer.get_sheet_by_name("模型报告")
>>> writer.insert_value2sheet(worksheet, "B2", value="模型报告", style="header")
>>> df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
>>> writer.insert_df2sheet(worksheet, df, "B4")
>>> writer.save("report.xlsx")

AUTO_FAST_MIN_CELLS = 10000

AUTO_FAST_MIN_COLUMNS = 50

AUTO_FAST_MIN_ROWS = 500

add_auto_filter(worksheet, ref=None)

给工作表添加自动筛选（auto_filter）。

参数:

• worksheet (Worksheet | str) -- 工作表对象或名称

• ref (str | None) -- 筛选区域，如"A1:E10"，默认为整个有数据的区域

返回类型:

None

add_conditional_formatting(worksheet, start_space, end_space, condition_color=None)

设置条件格式（数据条）。

参数:

• worksheet (Worksheet) -- 工作表对象

• start_space (str) -- 开始单元格位置，如'B2'

• end_space (str) -- 结束单元格位置，如'B10'

• condition_color (str | None) -- 条件格式颜色，默认使用ExcelWriter的condition_color

返回类型:

None

add_sparkline(worksheet, location, data_range, type='line', series_color=None, negative_color=None, markers=False, marker_color=None, high_point=False, low_point=False, first_point=False, last_point=False, negative_points=False, high_color=None, low_color=None, first_color=None, last_color=None, display_x_axis=False, show_empty_as='gap', line_weight=None)

向单元格插入迷你图（Sparkline）。

在单个单元格内绘制折线图、柱状图或盈亏图，效果类似 xlsxwriter 的 add_sparkline。 由于 openpyxl 不支持写入迷你图，本方法仅记录配置，在 save() 时将 x14:sparklineGroups 注入到 worksheet XML 中。默认配色采用 hscredit 主题风格。

备注

迷你图通过直接修改 xlsx 内部 XML 实现，Excel 可正常显示。但 openpyxl 不识别该扩展， 若用 openpyxl 重新打开并保存（含 mode='append' 追加模式），迷你图会丢失。 建议迷你图在最终输出步骤添加。

参数:

• worksheet (Worksheet | str) -- 工作表对象或名称

• location (str | List[str]) -- 迷你图所在单元格，如'H2'；可传列表与 data_range 一一对应批量生成同组迷你图

• data_range (str | List[str]) -- 数据区域，如'B2:G2'或'Sheet1!B2:G2'（未含sheet名时默认当前sheet）；可传列表

• type (str) -- 迷你图类型，可选'line'(折线)、'column'(柱状)、'win_loss'(盈亏)，默认'line'

• series_color (str | None) -- 主体颜色，默认为主题色

• negative_color (str | None) -- 负值颜色（盈亏图/柱状图负值），默认为 hscredit 坏样本红

• markers (bool) -- 是否显示数据点标记（仅折线图），默认为False

• marker_color (str | None) -- 标记颜色，默认同 series_color

• high_point (bool) -- 是否高亮最高点，默认为False

• low_point (bool) -- 是否高亮最低点，默认为False

• first_point (bool) -- 是否高亮首点，默认为False

• last_point (bool) -- 是否高亮尾点，默认为False

• negative_points (bool) -- 是否高亮负值点，默认为False

• high_color (str | None) -- 最高点颜色，默认同 series_color

• low_color (str | None) -- 最低点颜色，默认同 negative_color

• first_color (str | None) -- 首点颜色，默认为提升橙

• last_color (str | None) -- 尾点颜色，默认为提升橙

• display_x_axis (bool) -- 是否显示横轴（数据含正负时分隔），默认为False

• show_empty_as (str) -- 空单元格显示方式，可选'gap'(留空)、'zero'(零)、'span'(连线)，默认'gap'

• line_weight (float | None) -- 折线粗细（磅），默认为None（使用Excel默认）

返回类型:

None

参考样例

>>> # 在 H2 单元格按 B2:G2 数据绘制折线迷你图
>>> writer.add_sparkline(ws, "H2", "B2:G2", markers=True, high_point=True, low_point=True)
>>>
>>> # 柱状迷你图
>>> writer.add_sparkline(ws, "H3", "B3:G3", type="column")
>>>
>>> # 盈亏迷你图
>>> writer.add_sparkline(ws, "H4", "B4:G4", type="win_loss")

adjust_columns_width(worksheet, columns=None, start_col=None, end_col=None, max_width=50, min_width=8, extra_padding=2.0)

批量调整多列宽度，确保已有单元格和模板列样式不丢失。

通过恢复调用前的单元格样式快照，并保留模板列维度样式，避免列宽调整影响空白区域白底。

参数:

• worksheet (Worksheet) -- 工作表对象

• columns (str | List[str] | int | List[int] | None) -- 需要调整宽度的列，可以是列字母或列索引列表，默认为None（自动检测所有有数据的列）

• start_col (str | int | None) -- 起始列，与 columns 参数互斥

• end_col (str | int | None) -- 结束列，与 columns 参数互斥

• max_width (float) -- 最大列宽，默认为50

• min_width (float) -- 最小列宽，默认为8

• extra_padding (float) -- 额外填充宽度，默认为2.0

返回类型:

None

参考样例

>>> # 调整指定列
>>> writer.adjust_columns_width(worksheet, columns=['A', 'B', 'C'])
>>>
>>> # 调整列范围
>>> writer.adjust_columns_width(worksheet, start_col='A', end_col='F')
>>>
>>> # 自动检测并调整所有有数据的列
>>> writer.adjust_columns_width(worksheet)

static astype_insertvalue(value, decimal=4)

格式化需要存储Excel的内容。

参数:

• value (Any) -- 需要插入Excel的内容

• decimal (int | None) -- 如果是浮点型，需要保留的小数位数，默认为4；None 表示不主动舍入

返回:

格式化后的内容

返回类型:

Any

static calc_continuous_cnt(list_, index_=0)

计算列表中从某个索引开始连续出现某个元素的个数。

参数:

• list_ (List) -- 需要检索的列表

• index_ (int) -- 起始索引，默认为0

返回:

(元素值, 索引值, 连续出现的个数)

返回类型:

Tuple[Any, int | None, int | None]

参考样例

>>> calc_continuous_cnt = ExcelWriter.calc_continuous_cnt
>>> list_ = ['A','A','A','A','B','C','C','D','D','D']
>>> calc_continuous_cnt(list_, 0)
('A', 0, 4)
>>> calc_continuous_cnt(list_, 4)
('B', 4, 1)

static calculate_rgba_color(hex_color, opacity, prefix='#')

根据颜色和透明度计算对应的颜色值。

参数:

• hex_color (str) -- hex格式的颜色值

• opacity (float) -- 透明度，[0, 1]之间的数值

• prefix (str) -- 返回颜色的前缀，默认为"#"

返回:

对应某个透明度的颜色

返回类型:

str

static check_contain_chinese(check_str)

检查字符串中是否包含中文。

参数:

check_str (str) -- 需要检查的字符串

返回:

(每个字符是否是中文的列表, 英文字符个数, 中文字符个数)

返回类型:

Tuple[List[bool], int, int]

static get_cell_space(space)

转换单元格位置格式。

支持两种格式： - 字符串格式: 'B2' - 元组格式: (2, 2) 表示第2行第2列

参数:

space (str | Tuple[int, int]) -- 单元格位置

返回:

转换后的格式

返回类型:

Tuple[int, int] | str

参考样例

>>> get_cell_space = ExcelWriter.get_cell_space
>>> get_cell_space("B3")
(2, 3)
>>> get_cell_space((2, 2))
'B2'

get_sheet_by_name(name)

获取或创建指定名称的工作表。

参数:

name (str) -- 工作表名称

返回:

工作表对象

返回类型:

Worksheet

init_style(font, fontsize, theme_color)

初始化单元格样式。

参数:

• font (str) -- 字体名称

• fontsize (int) -- 字体大小

• theme_color (str) -- 主题颜色

返回类型:

None

insert_bin_chart2sheet(worksheet, data, table_anchor, chart_anchor=None, bar_columns=('好样本数', '坏样本数'), line_columns=('坏样本率',), category_column=None, title=None, header=True, index=False, bar_stacked=True, width=18.0, height=9.0)

基于已写入Excel的分箱统计表生成分箱图（柱状图 + 坏样本率折线，双坐标轴）。

本方法复现 hscredit.core.viz.bin_plot 的样式：左轴堆叠柱状图展示各分箱好/坏样本数， 右轴折线展示坏样本率，配色与字体均采用 hscredit 主题风格。图表数据**直接引用** worksheet 中已写入的单元格区域，故图表会随表格数据联动。

使用前需先将 feature_bin_stats 输出的分箱表通过 insert_df2sheet() （或 dataframe2excel()）写入到 table_anchor 位置（含表头）。

参数:

• worksheet (Worksheet) -- 工作表对象

• data (DataFrame) -- 分箱统计表（与写入Excel的DataFrame一致，用于定位列）

• table_anchor (str | Tuple[int, int]) -- 表格写入的左上角位置（含表头），如'B2'或(2, 2)

• chart_anchor (str | Tuple[int, int] | None) -- 图表插入位置，默认为None（自动置于表格右侧一列）

• bar_columns (Tuple[str, ...]) -- 柱状图列名（左轴），默认为("好样本数", "坏样本数")

• line_columns (Tuple[str, ...]) -- 折线图列名（右轴），默认为("坏样本率",)

• category_column (str | None) -- 分类轴列名（横轴），默认为None（优先取"分箱标签"，其次"分箱"）

• title (str | None) -- 图表标题，默认为None

• header (bool) -- 表格写入时是否含表头，默认为True

• index (bool) -- 表格写入时是否含索引，默认为False

• bar_stacked (bool) -- 柱状图是否堆叠，默认为True

• width (float) -- 图表宽度（厘米），默认为18.0

• height (float) -- 图表高度（厘米），默认为9.0

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> from hscredit.report import feature_bin_stats
>>> from hscredit.excel import ExcelWriter
>>> bin_table = feature_bin_stats(df, '某特征', target='target')
>>> writer = ExcelWriter()
>>> ws = writer.get_sheet_by_name('分箱图')
>>> writer.insert_df2sheet(ws, bin_table, 'B2', fill=True)
>>> writer.insert_bin_chart2sheet(ws, bin_table, 'B2', title='某特征分箱图')
>>> writer.save('bin_chart.xlsx')

insert_chart2sheet(worksheet, insert_space, chart, width=15.0, height=7.5)

向Excel插入原生图表（openpyxl chart 对象）。

与 insert_pic2sheet() 不同，此方法插入的是Excel原生图表（基于单元格数据动态生成）， 而非静态图片，可在Excel中交互、随数据更新。

参数:

• worksheet (Worksheet) -- 工作表对象

• insert_space (str | Tuple[int, int]) -- 插入位置（图表左上角锚点），如'B2'或(2, 2)

• chart (Any) -- openpyxl 图表对象（如 BarChart / LineChart）

• width (float) -- 图表宽度（厘米），默认为15.0

• height (float) -- 图表高度（厘米），默认为7.5

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

insert_df2sheet(worksheet, data, insert_space, merge_column=None, header=True, index=False, auto_width=False, fill=False, merge=False, merge_index=True, merge_header=True, decimal=4, speed='auto')

向Excel插入DataFrame。

参数:

• worksheet (Worksheet) -- 工作表对象

• data (DataFrame) -- 需要插入的DataFrame

• insert_space (str | Tuple[int, int]) -- 插入位置，如'B2'或(2, 2)

• merge_column (str | List[str] | None) -- 需要分组显示的列，默认为None

• header (bool) -- 是否存储DataFrame的header，默认为True

• index (bool) -- 是否存储DataFrame的index，默认为False

• auto_width (bool) -- 是否自动调整列宽，默认为False（在所有数据写入完成后统一调整，避免边框样式丢失）

• fill (bool) -- 是否使用颜色填充而非边框，默认为False

• merge (bool) -- 是否合并单元格，默认为False

• merge_index (bool) -- 当存储index时，是否合并连续相同的index值，默认为True

• merge_header (bool | str | int | Sequence[int]) -- 多层列名是否横向合并相邻相同标题，默认True合并全部层级； 可传False/``"none"``不合并，或传层级序号/序号列表仅合并指定层级

• decimal (int | None) -- 浮点值保留小数位数，默认4；None表示不主动舍入

• speed (str) -- 写入速度，可选``"auto"、"normal"或"fast"，默认"auto"``； 自动模式根据数据行数、有效列数和单元格数选择保样式写入路径

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> import pandas as pd
>>> df = pd.DataFrame({'A': [1, 1, 2], 'B': [4, 5, 6], 'C': [7, 8, 9]})
>>>
>>> # 基本插入
>>> writer.insert_df2sheet(worksheet, df, "B2")
>>>
>>> # 使用颜色填充
>>> writer.insert_df2sheet(worksheet, df, "B10", fill=True)
>>>
>>> # 保存索引
>>> writer.insert_df2sheet(worksheet, df.set_index('A'), "B20", index=True)
>>>
>>> # 分组显示
>>> writer.insert_df2sheet(worksheet, df, "B30", merge_column='A', merge=True)

insert_hyperlink2sheet(worksheet, insert_space, hyperlink=None, file=None, sheet=None, target_space=None)

向单元格插入超链接。

参数:

• worksheet (Worksheet) -- 工作表对象

• insert_space (str | Tuple[int, int]) -- 插入位置，如'B2'或(2, 2)

• hyperlink (str | None) -- 超链接地址，与target_space互斥

• file (str | None) -- 超链接文件路径，默认当前文件

• sheet (str | None) -- 超链接sheet名称，默认当前sheet

• target_space (str | Tuple[int, int] | None) -- 超链接目标位置，如'B10'或(10, 2)

返回类型:

None

参考样例

>>> # 链接到当前sheet的其他位置
>>> writer.insert_hyperlink2sheet(worksheet, "B2", target_space="B10")
>>>
>>> # 链接到其他sheet
>>> writer.insert_hyperlink2sheet(worksheet, "B2", sheet="Sheet2", target_space="A1")
>>>
>>> # 链接到外部文件
>>> writer.insert_hyperlink2sheet(worksheet, "B2", file="other.xlsx", sheet="Sheet1", target_space="A1")

insert_pic2sheet(worksheet, fig, insert_space, figsize=(600, 250))

向Excel插入图片。

参数:

• worksheet (Worksheet) -- 工作表对象

• fig (str) -- 图片路径

• insert_space (str | Tuple[int, int]) -- 插入位置，如'B2'或(2, 2)

• figsize (Tuple[int, int]) -- 图片大小(宽, 高)，默认为(600, 250)

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

insert_pivot_chart2sheet(worksheet, chart_anchor, pivot_name=None, chart_type='bar', title=None, width=15.0, height=7.5, bar_stacked=False)

基于已创建的数据透视表插入Excel原生数据透视图。

本方法先用 openpyxl 在透视表输出区域上构建普通图表（柱状/折线/饼图）， 并在 save() 时向该图表 XML 注入 c:pivotSource，使其成为绑定到透视表的 原生数据透视图，可随透视表刷新联动。

需先调用 insert_pivot_table2sheet() 创建透视表。

参数:

• worksheet (Worksheet | str) -- 透视图放置的工作表对象或名称（通常与透视表同表）

• chart_anchor (str | Tuple[int, int]) -- 图表插入位置，如'H2'或(2, 8)

• pivot_name (str | None) -- 关联的透视表名称，默认为None（取最近创建的透视表）

• chart_type (str) -- 图表类型，可选'bar'(柱状)、'line'(折线)、'pie'(饼图)，默认'bar'

• title (str | None) -- 图表标题，默认为None

• width (float) -- 图表宽度（厘米），默认为15.0

• height (float) -- 图表高度（厘米），默认为7.5

• bar_stacked (bool) -- 柱状图是否堆叠，默认为False

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> writer.insert_pivot_table2sheet(ws, df, 'B2', rows='商品类别', values=[('放款金额', 'sum')])
>>> writer.insert_pivot_chart2sheet(ws, 'H2', chart_type='bar', title='各类别放款金额')

insert_pivot_table2sheet(worksheet, data=None, pivot_anchor=None, rows=None, columns=None, values=None, filters=None, filter_items=None, groups=None, subtotals=False, source_sheet=None, source_anchor=(1, 1), write_source=None, name=None, show_row_totals=True, show_col_totals=True, theme_style=True, style=None, fill=True, source_range=None)

向工作表插入Excel原生数据透视表。

由于 openpyxl 不支持创建数据透视表，本方法仅记录配置，在 save() 时将 pivotCacheDefinition / pivotCacheRecords / pivotTable 等部件注入到 xlsx 中，生成 Excel 可交互、可刷新的原生数据透视表。透视缓存写入 refreshOnLoad="1"， Excel 打开时会基于源数据自动刷新。

备注

将已有文件作为 style_excel 加载时，可保留其中已有透视表并继续追加。若仅在 save() 阶段通过 mode='append' 合并另一个目标文件，仍只复制单元格值/样式， 不保证保留该目标文件中的原生图、迷你图与图片；此类文件应先作为 style_excel 加载。

参数:

• worksheet (Worksheet | str) -- 透视表放置的工作表对象或名称

• data (DataFrame | None) -- 源数据 DataFrame（透视缓存基于此构建）。省略时从 source_sheet 的 source_range 读取

• pivot_anchor (str | Tuple[int, int] | None) -- 透视表左上角锚点，如'B2'或(2, 2)

• rows (str | List[str] | None) -- 行字段（列名或列名列表），默认为None

• columns (str | List[str] | None) -- 列字段（列名或列名列表），默认为None

• values (Any | None) --

  值字段，支持多种形式：

  • '金额' 或 ['金额', '数量']：默认聚合（数值列求和，非数值列计数）

  • [('金额', 'sum'), ('数量', 'mean')]：显式指定聚合

  • [('金额', 'sum', '全局占比')]：聚合 + 占比显示（全局/行/列/组合占比）

  • {'金额': 'sum'} 或 [{'field': '金额', 'agg': 'sum', 'show_as': '全局占比', 'name': '占比', 'number_format': '0.00%'}]

  聚合：sum/count/average(mean)/max/min/product/count_nums/std/stdp/var/varp （可用 hscredit.excel._pivot.register_aggregation 扩展别名）

• filters (str | List[str] | Dict[Any, Any] | None) -- 页/筛选字段。列名/列名列表，或 {字段: [允许值]} 直接指定筛选项

• filter_items (Dict[Any, Any] | None) -- 筛选项 {字段: [允许值]}，可作用于行/列/筛选任一字段，仅保留所列取值

• groups (Dict[Any, Any] | None) -- 数值字段分组 {字段: {'start': 起始值, 'interval': 步长}} （亦支持 {字段: (起始, 步长)}），对横轴/纵轴数值特征按步长分桶统计

• subtotals (bool) -- 是否对非最内层行/列字段显示分类汇总，默认为False

• source_sheet (Worksheet | str | None) -- 源数据所在工作表对象或名称，默认为None（自动新建源数据表写入 data）

• source_anchor (str | Tuple[int, int]) -- 源数据写入/定位的左上角（含表头），默认为(1, 1)

• write_source (bool | None) -- 是否写入源数据，默认为None（source_sheet 为None时自动写入）

• name (str | None) -- 透视表名称，默认为None（自动命名「数据透视表N」）

• show_row_totals (bool) -- 是否显示行总计，默认为True

• show_col_totals (bool) -- 是否显示列总计，默认为True

• theme_style (bool) -- 是否套用适配 theme_color 的 hscredit 主题样式，默认为True

• style (str | None) -- 透视表样式名，默认为None（theme_style 为True时用主题样式，否则用内置 PivotStyleLight16）

• fill (bool) -- 自动写入源数据时是否使用颜色填充，默认为True

• source_range (str | None) -- 已有源数据区域（含首行字段名），如 'A1:H5000'。 仅在 data 为None时使用，且不会改写源数据

返回:

(透视表区域下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> import pandas as pd
>>> from hscredit.excel import ExcelWriter
>>> df = pd.DataFrame({
...     '商品类别': ['数码', '服饰', '数码', '服饰'],
...     '区域': ['华东', '华东', '华南', '华南'],
...     '放款金额': [100, 200, 300, 400],
... })
>>> with ExcelWriter(theme_color='2639E9').set_filename('pivot.xlsx') as writer:
...     ws = writer.get_sheet_by_name('透视表')
...     writer.insert_pivot_table2sheet(
...         ws, df, 'B2',
...         rows='商品类别', columns='区域',
...         values=[('放款金额', 'sum'), ('放款金额', 'sum', '全局占比')],
...         groups={'放款金额': {'start': 0, 'interval': 100}},
...         subtotals=True,
...     )
>>> # 也可直接引用已有Excel中的数据区域，不会重写源数据
>>> writer = ExcelWriter(style_excel='existing.xlsx', mode='append')
>>> writer.insert_pivot_table2sheet(
...     worksheet='透视分析', pivot_anchor='B2',
...     source_sheet='贷款明细', source_range='A1:H5000',
...     rows='区域', values=[('放款金额', 'sum')],
... )
>>> writer.save('existing.xlsx')  # 或另存为其他路径

insert_rows(worksheet, row, row_index, col_index, merge_rows=None, style='', auto_width=False, style_only=False, multi_levels=False, decimal=4)

向Excel插入一行数据。

参数:

• worksheet (Worksheet) -- 工作表对象

• row (List) -- 行数据

• row_index (int) -- 行索引

• col_index (str | int) -- 起始列索引或字母

• merge_rows (List[int] | None) -- 需要合并的行索引列表，默认为None

• style (str) -- 样式名称，默认为空

• auto_width (bool) -- 是否自动调整列宽，默认为False（推荐在数据全部写入后使用 adjust_columns_width 批量调整）

• style_only (bool) -- 是否仅应用样式，默认为False

• multi_levels (bool) -- 是否多层索引，默认为False

• decimal (int | None)

返回类型:

None

insert_value2sheet(worksheet, insert_space, value='', style='content', auto_width=False, end_space=None, align=None, max_col_width=50, decimal=4)

向单元格插入内容。

参数:

• worksheet (Worksheet) -- 工作表对象

• insert_space (str | Tuple[int, int]) -- 插入位置，如'B2'或(2, 2)

• value (Any) -- 插入的内容，默认为""

• style (str) -- 样式名称，默认为"content"

• auto_width (bool) -- 是否自动调整列宽，默认为False（推荐在数据全部写入后使用 adjust_columns_width 批量调整）

• end_space (str | Tuple[int, int] | None) -- 合并单元格的结束位置，默认为None

• align (Dict[str, str] | None) -- 文本对齐方式，默认为None，例如{'horizontal': 'left', 'vertical': 'center'}

• max_col_width (int) -- 最大列宽，默认为50

• decimal (int | None)

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> # 插入普通内容
>>> writer.insert_value2sheet(worksheet, "B2", value="模型报告", style="header")
>>>
>>> # 合并单元格
>>> writer.insert_value2sheet(worksheet, "B2", value="标题", style="header", end_space="D2")
>>>
>>> # 批量调整列宽（推荐在所有数据写入完成后调用）
>>> writer.adjust_columns_width(worksheet, columns=['A', 'B', 'C'])

数字样字符串（如 "466"、"25%"、"00123"）会保持为文本；保存时自动关闭 Excel 的“以文本形式存储的数字”错误提示。

static is_numeric_like_string(value)

检查值是否为类似数字的字符串（如 "123"、"00123"、"123.45"、"12.34%"、"1,234.56"）。

这类字符串在Excel中会显示绿色感叹号（以文本形式存储的数字）。

参数:

value (Any) -- 需要检查的值

返回:

如果是类似数字的字符串返回True，否则返回False

返回类型:

bool

static itlubber_border(border, color, white=False)

生成边框样式。

参数:

• border (List[str]) -- 边框样式列表，长度为3或4。长度为3表示[左, 右, 下]，长度为4表示[左, 右, 下, 上]

• color (List[str]) -- 边框颜色列表

• white (bool) -- 是否显示白色边框，默认为False

返回:

边框对象

返回类型:

Border

merge_cells(worksheet, start, end)

合并单元格并保证样式正确合并。

参数:

• worksheet (Worksheet) -- 工作表对象

• start (str | Tuple[int, int]) -- 开始位置，如'B2'或(2, 2)

• end (str | Tuple[int, int]) -- 结束位置，如'F10'或(10, 6)

返回类型:

None

move_sheet(worksheet, offset=0, index=None)

移动工作表位置。

参数:

• worksheet (Worksheet | str) -- 工作表对象或名称

• offset (int) -- 相对移动位置，默认为0

• index (int | None) -- 移动到的目标绝对位置索引（从0开始），默认为None；传入时忽略 offset

返回类型:

None

save(filename, close=True)

保存Excel文件。

备注

迷你图、数据透视表/透视图均在 openpyxl 保存后通过注入 xlsx 内部 XML 实现。 将已有文件作为 style_excel 加载可保留并追加透视表；但仅在保存阶段通过 mode='append' 合并另一个目标文件时，只复制单元格值/样式，不保证保留该目标 文件中的迷你图、透视表、原生图与图片。

参数:

• filename (str) -- 保存路径

• close (bool) -- 是否关闭workbook，默认为True

返回类型:

None

static set_column_width(worksheet, column, width)

调整Excel列宽。

参数:

• worksheet (Worksheet) -- 工作表对象

• column (str | int) -- 列，可以是字母（如'B'）或索引（如2）

• width (float) -- 列宽

返回类型:

None

set_filename(filename)

设置用于上下文管理器自动保存的文件路径。

支持链式调用，可以与with语句配合使用。

参数:

filename (str) -- 保存路径

返回:

self

返回类型:

ExcelWriter

参考样例

>>> # 方法1：使用set_filename设置路径
>>> with ExcelWriter().set_filename("report.xlsx") as writer:
...     worksheet = writer.get_sheet_by_name("Sheet1")
...     writer.insert_value2sheet(worksheet, "B2", "Hello")
>>> # 文件自动保存到report.xlsx

>>> # 方法2：手动调用save（原有方式）
>>> writer = ExcelWriter()
>>> worksheet = writer.get_sheet_by_name("Sheet1")
>>> writer.insert_value2sheet(worksheet, "B2", "Hello")
>>> writer.save("report.xlsx")

set_freeze_panes(worksheet, space)

设置冻结窗格。

参数:

• worksheet (Worksheet | str) -- 工作表对象或名称

• space (str | Tuple[int, int]) -- 冻结位置，如'B2'或(2, 2)

返回类型:

None

static set_number_format(worksheet, space, _format)

设置数值显示格式。

参数:

• worksheet (Worksheet) -- 工作表对象

• space (str) -- 单元格范围，如'B2:B10'

• _format (str) -- 显示格式，如'0.00%'或'#,##0'

返回类型:

None

hscredit.excel.dataframe2excel(data, excel_writer, sheet_name=None, title=None, header=True, theme_color='2639E9', condition_color=None, fill=True, percent_cols=None, condition_cols=None, custom_cols=None, custom_format='#,##0', color_cols=None, percent_rows=None, condition_rows=None, custom_rows=None, color_rows=None, left_cols=None, right_cols=None, start_col=2, start_row=2, mode='replace', figures=None, figsize=(600, 350), image_bottom_padding_rows=1, writer_params=None, auto_filter=False, decimal=4, speed='auto', **kwargs)

快速将DataFrame写入Excel。

这是一个便捷函数，封装了ExcelWriter的常用操作。

参数:

• data (DataFrame) -- 需要保存的DataFrame

• excel_writer (str | ExcelWriter) -- 文件路径或ExcelWriter对象

• sheet_name (str | None) -- 工作表名称，默认为None

• title (str | None) -- 标题，默认为None

• header (bool) -- 是否保存列名，默认为True

• theme_color (str) -- 主题颜色，默认为"2639E9"

• condition_color (str | List[str] | Dict[Any, str | List[str]] | None) --

  条件格式（数据条/颜色渐变）颜色，默认为None（使用ExcelWriter的condition_color， 其默认值为副主题色"F76E6C"）。单次传入值优先于ExcelWriter配置。支持三种类型：

  • str：所有 condition_cols/color_cols/condition_rows/color_rows 统一使用该颜色

  • list/tuple：2 或 3 个颜色组成的异色色阶锚点，仅对 color_cols/color_rows 颜色渐变生效（2 色为 [低值色, 高值色] 双色阶，3 色为 [低值色, 中值色, 高值色] 三色阶；超过 3 个自动取首/中/尾； 数据条等单色场景取末位颜色）

  • dict：以列名（或行索引值）为key分别指定颜色，值可为 str 或上述 list/tuple，匹配方式类似 condition_cols —— 单层为列名，多层级可为完整列名tuple或其中任意层级名称；未匹配到的回退使用ExcelWriter的condition_color

• fill (bool) -- 是否使用颜色填充，默认为True

• percent_cols (List | None) -- 需要显示为百分数的列，默认为None

• condition_cols (List | None) -- 需要显示数据条的列，默认为None

• custom_cols (List | None) -- 需要自定义格式的列，默认为None

• custom_format (str) -- 自定义格式，默认为"#,##0"

• color_cols (List | None) -- 需要显示颜色渐变的列，默认为None

• percent_rows (List | None) -- 需要显示为百分数的行，默认为None

• condition_rows (List | None) -- 需要显示数据条的行，默认为None

• custom_rows (List | None) -- 需要自定义格式的行，默认为None

• color_rows (List | None) -- 需要显示颜色渐变的行，默认为None

• left_cols (List | None) -- 需要左对齐的列名或列索引列表，默认为None（数据行，非表头）

• right_cols (List | None) -- 需要右对齐的列名或列索引列表，默认为None（数据行，非表头）

• start_col (int) -- 起始列，默认为2

• start_row (int) -- 起始行，默认为2

• mode (str) -- 写入模式，默认为"replace"

• figures (str | List[str] | None) -- 需要插入的图片路径，默认为None

• figsize (Tuple[int, int]) -- 图片大小，默认为(600, 350)

• image_bottom_padding_rows (int) -- 图片区与下方表格之间的额外空行数，默认为1

• writer_params (Dict | None) -- ExcelWriter参数，默认为None

• decimal (int | None) -- 浮点值保留小数位数，默认4；None表示不主动舍入

• speed (str) -- 写入速度，可选``"auto"、"normal"或"fast"，默认"auto"``； 自动模式在行数不少于500、有效列数不少于50或有效单元格数不少于10000时使用快速路径

• kwargs -- 其他参数，传递给insert_df2sheet

• auto_filter (bool)

返回:

(下一行行号, 下一列列号)

返回类型:

Tuple[int, int]

参考样例

>>> import pandas as pd
>>> from hscredit.excel import dataframe2excel
>>>
>>> # 创建示例数据
>>> df = pd.DataFrame({
...     'feature': ['A', 'B', 'C'],
...     'iv': [0.1, 0.2, 0.3],
...     'ks': [0.3, 0.4, 0.5],
...     'rate': [0.05, 0.10, 0.15]
... })
>>>
>>> # 快速写入Excel
>>> dataframe2excel(
...     df,
...     "report.xlsx",
...     sheet_name="特征分析",
...     title="特征统计表",
...     percent_cols=['rate'],  # 百分比格式
...     condition_cols=['iv', 'ks'],  # 条件格式
...     auto_width=True
... )

hscredit.excel.resolve_condition_color(condition_color, column, default_color)

解析某一列（或行）对应的条件格式单色（数据条等单色场景使用）。

参数:

• condition_color (str | List[str] | Dict[Any, str | List[str]] | None) --

  条件格式颜色配置，支持以下类型：

  • str：所有列/行统一使用该颜色

  • list/tuple：由 2 或 3 个颜色组成的色阶锚点（仅 color_cols/color_rows 颜色渐变完整生效； 数据条等单色场景取末位颜色）

  • dict：以列名（或行索引值）为key分别指定颜色，值可为 str 或上述 list/tuple，匹配方式类似 condition_cols：

    • 单层列名：key直接为列名

    • 多层级列名：key可以是完整的列名tuple，也可以是其中任意一层级的名称（优先匹配完整tuple，其次按由内到外的层级匹配）

    • dict中未匹配到的列/行回退使用 default_color

• column (Any) -- 当前列名或行索引值，多层级时为tuple

• default_color (str) -- condition_color 为None，或为dict且未匹配到时使用的颜色

返回:

最终使用的单个颜色（list/tuple 锚点取末位），去除 # 前缀并大写

返回类型:

str

参考样例

>>> resolve_condition_color('F76E6C', 'iv', '2639E9')
'F76E6C'
>>> resolve_condition_color({'iv': 'F76E6C', 'ks': '5B8FF9'}, 'iv', '2639E9')
'F76E6C'
>>> resolve_condition_color({'iv': 'F76E6C'}, 'ks', '2639E9')
'2639E9'
>>> resolve_condition_color({('分组1', 'iv'): 'F76E6C'}, ('分组1', 'iv'), '2639E9')
'F76E6C'
>>> resolve_condition_color({'iv': 'F76E6C'}, ('分组1', 'iv'), '2639E9')
'F76E6C'
>>> resolve_condition_color(['#3B82F6', '#E879F9', '#EF4444'], 'iv', '2639E9')
'EF4444'

hscredit.excel.register_pivot_aggregation(key, subtotal, prefix=None)

注册/扩展聚合方式别名（聚合函数可扩展）。

Excel 原生汇总仅 11 种（sum/count/average/max/min/product/countNums/stdDev/stdDevp/var/varp）， 本函数用于为其登记自定义别名，使 values 参数可用更贴合业务的名称。

参数:

• key (str) -- 别名（大小写不敏感），如 '总和'、'均值'

• subtotal (str) -- 对应的 OOXML 汇总取值，须为 11 种之一

• prefix (str | None) -- 中文标题前缀，默认为None（复用 subtotal 已有前缀，没有则用 key）

返回类型:

None

参考样例

>>> from hscredit.excel import _pivot
>>> _pivot.register_aggregation('均值', 'average', '平均值项')
>>> _pivot.register_aggregation('总和', 'sum')