slidej

SlideJ — Agent 指南

快速开始

# JSON -> PPTX
slidej generate input.json -o output.pptx
slidej gen input.json -o output.pptx          # alias

# PPTX -> JSON
slidej parse input.pptx -o output.json
slidej parse input.pptx                       # stdout
slidej parse input.pptx --no-images -o out.json

# Templates
slidej template list                          # list all
slidej template info <name>                   # show style guide
slidej template use <name> -o deck.json       # export for editing
slidej template save input.json <name> -d "Description" -t "tag1,tag2"
slidej template remove <name>

# Helpers
slidej schema                                 # print JSON schema
slidej example -o example.json                # demo deck

模板

模板	风格	最适合
title-slide	深色主视觉，居中	标题页、章节分隔页
pitch-deck	专业深色渐变到浅色	路演、提案
report	简洁商务风，表格	报告、仪表盘
minimal	留白，排版	学术、文字密集型
dark-modern	深色 UI，渐变点缀	科技、SaaS 演示
sunset-wave	暖色渐变，有机形态	创意、叙事
candy-pop	白色背景上的大胆波普艺术	活动、营销
ocean-aurora	深邃冷色调，光晕	技术展示、高端
neon-garden	黑底霓虹	创意机构、娱乐

---

JSON 结构

根节点

{
  "width": 13.333,
  "height": 7.5,
  "meta": { "title": "Title", "author": "Author" },
  "theme": {
    "colors": { "accent1": "4472C4", "accent2": "ED7D31" },
    "majorFont": "Calibri Light",
    "minorFont": "Calibri"
  },
  "slides": [...]
}

幻灯片

{
  "background": "1A1A2E",
  "transition": "fade",
  "elements": [...]
}

背景：十六进制字符串 "1A1A2E" 或渐变对象：

{
  "type": "gradient",
  "stops": [
    { "position": 0, "color": "0B0B1F" },
    { "position": 100, "color": "162447" }
  ],
  "angle": 135
}

过渡："fade" | "push" | "wipe" | "split" | "cover" | "cut" | "dissolve" | "random"，或对象 { "type": "fade", "speed": "med", "advanceAfter": 3000 }。

---

元素

所有元素必须包含 position: { x, y, w, h }，单位为英寸。

幻灯片尺寸：宽 13.333" x 高 7.5"。安全边距：每边 0.5"。

规则

• 颜色为不带 # 的裸十六进制值：使用 "FF0000" 而非 "#FF0000"。
• 字号单位为磅。文本不会自动缩放——如果文本溢出，请减小 fontSize 或放大文本框。
• 图片 src 路径相对于 JSON 文件所在目录解析。
• 在任何文本字符串中使用 "\n" 表示换行。

文本

{
  "type": "text",
  "text": "Hello World",
  "position": { "x": 1, "y": 1, "w": 10, "h": 1.5 },
  "fontSize": 36,
  "bold": true,
  "color": "FFFFFF",
  "fontFamily": "Calibri Light",
  "align": "center",
  "vertAlign": "middle"
}

多段落（每一项为独立段落）：

"text": [
  { "text": "Heading", "fontSize": 28, "bold": true, "color": "FFFFFF" },
  { "text": "Subtitle", "fontSize": 16, "color": "AAAAAA" }
]

单段落中的混合样式片段：

"text": [
  {
    "align": "center",
    "runs": [
      { "text": "Bold part ", "bold": true, "color": "FF0000" },
      { "text": "normal part", "color": "333333" }
    ]
  }
]

项目符号列表：

"text": [
  { "text": "First point", "bullet": true },
  { "text": "Second point", "bullet": true }
]

可选：fill、line、shadow、rotation、margin、lineSpacing、italic、underline、strike。

形状

{
  "type": "shape",
  "shapeType": "roundRect",
  "position": { "x": 1, "y": 1, "w": 4, "h": 3 },
  "fill": "4472C4",
  "line": { "color": "333333", "width": 2 },
  "text": "Label",
  "fontSize": 18,
  "color": "FFFFFF",
  "align": "center",
  "vertAlign": "middle"
}

形状类型：rect、roundRect、ellipse、triangle、diamond、pentagon、hexagon、octagon、star5、star6、rightArrow、leftArrow、upArrow、downArrow、line、cloud、heart、lightningBolt、callout1、callout2、chevron、donut、blockArc、arc、pie、plaque、can、parallelogram、trapezoid。

填充可使用渐变：

"fill": {
  "type": "gradient",
  "stops": [
    { "position": 0, "color": "4472C4" },
    { "position": 100, "color": "2E5CA8" }
  ],
  "angle": 135
}

可选：noFill（仅轮廓）、adjust（几何调整）、shadow、rotation。

图片

{
  "type": "image",
  "src": "assets/photo.png",
  "position": { "x": 2, "y": 2, "w": 5, "h": 3 }
}

可选：hyperlink、crop: { left, top, right, bottom }、line、rotation。

表格

{
  "type": "table",
  "position": { "x": 0.5, "y": 2, "w": 12, "h": 4 },
  "headerRow": true,
  "fontSize": 14,
  "rows": [
    ["Column A", "Column B", "Column C"],
    ["Data 1", "100", "OK"]
  ]
}

带样式的单元格：{ "text": "Header", "bold": true, "fill": "4472C4", "color": "FFFFFF", "align": "center" }。

表格不支持动画。

组合

组合将多个元素包裹为一个单元。子元素使用绝对坐标（不相对于组合）。

{
  "type": "group",
  "position": { "x": 0, "y": 0, "w": 8, "h": 8 },
  "rotation": 0,
  "children": [
    { "type": "shape", "shapeType": "ellipse", "position": { "x": 0, "y": 0, "w": 8, "h": 8 }, "fill": "FAFAFA" },
    { "type": "shape", "shapeType": "ellipse", "position": { "x": 3.8, "y": 0, "w": 0.4, "h": 0.4 }, "fill": "FF0000" }
  ],
  "animations": [
    { "type": "fadeIn", "duration": 500, "trigger": "afterPrevious", "order": 0 },
    { "type": "spin", "degrees": 90, "duration": 800, "trigger": "afterPrevious", "order": 1 }
  ]
}

要点：

• 组合上的 rotation 设置初始旋转角度（度）。这是静态基准角度。
• 组合上的动画作用于整个单元——所有子元素一起移动/淡入淡出/旋转。
• 组合 rotation + spin 动画会叠加：你可以在不同幻灯片上设置不同的基准 rotation 并添加相同的 spin，从而营造连续旋转效果（例如 0、72、144... 基准 + 每次 spin 72）。
• 组合内的子元素不能拥有自己的动画——只有组合本身可以播放动画。

---

动画

为任何文本、形状、图片或组合元素添加 "animations": [...]。

"animations": [
  { "type": "fadeIn", "duration": 500, "trigger": "afterPrevious", "delay": 0 }
]

触发器（动画的排序方式）

触发器	行为
onClick	鼠标点击时播放（默认）。开始新的点击组。
withPrevious	与上一个动画同时播放。
afterPrevious	在上一个动画结束后播放。

幻灯片上的第一个 afterPrevious 动画会在进入幻灯片时自动播放——无需点击。这是让内容自动出现的标准方式。

全部动画类型

进入（元素出现）：

类型	必填字段	描述
appear	—	立即出现
fadeIn	—	不透明度 0 -> 100%
flyIn	direction	从某个方向飞入
wipeIn	direction	从某个方向擦除显示
zoomIn	—	从 0% 缩放到 100%
splitIn	—	开门式展开显示
bounceIn	—	带过冲的缩放
floatIn	—	淡入 + 垂直上浮
swivel	—	淡入 + 水平展开
dissolveIn	—	溶解效果

退出（元素消失）：

类型	必填字段	描述
fadeOut	—	不透明度 100% -> 0
flyOut	direction	向某个方向飞出
wipeOut	direction	向某个方向擦除消失
zoomOut	—	从 100% 缩放到 0%
floatOut	—	淡出 + 飘散离开
dissolveOut	—	溶解消失

强调（元素已可见）：

类型	必填字段	描述
pulse	scale（默认 110）	短暂脉冲缩放
spin	degrees（默认 360）	原地旋转
growShrink	scale	放大/缩小
colorChange	color	填充动画过渡到新颜色
transparency	opacity	动画过渡到某不透明度 %
teeter	degrees	左右摇摆
blink	—	快速隐藏/显示

运动：

类型	必填字段	描述
motionPath	points 数组或 path+direction+distance	沿路径移动

方向值（用于 flyIn/Out、wipeIn/Out）

top、bottom、left、right、topLeft、topRight、bottomLeft、bottomRight

---

动画模式

模式 1：交错进入（元素一个接一个出现）

对每个元素使用 afterPrevious 并逐渐增大 delay：

// Element 1 — auto-plays on slide entry (first afterPrevious = auto-play)
{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious" }

// Element 2 — starts after element 1 finishes, plus 200ms pause
{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious", "delay": 200 }

// Element 3 — starts after element 2 finishes, plus 200ms pause
{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious", "delay": 200 }

模式 2：同时进入（多个元素同时出现）

对应当一起出现的元素使用 withPrevious：

// Element 1
{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious" }

// Element 2 — plays at the same time as Element 1
{ "type": "fadeIn", "duration": 500, "trigger": "withPrevious" }

模式 3：幻灯片进入时自动播放序列

全部使用 afterPrevious —— 幻灯片出现时整条链自动播放：

// Title fades in automatically
{ "type": "fadeIn", "duration": 800, "trigger": "afterPrevious" }

// Subtitle fades in after title, with a 300ms gap
{ "type": "fadeIn", "duration": 600, "trigger": "afterPrevious", "delay": 300 }

// Divider line wipes in after subtitle
{ "type": "wipeIn", "direction": "right", "duration": 400, "trigger": "afterPrevious", "delay": 200 }

// Content cards fly in one by one
{ "type": "flyIn", "direction": "bottom", "duration": 600, "trigger": "afterPrevious", "delay": 200 }
{ "type": "flyIn", "direction": "bottom", "duration": 600, "trigger": "afterPrevious", "delay": 200 }

模式 4：单个元素上的多个动画

一个元素可以有多个按顺序播放的动画。使用 order 控制顺序：

"animations": [
  { "type": "fadeIn", "duration": 300, "trigger": "afterPrevious", "order": 0 },
  { "type": "spin", "degrees": 72, "duration": 900, "trigger": "afterPrevious", "order": 1 }
]

模式 5：跨幻灯片旋转轮盘

使用一个带有基础 rotation 的组合，该 rotation 每张幻灯片变化 + 一个 spin 动画：

// Slide 2: rotation 0, spin +72
{ "type": "group", "rotation": 0, "animations": [
    { "type": "fadeIn", "duration": 300, "trigger": "afterPrevious", "order": 0 },
    { "type": "spin", "degrees": 72, "duration": 900, "trigger": "afterPrevious", "order": 1 }
]}

// Slide 3: rotation 72, spin +72
{ "type": "group", "rotation": 72, "animations": [
    { "type": "fadeIn", "duration": 300, "trigger": "afterPrevious", "order": 0 },
    { "type": "spin", "degrees": 72, "duration": 900, "trigger": "afterPrevious", "order": 1 }
]}

// Slide 4: rotation 144, spin +72
{ "type": "group", "rotation": 144, "animations": [...same...] }

每张幻灯片都从上一次结束的位置开始（基础 rotation = 上一次的基础值 + spin 度数）。

模式 6：点击显示（交互式）

对只应在点击时出现的元素使用 onClick：

// Visible immediately
{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious" }

// Appears on first click
{ "type": "fadeIn", "duration": 500, "trigger": "onClick" }

// Appears on second click
{ "type": "flyIn", "direction": "left", "duration": 600, "trigger": "onClick" }

---

布局参考

幻灯片：13.333" x 7.5"。安全区域：x=0.5 到 x=12.833，y=0.5 到 y=7.0。

Y=0.4–0.5    Title area         (h ~ 1.0–1.5)
Y=1.8–2.0    Content start      (h ~ 4.0)
Y=6.0–6.5    Footer / source    (h ~ 0.5)

常用列布局

布局	第 1 列	第 2 列	第 3 列
2 列	x=0.5, w=5.9	x=6.8, w=5.9	—
3 列	x=0.5, w=3.8	x=4.7, w=3.8	x=8.9, w=3.8
4 列	x=0.5, w=2.83	x=3.67, w=2.83	x=6.83, w=2.83

列间距：约 0.4"。

水平居中 N 个元素

公式：给定 itemW、gap 和 N 个元素：

• totalW = N * itemW + (N-1) * gap
• startX = (13.333 - totalW) / 2
• 每个元素：x = startX + i * (itemW + gap)

将元素排列成圆形

对于以 (cx, cy) 为中心、半径为 R 的圆上的 N 个元素，元素尺寸为 s：

• angle_i = i * (360 / N) - 90（从顶部开始）
• x = cx + R * cos(angle_i) - s/2
• y = cy + R * sin(angle_i) - s/2

---

组件（高级）

这些会自动展开为原始组合。使用 position 和可选的 animations。

progressBar

{ "type": "progressBar", "position": { "x": 1, "y": 1, "w": 5, "h": 0.5 },
  "value": 72, "color": "4472C4", "trackColor": "E6E6E6", "showLabel": true }

progressRing

{ "type": "progressRing", "position": { "x": 1, "y": 1, "w": 2, "h": 2 },
  "value": 65, "color": "70AD47", "trackColor": "E6E6E6", "thickness": 0.16, "showLabel": true }

barChart

{ "type": "barChart", "position": { "x": 1, "y": 3, "w": 6, "h": 3 },
  "data": [40, 70, 55, 90], "labels": ["Q1", "Q2", "Q3", "Q4"],
  "colors": ["4472C4", "5B9BD5", "70AD47", "ED7D31"], "showValues": true, "axis": true }

kpiCard

{ "type": "kpiCard", "position": { "x": 1, "y": 1, "w": 3, "h": 1.5 },
  "value": "$1.2M", "label": "Revenue", "delta": "+12%", "accent": "5B9BD5" }

ratingStars

{ "type": "ratingStars", "position": { "x": 1, "y": 1, "w": 4, "h": 0.9 },
  "rating": 4, "max": 5, "color": "FFC000", "emptyColor": "D9D9D9" }

timeline

{ "type": "timeline", "position": { "x": 1, "y": 1.5, "w": 11, "h": 2 },
  "items": [{ "label": "2021", "sub": "Founded" }, { "label": "2022", "sub": "Seed" }],
  "dotColor": "4472C4", "lineColor": "CCCCCC" }

processFlow

{ "type": "processFlow", "position": { "x": 1, "y": 5, "w": 6, "h": 0.8 },
  "steps": ["Plan", "Build", "Test", "Ship"],
  "colors": ["4472C4", "5B9BD5", "70AD47", "ED7D31"], "shape": "chevron" }

---

完整示例：标题幻灯片 + 内容幻灯片

{
  "width": 13.333, "height": 7.5,
  "meta": { "title": "Demo", "author": "Agent" },
  "theme": {
    "colors": { "accent1": "4472C4", "accent2": "ED7D31" },
    "majorFont": "Calibri Light", "minorFont": "Calibri"
  },
  "slides": [
    {
      "background": { "type": "gradient", "stops": [{ "position": 0, "color": "0B0B1F" }, { "position": 100, "color": "162447" }], "angle": 135 },
      "transition": "fade",
      "elements": [
        {
          "type": "text", "text": "Presentation Title",
          "position": { "x": 0.8, "y": 2.5, "w": 11.7, "h": 1.2 },
          "fontSize": 48, "bold": true, "color": "FFFFFF", "align": "center", "fontFamily": "Calibri Light",
          "animations": [{ "type": "fadeIn", "duration": 800, "trigger": "afterPrevious" }]
        },
        {
          "type": "text", "text": "Subtitle goes here",
          "position": { "x": 2, "y": 3.8, "w": 9.3, "h": 0.6 },
          "fontSize": 20, "color": "8899BB", "align": "center", "fontFamily": "Calibri Light",
          "animations": [{ "type": "fadeIn", "duration": 600, "trigger": "afterPrevious", "delay": 300 }]
        },
        {
          "type": "shape", "shapeType": "rect",
          "position": { "x": 4.3, "y": 4.6, "w": 4.7, "h": 0.022 },
          "fill": "4472C4",
          "animations": [{ "type": "wipeIn", "direction": "right", "duration": 500, "trigger": "afterPrevious", "delay": 200 }]
        }
      ]
    },
    {
      "background": "FFFFFF",
      "transition": "fade",
      "elements": [
        {
          "type": "text", "text": "Section Title",
          "position": { "x": 0.5, "y": 0.4, "w": 12.3, "h": 1 },
          "fontSize": 36, "bold": true, "color": "2D3436", "align": "center",
          "animations": [{ "type": "fadeIn", "duration": 500, "trigger": "afterPrevious" }]
        },
        {
          "type": "shape", "shapeType": "roundRect",
          "position": { "x": 0.5, "y": 1.8, "w": 3.8, "h": 2.5 },
          "fill": "4472C4",
          "text": [
            { "text": "Card 1", "fontSize": 20, "bold": true, "color": "FFFFFF" },
            { "text": "Description here", "fontSize": 14, "color": "CCDDFF" }
          ],
          "align": "center", "vertAlign": "middle",
          "animations": [{ "type": "flyIn", "direction": "bottom", "duration": 600, "trigger": "afterPrevious", "delay": 200 }]
        },
        {
          "type": "shape", "shapeType": "roundRect",
          "position": { "x": 4.7, "y": 1.8, "w": 3.8, "h": 2.5 },
          "fill": "ED7D31",
          "text": [
            { "text": "Card 2", "fontSize": 20, "bold": true, "color": "FFFFFF" },
            { "text": "More details", "fontSize": 14, "color": "FFE0C0" }
          ],
          "align": "center", "vertAlign": "middle",
          "animations": [{ "type": "flyIn", "direction": "bottom", "duration": 600, "trigger": "afterPrevious", "delay": 200 }]
        },
        {
          "type": "shape", "shapeType": "roundRect",
          "position": { "x": 8.9, "y": 1.8, "w": 3.8, "h": 2.5 },
          "fill": "70AD47",
          "text": [
            { "text": "Card 3", "fontSize": 20, "bold": true, "color": "FFFFFF" },
            { "text": "Third point", "fontSize": 14, "color": "D4EFCC" }
          ],
          "align": "center", "vertAlign": "middle",
          "animations": [{ "type": "flyIn", "direction": "bottom", "duration": 600, "trigger": "afterPrevious", "delay": 200 }]
        }
      ]
    }
  ]
}

---

工作流：修改现有 PPTX

slidej parse original.pptx --no-images -o deck.json   # Step 1: parse
# Edit deck.json (remove `id`, `name`, `srcBase64` fields if present)
slidej generate deck.json -o updated.pptx              # Step 2: regenerate

工作流：从模板创建

slidej template list                                   # browse
slidej template info pitch-deck                        # see style guide
slidej template use pitch-deck -o deck.json            # export
# Edit deck.json
slidej generate deck.json -o presentation.pptx         # generate