# 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)