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 运行环境重建后,通常需要重新准备临时上传的字体文件和字体安装。将字体安装步骤放在导出步骤之前,可以减少重新连接后出现字体变化的情况。
备注:内容仅供参考。
