lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
138 lines
3.2 KiB
Markdown
138 lines
3.2 KiB
Markdown
# 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)
|