lanyuanxiaoyao
b2132dc06b
- Set text_frame.word_wrap = True in add_text_element() for PPTX - Change CSS from white-space: pre-wrap to normal in HTML preview - Add overflow-wrap: break-word for better word breaking - Update README.md with auto-wrap documentation - Update element-rendering and html-rendering specs - Archive change: 2026-03-02-add-text-auto-wrap
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 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
|
||
|
||
无。这是一个简单直接的功能改进，实现方式清晰。
|