convez.ai
Skill
cocohahaha

pptx-editable-charts

cocohahaha/pptx-editable-charts

Ver no GitHub
InicialPluginScore · de 0 a 100

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-charts

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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/:

开发

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

Ver o original no GitHub

Bom para

Relacionados