# web-to-pixso → PPT 映射分析

## 1. JSON 结构总览

### 顶层字段
| 字段 | 说明 |
|------|------|
| `canvas` | 画布尺寸 `{width, height, x, y, backgroundColor}` |
| `nodes` | 根节点树（type=FRAME, name=html） |
| `assets` | 图片资源 `{key: base64}` |
| `fonts` | 字体列表 |
| `schemaVersion` | JSON 版本号 |

### 节点类型
| 类型 | 数量 | 说明 |
|------|------|------|
| FRAME | 471 | HTML 容器（div, section, table, header 等） |
| TEXT | 393 | 文字节点 |
| RECTANGLE | 10 | 截图底图（comparison layer，用于视觉对比） |

### 节点属性
```
type          - FRAME/TEXT/RECTANGLE
rect          - {x, y, width, height} 像素坐标
styles        - 57个CSS属性（见下表）
name          - HTML元素名或文字内容
tag           - HTML标签名（HTML/DIV/TABLE/TR/TD/SPAN/#text等）
text / src    - 文字内容（TEXT节点用text，收集时映射为src）
layerGroup    - editable/text/comparison
backgroundImages - 图片资源引用数组
clipRect      - 裁剪区域
visibleRect   - 可见区域
clipped       - 是否被裁剪
id            - 节点ID
section       - document
visualRole    - layout-wrapper/text-node/raster-fallback
```

## 2. 57个 styles 字段分类

### 已处理（15个）
| 字段 | 用途 | 当前处理方式 |
|------|------|-------------|
| backgroundColor | 背景色 | → shape fill |
| backgroundImage | 渐变背景 | → 提取起始色做纯色 fill |
| borderTopWidth/Color/Style | 顶部边框 | → shape line（四边都有时）或单独线条 |
| borderBottomWidth/Color/Style | 底部边框 | 同上 |
| borderLeftWidth/Color/Style | 左边框 | 同上 |
| borderRightWidth/Color/Style | 右边框 | 同上 |
| borderTopLeftRadius | 圆角 | → rectRadius |
| boxShadow | 阴影 | → shadow |
| fontSize | 字号 | → fontSize（pt） |
| fontFamily | 字体 | → fontFace |
| color | 文字颜色 | → color |
| fontWeight | 粗体 | → bold |
| fontStyle | 斜体 | → italic |
| textAlign | 对齐 | → align |

### 未处理（42个）
| 字段 | 重要性 | 说明 |
|------|--------|------|
| **opacity** | 高 | 元素透明度，PPT支持 `opacity` |
| **lineHeight** | 高 | 行高，影响文字换行和间距 |
| **letterSpacing** | 中 | 字间距，PPT支持 `charSpacing` |
| **textDecorationLine** | 中 | 下划线/删除线 |
| **textTransform** | 低 | 大小写转换 |
| **whiteSpace** | 高 | 控制换行行为（nowrap等） |
| **wordBreak** | 中 | 断词规则 |
| **visibility** | 中 | visible/hidden |
| **display** | 中 | none时不渲染 |
| **transform** | 中 | 旋转/缩放/位移 |
| **transformOrigin** | 低 | 变换原点 |
| **zIndex** | 高 | 层级顺序 |
| **overflow** | 中 | 溢出处理 |
| **clipPath** | 低 | 裁剪路径 |
| **filter** | 低 | CSS滤镜 |
| **borderTopRightRadius** | 中 | 右上圆角（目前只用左上） |
| **borderBottomLeftRadius** | 中 | 左下圆角 |
| **borderBottomRightRadius** | 中 | 右下圆角 |
| **backgroundPosition** | 低 | 背景定位 |
| **backgroundSize** | 低 | 背景尺寸 |
| **backgroundRepeat** | 低 | 背景重复 |
| **backgroundClip** | 低 | 背景裁剪 |
| **backgroundOrigin** | 低 | 背景原点 |
| **position** | 低 | 定位方式 |
| **objectFit** | 低 | 图片适配 |
| **objectPosition** | 低 | 图片定位 |
| **maskImage/MaskPosition/MaskSize** | 低 | 遮罩 |
| **webkitMaskImage/MaskPosition/MaskSize** | 低 | 遮罩（webkit） |
| **backdropFilter** | 低 | 背景滤镜 |

## 3. 映射优先级

### P0（必须处理）
1. **opacity** → shape/text 的 opacity 属性
2. **whiteSpace** → 控制文字是否换行
3. **zIndex** → 调整 objects 数组顺序（后渲染在上层）
4. **lineHeight** → 文字行高（paraSpaceBefore/after 或 lineSpacingMultiple）

### P1（应该处理）
5. **letterSpacing** → charSpacing（字符间距）
6. **textDecorationLine** → underline/strike
7. **display:none** → 跳过该节点
8. **visibility:hidden** → 跳过该节点
9. **四个圆角独立处理** → 当前只用了 borderTopLeftRadius

### P2（可以处理）
10. **transform** → rotate 属性
11. **wordBreak** → 辅助判断换行
12. **overflow** → 辅助判断裁剪
13. **filter** → 特殊效果（大部分PPT不支持）

## 4. 当前代码架构

```
HTML → web-to-pixso 插件 → JSON
                              ↓
                        convert-w2p.js（提取+映射）
                              ↓
                        Schema JSON
                              ↓
                        pptxgenjs（渲染）
                              ↓
                        .pptx 文件
```

### convert-w2p.js 处理流程
1. findSlides() — 找 page/slide-N 容器
2. collectSlideChildren() — 递归提取子节点（保留层级）
3. collectOrphans() — 收集游离节点归入最近 slide
4. 排序：FRAME 在前，TEXT 在后
5. 映射循环：遍历每个子节点
   - TEXT → text 对象（含字号/字体/颜色/粗体/对齐）
   - IMAGE → image 对象
   - FRAME with bg → shape 对象（含 fill/border/shadow/rectRadius）
   - 四边 border → 独立线条 shape
6. 输出 Schema JSON + 调用 pptxgenjs 生成 PPTX

## 5. 下一步行动

### 短期（本次迭代）
- [ ] 实现 P0：opacity、whiteSpace、zIndex、lineHeight
- [ ] 实现 P1：letterSpacing、textDecoration、display/visibility 过滤

### 中期
- [ ] 建立 web-to-pixso JSON 的完整字段文档
- [ ] 验证不同 HTML 结构的 JSON 输出一致性
- [ ] 处理 transform（旋转）

### 长期
- [ ] 参考设计稿，实现高度还原的 PPT 输出
- [ ] 处理复杂布局（grid/flex 嵌套）