lanyuanxiaoyao
cd7988cbd5
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
3.8 KiB
3.8 KiB
1. 准备工作
- 1.1 在
yaml2pptx.py的 Inline script metadata 中添加flask和watchdog依赖 - 1.2 在文件顶部添加预览模式相关的导入语句（使用条件导入，仅在预览模式下导入）
2. 命令行参数
- 2.1 在
parse_args()函数中添加--preview参数（布尔类型，默认 False） - 2.2 在
parse_args()函数中添加--port参数（整数类型，默认 5000）
3. HTML 渲染函数
- 3.1 实现
render_text_element_to_html(elem)函数，将文本元素转换为 HTML<div>标签 - 3.2 实现
render_shape_element_to_html(elem)函数，将形状元素转换为 HTML<div>标签 - 3.3 实现
render_table_element_to_html(elem)函数，将表格元素转换为 HTML<table>标签 - 3.4 实现
render_image_element_to_html(elem, base_path)函数，将图片元素转换为 HTML<img>标签 - 3.5 实现
render_slide_to_html(slide_data, index)函数，渲染单个幻灯片为 HTML - 3.6 实现
generate_preview_html(yaml_file, template_dir)函数，生成完整的预览 HTML 页面
4. HTML 模板
- 4.1 定义
HTML_TEMPLATE常量，包含完整的 HTML 页面结构、CSS 样式和 SSE 客户端 JavaScript - 4.2 定义
ERROR_TEMPLATE常量，用于显示 YAML 解析错误
5. Flask 应用
- 5.1 创建 Flask 应用实例
app = Flask(__name__) - 5.2 实现主页面路由
@app.route('/')，返回预览 HTML - 5.3 实现 SSE 事件流路由
@app.route('/events')，推送文件变化通知
6. 文件监听
- 6.1 实现
YAMLChangeHandler类，继承FileSystemEventHandler - 6.2 在
on_modified()方法中检测.yaml文件变化，推送更新通知到队列 - 6.3 创建全局队列
change_queue = queue.Queue()用于通知文件变化
7. 预览服务器启动
- 7.1 实现
start_preview_server(yaml_file, template_dir, port)函数 - 7.2 在函数中启动 watchdog 监听器，监听 YAML 文件所在目录
- 7.3 在函数中使用
webbrowser.open()自动打开浏览器 - 7.4 在函数中启动 Flask 应用，监听指定端口
- 7.5 添加 Ctrl+C 信号处理，优雅退出服务器
8. 主函数修改
- 8.1 在
main()函数中添加条件判断：if args.preview: - 8.2 在预览模式分支中调用
start_preview_server() - 8.3 在非预览模式分支中保持原有的 PPTX 生成逻辑
9. 错误处理
- 9.1 在预览 HTML 生成中捕获
YAMLError，返回错误页面 - 9.2 在 Flask 路由中添加异常处理，避免服务器崩溃
- 9.3 在端口占用时捕获异常，提示用户使用
--port参数
10. 日志输出
- 10.1 在预览服务器启动时输出日志：监听的文件路径、预览 URL、停止方法
- 10.2 在文件变化时输出日志：
[INFO] 检测到文件变化: <文件路径> - 10.3 在服务器停止时输出日志：
[INFO] 已停止
11. 测试
- 11.1 测试基本功能：启动预览服务器，浏览器自动打开
- 11.2 测试文件监听：修改 YAML 文件，浏览器自动刷新
- 11.3 测试模板支持：使用模板的 YAML 文件能正确预览
- 11.4 测试错误处理：YAML 语法错误时显示错误页面
- 11.5 测试所有元素类型：文本、形状、表格、图片都能正确渲染
- 11.6 测试多幻灯片：多个幻灯片垂直排列显示
- 11.7 测试向后兼容：不使用
--preview参数时，PPTX 生成功能正常 - 11.8 测试自定义端口：
--port参数能正确指定端口 - 11.9 测试 Ctrl+C 退出：能优雅停止服务器
12. 文档更新
- 12.1 在 README.md 中添加预览功能的使用说明
- 12.2 在 README.md 中添加预览功能的示例命令
- 12.3 在 README.md 中说明预览效果与 PPTX 可能存在差异