PAYATHON 2026

Google Colab 中 Pandas 使用 dataframe_image 导出图片时如何保持字体?

数据小陈

如何让导出的图片使用指定字体?

导出图片的渲染环境需要能读取目标字体,Pandas Styler 中也要明确设置 font-family。使用浏览器后端时,这两个条件都要满足。

本机安装了字体,或 Colab 中的字体安装命令执行成功,都不能确认导出时使用了该字体。原问题没有提供字体名称、安装命令和导出代码,暂时无法确定具体原因,可以按以下步骤排查。

为什么单元格显示正常,导出后却变了?

Colab 单元格中的 HTML 表格由当前浏览器显示,可以使用本机字体。导出图片时使用的是另一套渲染环境;如果使用浏览器后端,通常会在 Colab 运行环境中启动浏览器。

两边能访问的字体可能不同。安装字体后仍未生效,也可能是 CSS 中的字体族名称不对、样式没有覆盖表头,或指定字体缺少部分字符,触发了字体回退。

dataframe_image 的渲染后端也会影响处理方式。使用 matplotlib 后端时,需要检查 Matplotlib 的字体配置和缓存,不能直接套用浏览器的字体排查方法。

1. 在 Colab 中安装并检查字体

以下示例假设字体文件已上传到 /content/MyFont.ttf,请将路径换成实际路径。示例需要系统提供 Fontconfig;如果找不到 fc-scan 或 fc-cache,可以先在 Colab 单元格中执行:

!apt-get -qq update
!apt-get -qq install -y fontconfig

将字体复制到当前用户的字体目录,刷新缓存,再读取字体文件中的字体族名称:

from pathlib import Path
import shutil
import subprocess

font_source = Path('/content/MyFont.ttf')  # 替换为实际字体路径
if not font_source.is_file():
    raise FileNotFoundError(font_source)

font_dir = Path.home() / '.local/share/fonts'
font_dir.mkdir(parents=True, exist_ok=True)
font_target = font_dir / font_source.name
shutil.copy2(font_source, font_target)

subprocess.run(['fc-cache', '-f'], check=True)

font_family = subprocess.check_output(
    ['fc-scan', '--format', '%{family[0]}', str(font_target)],
    text=True,
).strip()

print('Font family:', font_family)
subprocess.run(
    ['fc-match', '-f', '%{family} | %{file}\n', font_family],
    check=True,
)

CSS 使用字体族名称,它不一定与文件名相同。例如,文件名为 MyFont-Regular.ttf,字体族名称不一定是 MyFont-Regular。

检查 fc-match 输出的字体名称和文件路径。如果匹配到其他字体,说明 Fontconfig 进行了替代匹配,需要检查字体文件、安装目录或字体族名称。fc-match 找到目标字体只是系统层面的检查,还要结合导出结果判断。

2. 在 Styler 中明确指定字体

下面的独立示例沿用上一步得到的 font_family,同时设置表头和数据单元格的字体,方便观察是否一致:

import json
import pandas as pd
import dataframe_image as dfi

# json.dumps 为字体族名称生成带引号的字符串。
font_css = f'{json.dumps(font_family, ensure_ascii=False)}, sans-serif'

# 示例数据,请替换为实际 DataFrame。
df = pd.DataFrame({
    'Item': ['Alpha', 'Beta'],
    'Value': [123, 456],
})

styled = df.style.set_table_styles(
    [
        {
            'selector': 'th, td',
            'props': [('font-family', font_css)],
        }
    ],
    overwrite=False,
)

# 需要当前 dataframe_image 版本支持 chrome 后端,
# 并且运行环境中有它能够找到的 Chrome/Chromium。
dfi.export(styled, 'table.png', table_conversion='chrome')

示例显式选择 chrome 后端,方便在浏览器渲染路径上排查。如果环境提示找不到 Chrome/Chromium,先解决浏览器依赖,再检查字体。

实际使用时,在原有的 Styler 对象上添加字体规则,并将同一个对象传给 dfi.export()。例如,已有 styled 时,执行 styled = styled.set_table_styles(...) 即可,不要为了导出重新创建一个没有字体设置的 df.style。

如果原有样式中也设置了 font-family,需要检查 CSS 优先级,避免新规则被其他规则覆盖。

3. 仍然不生效时检查什么?

  • 安装字体并刷新缓存后,重新启动用于导出的浏览器进程。已经运行的浏览器可能没有重新发现字体。
  • 如果只有中文、符号或少数字符变了,检查目标字体是否包含这些字符。浏览器可以在同一单元格中为不同字符选择不同字体。
  • 如果只有粗体或斜体不一致,检查相应字重和字形是否可用。
  • 如果字体来自网页中的 @font-face,确认导出页面也包含该声明,并且截图前字体已经加载完成。Colab 输出区域里的字体声明不一定会进入导出的 HTML。
  • 如果使用的是 matplotlib 后端,应按该后端的字体配置方式处理;浏览器 CSS 与 Matplotlib 字体设置分别作用于各自的渲染环境。

Colab 运行环境重建后,通常需要重新准备临时上传的字体文件和字体安装。将字体安装步骤放在导出步骤之前,可以减少重新连接后出现字体变化的情况。

备注:内容仅供参考。