lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
3.2 KiB
3.2 KiB
Elements 模块
core/elements.py 定义了所有元素类型的数据类和工厂函数。
职责
- 定义元素数据类（使用
@dataclass） - 在创建时进行元素级验证
- 提供元素工厂函数
包含的内容
FontConfig 类
字体配置数据类，支持所有字体属性：
@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
@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
@dataclass
class ImageElement:
type: str = 'image'
src: str = ''
box: list = field(default_factory=lambda: [1, 1, 4, 3])
ShapeElement
@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
@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() 工厂函数
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__ 中进行验证：
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 模块 - 模板系统
- Validators 模块 - 验证器详解