refactor: 重构文档结构,采用渐进式信息披露模式
将 README.md 拆分为多个专题文档,减少认知负荷: - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行,仅保留概览和导航 - 删除 README_DEV.md,内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
137
docs/development/modules/elements.md
Normal file
137
docs/development/modules/elements.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Elements 模块
|
||||
|
||||
`core/elements.py` 定义了所有元素类型的数据类和工厂函数。
|
||||
|
||||
## 职责
|
||||
|
||||
- 定义元素数据类(使用 `@dataclass`)
|
||||
- 在创建时进行元素级验证
|
||||
- 提供元素工厂函数
|
||||
|
||||
## 包含的内容
|
||||
|
||||
### FontConfig 类
|
||||
|
||||
字体配置数据类,支持所有字体属性:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class FontConfig:
|
||||
parent: Optional[str] = None
|
||||
family: Optional[str] = None
|
||||
size: Optional[int] = None
|
||||
bold: Optional[bool] = None
|
||||
italic: Optional[bool] = None
|
||||
underline: Optional[bool] = None
|
||||
strikethrough: Optional[bool] = None
|
||||
color: Optional[str] = None
|
||||
align: Optional[str] = None
|
||||
line_spacing: Optional[float] = None
|
||||
space_before: Optional[float] = None
|
||||
space_after: Optional[float] = None
|
||||
baseline: Optional[str] = None
|
||||
caps: Optional[str] = None
|
||||
```
|
||||
|
||||
在 `__post_init__` 中验证 baseline 和 caps 枚举值。
|
||||
|
||||
### 元素类
|
||||
|
||||
#### TextElement
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class TextElement:
|
||||
type: str = 'text'
|
||||
content: str = ''
|
||||
box: list = field(default_factory=lambda: [1, 1, 8, 1])
|
||||
font: FontConfig | str | dict = field(default_factory=dict)
|
||||
```
|
||||
|
||||
#### ImageElement
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ImageElement:
|
||||
type: str = 'image'
|
||||
src: str = ''
|
||||
box: list = field(default_factory=lambda: [1, 1, 4, 3])
|
||||
```
|
||||
|
||||
#### ShapeElement
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ShapeElement:
|
||||
type: str = 'shape'
|
||||
box: list = field(default_factory=lambda: [1, 1, 4, 2])
|
||||
shape: str = 'rectangle'
|
||||
fill: str = '#000000'
|
||||
line: dict = field(default_factory=dict)
|
||||
```
|
||||
|
||||
#### TableElement
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class TableElement:
|
||||
type: str = 'table'
|
||||
position: list = field(default_factory=lambda: [0, 0])
|
||||
col_widths: list = field(default_factory=list)
|
||||
data: list = field(default_factory=list)
|
||||
font: FontConfig | str | dict = field(default_factory=dict)
|
||||
header_font: FontConfig | str | dict = field(default_factory=dict)
|
||||
style: dict = field(default_factory=dict)
|
||||
```
|
||||
|
||||
### create_element() 工厂函数
|
||||
|
||||
```python
|
||||
def create_element(elem_dict: dict):
|
||||
elem_type = elem_dict.get('type')
|
||||
|
||||
if elem_type == 'text':
|
||||
return TextElement(**elem_dict)
|
||||
elif elem_type == 'image':
|
||||
return ImageElement(**elem_dict)
|
||||
elif elem_type == 'shape':
|
||||
return ShapeElement(**elem_dict)
|
||||
elif elem_type == 'table':
|
||||
return TableElement(**elem_dict)
|
||||
else:
|
||||
raise ValueError(f"Unknown element type: {elem_type}")
|
||||
```
|
||||
|
||||
自动将字典形式的 font 转换为 FontConfig 对象。
|
||||
|
||||
## 创建时验证
|
||||
|
||||
每个元素类在 `__post_init__` 中进行验证:
|
||||
|
||||
```python
|
||||
def __post_init__(self):
|
||||
# 检查必需字段
|
||||
if len(self.box) != 4:
|
||||
raise ValueError("box 必须包含 4 个数字")
|
||||
|
||||
# 验证颜色格式
|
||||
if self.fill and not _is_valid_color(self.fill):
|
||||
raise ValueError(f"无效的颜色格式: {self.fill}")
|
||||
```
|
||||
|
||||
## 元素级验证职责
|
||||
|
||||
- 必需字段检查
|
||||
- 数据类型检查
|
||||
- 值的有效性检查:
|
||||
- 颜色格式验证
|
||||
- 字体大小合理性
|
||||
- 枚举值检查(如形状类型)
|
||||
- 表格数据一致性
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Template 模块](template.md) - 模板系统
|
||||
- [Validators 模块](validators.md) - 验证器详解
|
||||
|
||||
[返回开发文档索引](../README.md)
|
||||
Reference in New Issue
Block a user