PPTX/openspec/changes/archive/2026-03-02-add-text-auto-wrap/design.md

Design: 文本框默认自动换行

Context

当前 yaml2pptx.py 中的 add_text_element() 函数创建 PPTX 文本框时，未设置 word_wrap 属性。python-pptx 的 TextFrame 默认行为是 word_wrap = False，这意味着长文本会溢出文本框边界。同样，HTML 预览中的 render_text_element_to_html() 函数使用 white-space: pre-wrap，这会保留所有空格和换行符，但对于自动换行的处理不够理想。

Current State:

• PPTX 生成：tf.word_wrap 未设置，默认为 False，长文本会溢出
• HTML 预览：使用 white-space: pre-wrap，保留格式但不确保自动换行

Constraints:

• 必须保持向后兼容性（此改进不会破坏现有功能）
• PPTX 和 HTML 预览行为应该一致
• 不能引入新的外部依赖

Goals / Non-Goals

Goals:

• 文本框默认启用文字自动换行
• 同步更新 PPTX 生成和 HTML 预览的行为
• 用户无需修改任何 YAML 配置

Non-Goals:

• 添加 YAML wrap 属性（不需要，直接默认启用）
• 文本框大小自动调整
• 文字大小自动缩放以适应文本框

Decisions

1. 直接默认启用自动换行，无需配置

Decision: 不添加任何 YAML 属性，直接在代码中设置 word_wrap = True

Rationale:

• 自动换行是文本框的合理默认行为
• 用户无需学习新的配置选项
• 简化代码，减少配置复杂度
• 符合大多数演示文稿软件的默认行为

Alternatives Considered:

• 添加 wrap 属性：增加配置复杂度，大部分用户都会希望自动换行

2. PPTX 实现方式

Decision: 在创建文本框后直接设置 text_frame.word_wrap = True

Rationale:

• python-pptx 原生支持此功能，无需额外依赖
• 代码改动最小，只需添加一行
• 性能开销为零

Code Location: yaml2pptx.py 第 406 行附近，在 textbox.text_frame 赋值后添加：

tf.word_wrap = True

3. HTML 预览实现方式

Decision: 将 CSS white-space: pre-wrap 改为 white-space: normal

Rationale:

• normal 是 CSS 默认值，允许文字在容器边界处自动换行
• 与 PPTX 的 word_wrap = True 行为一致
• 对于包含 \n 的内容，可以单独处理或在需要时使用 pre-wrap

Code Location: yaml2pptx.py 第 902 行，修改 render_text_element_to_html() 函数中的样式

Risks / Trade-offs

Risk 1: 包含手动换行符的文本

Risk: 如果用户在 YAML 中使用 \n 手动换行，white-space: normal 会忽略这些换行符

Mitigation:

• 可以改用 white-space: pre-wrap 或 white-space: break-spaced 来同时支持自动换行和手动换行
• 测试验证哪种行为更符合预期

Risk 2: 现有布局可能有细微变化

Risk: 启用自动换行后，某些长文本的显示方式可能与之前不同

Mitigation:

• 此变化是改进性的，使文本正确显示而非溢出
• 用户可以通过调整文本框大小来控制显示效果

Migration Plan

1. Phase 1: 修改 add_text_element() 函数，添加 tf.word_wrap = True
2. Phase 2: 修改 render_text_element_to_html() 函数，更新 CSS 样式
3. Phase 3: 创建测试 YAML 文件，包含长文本内容验证效果
4. Phase 4: 更新 README.md 说明文本框默认自动换行

Rollback Strategy: 如有问题，删除添加的代码行即可快速回滚

Open Questions

无。这是一个简单直接的功能改进，实现方式清晰。