pandas Styler 表格可视化 API 完全指南从 DataFrame.style 到 HTML / LaTeX / Typst 样式导出【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandasStyler 是 pandas 提供的一套表格可视化接口它把DataFrame/Series转化为带有 CSS 样式的 HTML 表格也支持 LaTeX、Typst、Excel 等导出让你无需依赖额外绘图库就能完成条件格式化、数据条、渐变色等常见报表美化。本文以仓库中 doc/source/reference/style.rst 的 API 清单为主线逐类讲解 Styler 的构造方式、样式应用方法、内置样式与导出接口并结合 pandas/io/formats/style.py 源码说明其底层实现与安全注意事项。读完本文你将能够用df.style快速构建专业、可复制的可视化数据表格。一、总览DataFrame.style与 Styler 体系Styler 对象的唯一入口是DataFrame.styleSeries 也可以作为构造输入其类定义位于 pandas/io/formats/style.py类名Styler(StylerRenderer)模块归属为pandas.io.formats.styleimport pandas as pd df pd.DataFrame([[1.0, 2.0, 3.0], [4, 5, 6]], index[a, b], columns[A, B, C]) styler df.style # Styler 对象 styler.to_html() # 输出 HTML 字符串Styler 采用链式调用 惰性渲染设计所有样式方法apply、map、highlight_max、bar等都不会立即计算而是把待执行任务追加到内部列表self._todo只有真正渲染如to_html、_repr_html_时才依次执行。从源码看Styler.apply的实现就是一行入队操作# pandas/io/formats/style.py#L2095-L2098 self._todo.append((lambda instance: instance._apply, (func, axis, subset), kwargs)) return self在 Jupyter Notebook 中Styler 定义了_repr_html_自动渲染style.py#L374在其他环境中则需要显式调用Styler.to_html()获取生成的 HTML。安全提示来自类文档 NotesStyler主要用于渲染你可控的、可信的数据。如果要在不可信的用户输入上渲染 HTML必须设置escapehtml否则可能引入 XSS 类安全漏洞详见 style.py#L161-L166。二、Styler 构造器直接实例化与自定义模板Styler构造参数直接实例化时Styler.__init__style.py#L214-L256接收以下参数参数默认值说明data必填待样式化的Series或DataFrameprecisionpandas.options.styler.format.precision浮点数保留小数位table_stylesNone{selector: (attr, value)}形式的列表uuid自动生成用于避免 CSS 冲突的唯一标识captionNone表格标题元组形式仅用于 LaTeX 双标题table_attributesNone追加到table开标签的属性默认自动带idcell_idsTrue每个单元格是否带id属性格式为T_uuid_rownum_row_colnum_colna_repNone缺失值显示形式回退到pandas.options.styler.format.na_repuuid_len5自动生成 uuid 的十六进制长度范围[0, 32]decimalpandas.options.styler.format.decimal小数分隔符thousandsNone千位分隔符escape选项配置html转义 latex转义 % $ # _ { } ~ ^ \latex-math在 latex 基础上保留$...$与\(...\)包裹的数学子串formatter选项配置值显示格式化见Styler.format构造器中会将这些格式化选项统一交给self.format(...)预置style.py#L242-L256所以直接实例化与df.style入口行为一致from pandas.io.formats.style import Styler styler Styler(df, precision2, captionMy table, escapehtml)Styler.from_custom_template接入自己的 Jinja2 模板内置模板由 Jinja2 渲染pandas/io/formats/style.py顶部通过import_optional_dependency(jinja2, extraDataFrame.style requires jinja2.)引入使用 Styler 必须安装 jinja2。Styler.from_custom_templatestyle.py#L4011允许指定自定义模板目录与模板文件名实现完全定制化的 HTML / LaTeX 输出from pandas.io.formats.style import Styler Styler.from_custom_template( searchpath[/path/to/templates], # 模板搜索目录 html_tablemy_html_table.tpl, # 自定义表格模板 html_stylemy_html_style.tpl, # 自定义样式模板 latexmy_latex.tpl, # 自定义 LaTeX 模板 )三、Styler 属性Jinja2 环境与模板对象文档中列出的属性直接对应 StylerRenderer 持有的渲染基础设施Styler.envJinja2Environment管理模板加载与全局变量Styler.template_html/template_html_style/template_html_table分别对应 HTML 整体、style样式块、table表格三个模板Styler.template_latex/template_typst/template_stringLaTeX、Typst、纯文本输出模板Styler.loaderJinja2Loader负责从默认模板目录或自定义模板路径加载.tpl文件。这些属性在to_html/to_latex/to_typst/to_string等导出方法中被调用例如to_html会把额外关键字参数透传给self.template.render(...)style.py#L1517-L1520这也是自定义模板时可注入额外变量的通道。四、样式应用apply/map与索引样式这是 Styler 的核心编程接口所有样式函数应返回包含 CSS 的字符串格式为attribute: value; attribute2: value2; ...不需要应用样式时返回空字符串或None。Styler.map逐元素应用func接收单个标量并返回样式字符串style.py#L2284-L2343。其底层实现通过self.data.loc[subset].map(func)逐元素计算后更新样式上下文style.py#L2275-L2282def color_negative(v, color): return fcolor: {color}; if v 0 else None df.style.map(color_negative, colorred) # 全表 df.style.map(color_negative, colorred, subsetA) # 仅 A 列 df.style.map(color_negative, colorred, subset[A, B]) df.style.map(color_negative, colorred, subset([0, 1, 2], slice(None))) # 2d 切片Styler.apply按列 / 按行 / 整表应用func的入参与axis有关style.py#L2009-L2098axis0默认即index每列一个Series入参返回等长 list-like 或带合法索引标签的Seriesaxis1即columns每行一个Series入参axisNone整个DataFrame一次性入参返回同形状 ndarray 或带合法行列标签的DataFrame这与DataFrame.apply的行为不同注意区分。def highlight_max(x, color): return np.where(x np.nanmax(x.to_numpy()), fcolor: {color};, None) df.style.apply(highlight_max, colorred) # 每列高亮最大值 df.style.apply(highlight_max, colorblue, axis1) # 每行高亮最大值 df.style.apply(highlight_max, colorgreen, axisNone)apply还支持返回不等长但含合法标签的Series/DataFrame例如对名为Total的汇总行单独加粗total_style pd.Series(font-weight: bold;, index[Total]) df.style.apply(lambda s: total_style)subset参数在所有方法中语义一致二维输入等价于DataFrame.loc[subset]一维输入或单键时等价于DataFrame.loc[:, subset]列优先。索引样式apply_index与map_indexStyler.apply_indexstyle.py#L21222.1.0 起替代已废弃的applymap_index按层级level对行索引或列索引整体应用样式函数Styler.map_indexstyle.py#L2199对索引标签逐元素应用样式函数。两者都支持axis0行索引与axis1列索引并通过refactor_levels处理 MultiIndex 的层级选择见 style.py#L2111。值格式化format/format_index/format_index_namesStyler.format控制单元格的显示文本不影响底层数据支持 str 格式化、格式化函数与列级字典df.style.format({:.2%}) # 全局百分比格式 df.style.format({A: {:.2f}, B: ${:,.2f}}) df.style.format(lambda v: f{v:,.1f} 元) # 自定义函数format_index与format_index_names分别作用于索引标签与索引名含 MultiIndex 的level、axis参数。Styler.relabel_index则用于重命名行 / 列索引标签。隐藏与布局hide/concat/set_stickyStyler.hidestyle.py#L2904按位置、标签或层级隐藏行 / 列 / 索引名 / 列名axisindex | columns | index-names | columns-names配合subset、level、names使用Styler.concatstyle.py#L258把另一个 Styler 追加到当前表格下方要求列结构与索引层级一致常用于追加汇总行合并后各 Styler 自身的样式、格式化与 CSS 类均保留Styler.set_stickystyle.py#L2604让索引列与表头在滚动时固定sticky参数axisindex | columns | both可设pixel_width/levels/z_index。表格级设置方法作用源码位置set_table_styles在style元素中添加 CSS 选择器规则并可自定义 CSS 类名css_class_namesstyle.py#L2756set_table_attributes向table开标签追加属性如classpure-tablestyle.py#L2346set_td_classes为td单元格设置class属性传入与数据同构的字符串 DataFramestyle.py#L1690set_tooltips配置悬停提示Tooltips对象可设css_name、css_props、show_arrowstyle.py#L388set_caption设置标题传入元组(长标题, 短标题)时用于 LaTeX 双标题style.py#L2555set_properties批量设置 CSS 属性如df.style.set_properties(**{background-color: yellow, font-size: 10pt})style.py#L3427set_uuid手动指定表格唯一标识用于多表共存时避免 CSS 冲突style.py#L2505clear清空已应用的全部样式与格式化就地操作返回Nonestyle.py#L1912pipe管道操作等价于f(self, *args, **kwargs)便于组合封装样式函数style.py#L4070生成的 CSS 类名规则根据Styler类文档style.py#L177-L199渲染结果会自动附加以下 CSS 类索引名与列名index_name、levelkk为 MultiIndex 层级索引标签单元格row_heading、rown、levelk列标签单元格col_heading、coln、levelk空白单元格blank数据单元格data裁剪单元格col_trim/row_trim。这些类名可通过set_table_styles的css_class_names参数整体重命名。五、内置样式高亮、渐变与数据条内置样式方法都要求 matplotlib 可用background_gradient等依赖 matplotlib colormap并自动预选数值列、忽略非数值列。高亮类highlight_null高亮缺失值style.py#L3604参数null_colorred、subset、props自定义完整 CSS 属性时null_color被忽略highlight_max/highlight_minstyle.py#L3656、style.py#L3715高亮每列 / 每行 / 整表的最大或最小值支持axis、subset、color、propshighlight_betweenstyle.py#L3774高亮落在[left, right]含inclusive参数区间内的值highlight_quantilestyle.py#L3893高亮位于指定分位数区间的值。df.style.highlight_null(null_colorpink) df.style.highlight_max(axis0, colorlightgreen) df.style.highlight_between(left1, right4, inclusiveboth) df.style.highlight_quantile(q_left0.25, q_right0.75, axis1)渐变色background_gradient与text_gradientbackground_gradientstyle.py#L3121按数据在每列 / 每行 / 整表的相对大小映射 matplotlib 色带默认cmapPuBudf.style.background_gradient(cmapviridis, axisNone, vmin0, vmax100) df.style.background_gradient(cmapRdBu, low0.1, high0.1) # 向两端扩展色带范围关键参数cmapmatplotlib colormap 名称或对象如viridis、RdBulow/high按数据范围map.min - low * map.range与map.max high * map.range扩展色带两端推荐取值[0, 1]vmin/vmax手动指定与色带最小 / 最大值对应的数据边界text_color_threshold文本颜色亮度阈值默认0.408用于保证深色 / 浅色背景上的文字可读性0 时文字全深色1 时文字全浅色gmap自定义渐变映射数组形状须与数据一致指定后vmin/vmax应相对于该映射给出。text_gradientstyle.py#L3279参数与之完全一致区别是只对文字颜色应用渐变。数据条barbarstyle.py#L3473在单元格内绘制水平数据条通过 CSS 渐变与background定位实现df.style.bar(color#d65f5f, width90, alignleft) df.style.bar(subset[A], alignzero, color[#d65f5f, #5fba7d])参数要点color支持单个颜色或[负值色, 正值色]列表width为条宽百分比[0, 100]默认 100align支持left | zero | mid分别表示从左侧起、以 0 为中点、以区间中点为基准vmin/vmax限制数据条刻度范围。条形的颜色计算与 CSS 拼接在Styler.css_bar/Styler.css_calc中实现style.py#L4444、style.py#L4477。六、样式导出与复用HTML / LaTeX / Typst / Excel / 字符串Styler.to_html最常用的导出接口style.py#L1443输出styletable两个 HTML 片段bufNone时以字符串返回html df.style.highlight_max().to_html() df.style.to_html(styled_table.html, doctype_htmlTrue) # 输出完整 HTML 文档 df.style.to_html(bufio.StringIO(), encodingutf-8)参数说明参数默认值说明bufNone文件路径或带write()的文件对象None返回字符串table_uuidStyler 既有值覆盖table idT_table_uuidtable_attributesStyler 既有值覆盖table开标签属性sparse_index/sparse_columnspandas.options.styler.sparse.*层次化索引是否压缩显示False时每行显式展示各层级bold_headersFalse表头加粗font-weight: bold;captionNone覆盖标题max_rows/max_columnspandas.options.styler.render.max_rows/max_columns渲染行 / 列上限总元素数受styler.render.max_elements262144对应 18 bit 浏览器渲染限制encodingutf-8文件编码同时写入 meta 标签doctype_htmlFalse是否输出含完整 HTML 文档结构的片段exclude_stylesFalse为True时只输出table本体去掉style与所有 class / id 标识**kwargs—透传给 Jinja2template.render供自定义模板注入变量Styler.to_latex与Styler.to_typstto_latexstyle.py#L686输出 LaTeX 表格支持column_format、position、hrulesbooktabs 风格横线、label、caption、clines、convert_css把常用 CSS 样式映射为 LaTeX 命令等参数to_typststyle.py#L1297输出 Typst 排版格式表格用于替代 LaTeX 的轻量文档工作流。Styler.to_excel使用Styler.to_excelstyle.py#L516可以把已应用的样式写入 Excel需配合ExcelWriter使用样式会在单元格层级保留颜色、字体、边框等视觉属性。Styler.to_string以纯文本形式输出表格无样式适合终端展示或日志。export/use样式跨表复用Styler.exportstyle.py#L2378导出与数据无关的样式apply/map注册的样式函数、表格属性、表格样式、行列隐藏开关与 CSS 类名Styler.usestyle.py#L2437将其套用到另一个 Stylerstyler pd.DataFrame([[1, 2], [3, 4]]).style styler2 pd.DataFrame([[9, 9, 9]]).style styler.hide(axis0).highlight_max(axis1) export styler.export() styler2.use(export)与Styler.copy数据与样式一起复制不同export刻意不包含caption、uuid、tooltips、按索引标签隐藏的行列、format格式化以及set_td_classes添加的类因为这些通常依赖具体数据见 style.py#L2400-L2415 的导出清单。七、完整示例从数据到成品报表把以上 API 组合成一段可运行的端到端示例import pandas as pd import numpy as np np.random.seed(42) df pd.DataFrame( np.random.randn(6, 4) * 10, index[frow{i} for i in range(6)], columns[A, B, C, D], ) styler ( df.style .format({:.2f}) # 数值格式化 .highlight_null(null_colorpink) # 缺失值 .highlight_max(axis0, colorlightgreen) # 每列最大值 .background_gradient(cmapPuBu, axisNone, vmin-15, vmax15) # 渐变背景 .bar(subset[D], color#d65f5f, alignzero) # D 列数据条 .set_caption(2026 年度销售分析) .set_table_attributes(classdataframe-report) # 追加 CSS 类 .set_sticky(axisindex, pixel_width60) # 固定索引列 ) html styler.to_html(doctype_htmlTrue) with open(report.html, w, encodingutf-8) as f: f.write(html)在 Jupyter 中直接以单元格最后一行书写styler即可自动渲染交互式表格脚本环境则用to_html/to_latex/to_typst/to_excel按需导出。八、深入阅读完整的 API 清单见 doc/source/reference/style.rst含 Styler 构造器、属性、样式应用、内置样式与导出共五大类接口交互式图文教程含大量可视化示例见 doc/source/user_guide/style.ipynb即原文档中Table Visualization指引指向的文件核心实现位于 pandas/io/formats/style.py约 4600 行模板渲染逻辑在 pandas/io/formats/style_render.pyHTML / LaTeX / Typst 的.tpl模板文件位于 pandas/io/formats/templates相关测试集中在 pandas/tests/io/formats/style/ 与 pandas/tests/io/formats/test_style.py可作为行为基准参考。一句话总结df.style返回的 Styler 对象是 pandas 表格可视化的统一入口配合apply/map编程式样式、内置高亮与渐变、以及to_html/to_latex/to_typst/to_excel多种导出通道你可以在纯 pandas 生态内完成从数据处理到成品报表的全部工作。【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考