# PPTX Programming - Python-pptx 编程生成PPT技能

## 📋 元数据

- **Skill 名称**: pptx-programming
- **版本**: 1.0.0
- **描述**: 使用 python-pptx 库编程生成专业PPT，支持4:3投影仪适配、布局一致性、垂直居中、装饰元素等高级功能
- **作者**: 小小莫
- **标签**: ppt, python-pptx, presentation, programming, layout, design
- **触发词**: python生成PPT、编程做PPT、python-pptx、专业PPT设计、4:3投影仪PPT

## ✨ 功能特性

### 核心功能
- 🎯 **4:3投影仪适配** - 专为投影仪设计的10x7.5英寸比例
- 📐 **布局一致性** - 并列元素等宽等高、等间距、同字体
- 🎨 **专业设计原则** - 六大设计原则自动实现
- 🖼️ **装饰元素** - 音乐符号、边框、渐变背景等
- 📊 **垂直居中** - 标签文字自动垂直居中
- 🔍 **溢出检查** - 自动检查并修复边界溢出

### 设计原则实现
1. **并列关系一致性** - 同一行标签/卡片统一样式
2. **独立元素不重叠** - 逻辑独立元素绝对不重叠
3. **标签文字垂直居中** - `vertical_anchor = MSO_ANCHOR.MIDDLE`
4. **溢出彻底解决** - 必须100%无溢出
5. **视觉层次清晰** - 标题>副标题>正文>说明文字
6. **4:3投影仪适配** - 10x7.5英寸，四周0.5英寸安全边距

## 🚀 快速开始

### 基础设置
```python
from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
from pptx.dml.color import RGBColor

# 4:3投影仪比例
prs = Presentation()
prs.slide_width = Inches(10)    # 10英寸宽
prs.slide_height = Inches(7.5)  # 7.5英寸高
```

### 配色方案（钢琴主题）
```python
DARK_BLUE = RGBColor(26, 26, 46)      # 深蓝背景
GOLD = RGBColor(212, 175, 55)         # 金色装饰
ROSE = RGBColor(183, 110, 121)        # 玫瑰金高亮
LIGHT = RGBColor(248, 245, 240)       # 浅米背景
WHITE = RGBColor(255, 255, 255)       # 白色文字
GRAY = RGBColor(85, 85, 85)           # 灰色说明
```

## 📖 核心功能详解

### 1. 标签垂直居中实现
```python
def create_centered_tag(slide, x, y, width, height, text):
    """创建垂直居中的标签"""
    tag = slide.shapes.add_textbox(Inches(x), Inches(y), Inches(width), Inches(height))
    tf = tag.text_frame
    tf.word_wrap = True
    tf.vertical_anchor = MSO_ANCHOR.MIDDLE  # 关键：垂直居中
    
    p = tf.paragraphs[0]
    p.text = text
    p.font.size = Pt(9)
    p.alignment = PP_ALIGN.CENTER  # 水平居中
    return tag
```

### 2. 并列标签等宽布局
```python
def create_equal_width_tags(slide, start_x, start_y, total_width, tags, height=0.3):
    """创建等宽并列标签"""
    tag_width = total_width / len(tags) - 0.15  # 每个标签宽度，留出间距
    
    for i, tag_text in enumerate(tags):
        x = start_x + i * (tag_width + 0.15)  # 等间距分布
        create_centered_tag(slide, x, start_y, tag_width, height, tag_text)
```

### 3. 装饰元素
```python
def add_musical_note(slide, x, y, size=0.3):
    """添加音乐符号装饰"""
    from pptx.enum.shapes import MSO_SHAPE
    
    # 音符头
    head = slide.shapes.add_shape(
        MSO_SHAPE.OVAL, Inches(x), Inches(y), Inches(size), Inches(size)
    )
    head.fill.solid()
    head.fill.fore_color.rgb = GOLD
    head.line.color.rgb = GOLD
    
    # 音符杆
    stem = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x + size * 0.4),
        Inches(y - size * 0.8),
        Inches(size * 0.2),
        Inches(size * 1.2),
    )
    stem.fill.solid()
    stem.fill.fore_color.rgb = GOLD
    stem.line.color.rgb = GOLD
```

### 4. 检查脚本
```python
def check_ppt_layout(ppt_path):
    """检查PPT布局问题"""
    prs = Presentation(ppt_path)
    slide_width = prs.slide_width
    slide_height = prs.slide_height
    
    issues = []
    for slide_idx, slide in enumerate(prs.slides):
        for shape in slide.shapes:
            if not hasattr(shape, 'has_text_frame') or not shape.has_text_frame:
                continue
                
            left = getattr(shape, 'left', 0)
            top = getattr(shape, 'top', 0)
            width = getattr(shape, 'width', 0)
            height = getattr(shape, 'height', 0)
            
            right = left + width
            bottom = top + height
            
            # 检查边界溢出
            if right > slide_width:
                overflow = (right - slide_width) / Inches(1)
                issues.append(f"幻灯片{slide_idx+1}: 右侧溢出 {overflow:.2f}英寸")
            
            if bottom > slide_height:
                overflow = (bottom - slide_height) / Inches(1)
                issues.append(f"幻灯片{slide_idx+1}: 底部溢出 {overflow:.2f}英寸")
    
    return issues
```

## 📁 项目结构

```
projects/青年钢琴集体课/01-课程设计/ppt/
├── 最终成果/体验课PPT_专业版.pptx          # 最终成果
├── 源码/
│   ├── create-ppt-v3.py              # 主生成脚本（574行完整实现）
│   ├── simple-check.py               # 简单检查脚本
│   └── check-ppt-layout.py           # 详细布局检查
└── 归档版本/                          # 7个中间版本
```

## 🎯 使用场景

### 1. 专业演示文稿
- 企业培训PPT
- 教育课程PPT
- 产品介绍PPT
- 会议演示PPT

### 2. 特定需求
- 4:3投影仪适配
- 品牌一致性设计
- 批量生成PPT
- 自动化PPT报告

### 3. 设计约束
- 必须遵循六大设计原则
- 必须彻底解决溢出问题
- 必须保持布局一致性
- 必须适配目标显示设备

## ⚠️ 注意事项

### 常见错误
- ❌ 并列标签样式不一致
- ❌ 独立元素重叠
- ❌ 标签文字不垂直居中
- ❌ 溢出问题"大为改善"但不彻底
- ❌ 4:3内容直接转为16:9

### 最佳实践
- ✅ 先定义设计原则，再写代码
- ✅ 使用函数封装重复逻辑
- ✅ 运行检查脚本验证布局
- ✅ 保存中间版本便于调试
- ✅ 记录设计决策和原则

## 🔗 相关技能

- **file-reader** - 文档读写编辑（包含PPT基础操作）
- **pptx-programming** - 本技能，编程生成专业PPT

## 📚 参考框架

本技能可使用以下通用框架加速开发：

### PPTGenerator 框架
位置: `.opencode/skills/ppt-generator/scripts/`

```python
# 使用通用框架
from ppt_generator import PPTGenerator, PianoCourseTemplate

# 方式1：使用模板
template = PianoCourseTemplate()
template.generate(
    title="课程标题",
    teacher={"name": "讲师", "title": "职位"},
    output_path="课程.pptx"
)

# 方式2：使用基础API
gen = PPTGenerator()
gen.use_theme("professional_blue")
gen.enable_wps_compatibility()
slide = gen.add_slide(layout="blank")
slide.add_title("标题")
slide.add_textbox("内容")
gen.save("output.pptx")
```

### 核心功能
- 主题系统 (professional_blue, warm_gold, modern_minimal)
- 样式常量 (title_large, body_medium等)
- WPS兼容性支持
- 装饰边框、音乐符号
- 卡片容器布局

### 模板系统
- PianoCourseTemplate - 钢琴课程模板
- BusinessReportTemplate - 企业报告模板
- EducationCourseTemplate - 教育课程模板

## 📄 许可证

MIT License

---

**创建时间**: 2025-02-23  
**基于项目**: 钢琴演奏入门班体验课PPT  
**目标受众**: 25-40岁女性（75%+）  
**设计风格**: 优雅音乐主题，专业简洁