# 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` 赋值后添加：
```python
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

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