pptx-editable-charts
cocohahaha/pptx-editable-charts
Editable data charts for AI-generated PowerPoint: native OOXML charts (double-click to edit), table heatmaps, layered editable SVG. Theme-token driven, Looker Studio aesthetics. Python lib + CLI + Claude Skill. 让 AI 生成的 PPT 图表真正可编辑
Instalação
npx convez-ai cocohahaha/pptx-editable-charts1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
pptx-editable-charts
让 AI 生成的 PPT 数据图表真正可编辑。 原生 OOXML 图表(PowerPoint 里双击就能改数据)+ 表格热力图 + 分层可编辑 SVG,全部走设计系统主题 Token,开箱即用的 Python 库 + CLI + Claude Skill。
Editable data charts for AI-generated PowerPoint decks: native OOXML charts (double-click to edit data), table-based heatmaps, and layered SVG that survives import into Figma / Illustrator / PowerPoint shape conversion. Theme-token driven, Looker Studio aesthetics by default.
pip install git+https://github.com/cocohahaha/pptx-editable-charts.git
pptchart demo --out demo.pptx # 6 种图表的演示 deck,每一张都可编辑
为什么你的 AI 生成图表「分层错乱、无法编辑」
AI 驱动的 PPT 生成方案(包括各类 Design Skill)处理数据图表时,常见三条实现路径,各有典型的失败模式:
| 实现路径 | 表现 | 根因 |
|---|---|---|
| (a) 渲染成图片插入(ECharts/matplotlib/HTML 截图 → PNG) | 完全不可编辑,改一个数字要重新生成 | 图片没有数据层。PowerPoint 眼里它就是一张位图 |
| (b) 用自由形状拼图表(几十个矩形、线条、文本框堆出"柱状图") | 分层(z-order)错乱、组合关系破碎、无法整体选中缩放、文字和形状漂移 | 形状没有图表语义。每个元素独立排 z 序,AI 很难一次摆对,后续编辑必乱 |
| (c) 直接写图表 XML 但部件不全 | PowerPoint 打开报修复提示,修复后图表丢失("做不出来") | 原生图表是一组部件:chart XML + 关系文件 + 嵌入式 Excel 工作簿,缺一不可 |
(b) 正是「分层有问题」的典型成因,(c) 是「干脆做不出来」的成因。
一个合法的原生图表在 .pptx 包里长这样:
ppt/charts/chart1.xml ← 图表定义(类型/系列/轴/样式)
ppt/charts/_rels/chart1.xml.rels ← 指向嵌入工作簿的关系
ppt/embeddings/Microsoft_Excel_Sheet1.xlsx ← 真正的 Excel 数据(双击编辑的来源)
[Content_Types].xml ← 为以上每个部件声明类型
PowerPoint 里双击图表弹出的数据表,就是那个嵌入的 xlsx。有这套部件,图表"天生可编辑";没有,怎么补救都不行。
各种插入方式的可编辑性对比
| 插入方式 | 改数据 | 改样式 | 整体缩放 | 套品牌主题 | 出错风险 |
|---|---|---|---|---|---|
| 原生 chart part(本库) | ✅ 双击改 | ✅ 全部 PPT 原生操作 | ✅ | ✅ | 低(python-pptx 保证部件完整) |
| 原生表格(本库热力图) | ✅ 改单元格 | ✅ 填充/字体全可改 | ✅ | ✅ | 低 |
| SVG 图片(本库图片输出) | ⚠️ 转形状后改文字 | ✅ 转形状后全可改 | ✅ 矢量无损 | ✅ | 低 |
| 形状堆叠 | ❌ 逐个改 | ⚠️ 极易错位 | ❌ 分层漂移 | ⚠️ | 高(分层错乱) |
| EMF/WMF | ❌ | ⚠️ 取消组合有损 | ✅ | ❌ | 中 |
| PNG/JPG | ❌ | ❌ | ⚠️ 模糊 | ❌ | 低但死路 |
结论:数据图表用原生 chart part,热力图用原生表格(PowerPoint 没有原生热力图类型),需要图片时用 SVG——这是同时满足「可编辑 + 不出错」的唯一组合。
支持的图表类型
| 类型 | type 值 | PPTX(原生可编辑) | SVG(分层可编辑) |
|---|---|---|---|
| 柱状图 | column / column_stacked | ✅ | ✅ |
| 条形图 | bar / bar_stacked | ✅ | ✅ |
| 折线图 | line / line_markers | ✅ | ✅ |
| 面积图 | area / area_stacked | ✅ | ✅(非堆叠) |
| 饼图/环形图 | pie / doughnut | ✅ | ➖ 用原生图表 |
| 热力图 | heatmap | ✅ 原生表格+色阶 | ✅ |
默认视觉规范参考 Google Looker Studio(前 Data Studio):Google 色板、浅灰横向网格线、无刻度线、顶部图例、Roboto 字体。全部可通过主题 Token 覆盖。
快速开始
CLI
# 从 spec JSON 生成可编辑图表 deck(可叠加品牌母版)
pptchart pptx --data charts.json --out report.pptx --theme themes/brand.json
pptchart pptx --data charts.json --out report.pptx --template 公司模板.pptx
# 单图输出可编辑 SVG(Figma / Illustrator / PPT 转形状)
pptchart svg --data chart.json --out chart.svg --size 960x540
# 全类型演示
pptchart demo --out demo.pptx --svg-dir svg-out/
spec JSON 格式
{
"type": "column",
"title": "季度营收对比",
"categories": ["Q1", "Q2", "Q3", "Q4"],
"series": [
{ "name": "2024", "values": [320, 410, 380, 520] },
{ "name": "2025", "values": [380, 470, 460, 610] }
],
"number_format": "#,##0",
"show_data_labels": false
}
热力图用矩阵形:
{
"type": "heatmap",
"title": "一周访问热力分布",
"rows": ["周一", "周二"],
"cols": ["上午", "下午", "晚上"],
"values": [[12, 320, 220], [10, 335, 210]]
}
--data 接受单个 spec 或 spec 数组(每个 spec 一页)。
Python API(嵌入你自己的生成流程)
from pptx import Presentation
from pptx.util import Inches
from pptchart import Theme, spec_from_dict, add_native_chart, add_heatmap
theme = Theme.load("themes/brand.json")
prs = Presentation("公司模板.pptx") # 直接在品牌母版上工作
slide = prs.slides.add_slide(prs.slide_layouts[6])
spec = spec_from_dict({...}) # 上面的 JSON 结构
add_native_chart(slide, spec, Inches(0.6), Inches(1.2), Inches(9), Inches(5), theme)
# 热力图: add_heatmap(slide, matrix_spec, x, y, cx, cy, theme)
prs.save("out.pptx")
主题系统:接入你的 Design System
主题是一个扁平 JSON Token 文件,只写需要覆盖的字段,其余回退到 Looker 风格默认值:
{
"font": { "family": "PingFang SC", "fallback": "Microsoft YaHei" },
"palette": ["#2A8A7A", "#E8B878", "#4A6FA5"],
"text": { "title": "#1A2B28", "axis": "#6B7C78" },
"gridline": { "color": "#E6ECEA" },
"heatmap": { "ramp": ["#FFFFFF", "#2A8A7A"] }
}
完整 Token 清单见 pptchart/theme.py 的 DEFAULTS,品牌接入模板见 themes/brand-template.json。把你 Design System 的色板/字体/灰阶填进去即可,所有图表类型(含热力图色阶和文字对比度自动切换)都会跟随。
作为 Claude Skill 使用
本仓库自带 SKILL.md,可直接作为 Claude Code skill 安装:
git clone https://github.com/cocohahaha/pptx-editable-charts.git ~/.claude/skills/pptx-editable-charts
如何与你已有的公司 Design Skill 协作(推荐做法、Token 映射、母版继承),见 docs/integration-guide.md。
SVG 的可编辑性保证
SVG 输出严格遵守一组经过调研验证的兼容规则(详见 docs/research/svg-editability-rules.md):
- 文字全部是真实
<text>元素(不转轮廓、无 tspan),带字体回退栈; - 样式全部内联 presentation attributes——无
<style>、class、defs、filter、foreignObject; width/height/viewBox数值一致,避免 Figma 重算缩放;- 分层
<g id="...">(background / gridlines / axes / series-N / value-labels / axis-labels / title / legend),Figma 和 Illustrator 直接显示为图层名; - 每个数据元素一个独立形状(每根柱一个
<rect>),PowerPoint「取消组合」两次转为原生形状后可逐个编辑。
PowerPoint 插入 SVG 转形状需要 Microsoft 365(2020-05 之后的 build)。Figma 对 SVG 文本的保留有已知限制(可能拆成矢量),Illustrator 和 PowerPoint 在字体已安装时文字保持可编辑。
已知边界
- PowerPoint 表格行高是最小值语义:热力图行数很多时请配合较小的
heatmap.value_size,否则文字会把行撑高。 - 横向条形图(
bar/bar_stacked)的数据在嵌入工作簿里是倒序存储的——PowerPoint 自下而上绘制类目,倒序后第一个类目显示在最上方(符合阅读顺序,也与 SVG 输出一致)。双击编辑数据时看到倒序属预期。 - 原生图表的标题/图例等位置由 PowerPoint 排版(这正是可编辑性的来源),不像图片那样像素级可控。
pie/doughnut不提供 SVG 输出(PPT 原生图表已覆盖该场景)。- 复杂组合图(双轴柱线混合)暂不支持,欢迎 PR。
研究档案
本仓库的所有关键技术决策都有实证依据,原始研究报告在 docs/research/:
- python-pptx 原生图表 30 项 API 探针(随库附带,升级 python-pptx 后可重跑验证)
- 表格热力图 9 项实证验证(含 OOXML schema 顺序陷阱)
- SVG 可编辑性规则调研(Figma/Illustrator/Office 三方兼容矩阵)
开发
python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest # 52 项测试
.venv/bin/python tools/probe_native_charts.py # 30 项 API 探针
License
MIT