1
0

refactor: 重构文档结构,采用渐进式信息披露模式

将 README.md 拆分为多个专题文档,减少认知负荷:
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行,仅保留概览和导航
- 删除 README_DEV.md,内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions

View File

@@ -0,0 +1,148 @@
# Template 模块
`core/template.py` 实现了模板系统,支持变量解析、条件渲染和模板渲染。
## 职责
- 模板加载和变量解析
- 条件表达式评估
- 模板渲染
## 包含的内容
### Template 类
#### from_data() 类方法
从字典创建模板实例(用于内联模板):
```python
@classmethod
def from_data(cls, template_data, template_name, base_dir=None):
"""从字典创建模板(内联模板或外部模板)"""
obj = cls.__new__(cls)
obj.data = template_data
obj.base_dir = base_dir
obj.vars_def = {var['name']: var for var in template_data.get('vars', [])}
obj.elements = template_data.get('elements', [])
return obj
```
#### 变量解析
**resolve_value()** - 解析变量值:
```python
def resolve_value(self, value, vars_values):
"""解析变量值,支持 {varname} 语法"""
if isinstance(value, str) and '{' in value:
# 替换变量
result = value
for var_name, var_value in vars_values.items():
result = result.replace(f'{{{var_name}}}', str(var_value))
return result
return value
```
**resolve_element()** - 解析元素中的变量:
```python
def resolve_element(self, element, vars_values):
"""递归解析元素中的所有变量"""
resolved = {}
for key, value in element.items():
if isinstance(value, dict):
resolved[key] = self.resolve_element(value, vars_values)
elif isinstance(value, str):
resolved[key] = self.resolve_value(value, vars_values)
else:
resolved[key] = value
return resolved
```
#### 条件渲染
**evaluate_condition()** - 委托给 ConditionEvaluator
```python
def evaluate_condition(self, condition, vars_values):
"""评估条件表达式"""
from core.condition_evaluator import ConditionEvaluator
evaluator = ConditionEvaluator()
return evaluator.evaluate(condition, vars_values)
```
#### 模板渲染
**render()** - 渲染模板:
```python
def render(self, vars_values):
"""渲染模板,返回解析后的元素列表"""
elements = []
for elem in self.elements:
# 检查条件渲染
if 'visible' in elem:
if not self.evaluate_condition(elem['visible'], vars_values):
continue
# 解析变量
resolved_elem = self.resolve_element(elem, vars_values)
elements.append(resolved_elem)
return elements
```
## 特点
### 支持两种模板方式
- **外部模板**:从文件加载
- **内联模板**:从字典创建(通过 `from_data()`
### 变量替换
支持 `{varname}` 语法的变量替换:
```yaml
templates:
title-slide:
vars:
- name: title
elements:
- type: text
content: "{title}" # 变量替换
```
### 条件渲染
支持 `visible` 属性的条件表达式:
```yaml
elements:
- type: text
content: "有数据"
visible: "{count > 0}"
```
## 内联模板支持
`from_data()` 类方法使模板可以从字典创建:
```python
# 从内联模板定义创建
template = Template.from_data(
template_data=inline_template_dict,
template_name="title-slide",
base_dir=document_base_dir
)
```
## 相关文档
- [条件评估器](../condition-rendering.md) - 条件表达式语法
- [Elements 模块](elements.md) - 元素数据类
- [内联模板](../../templates/inline.md) - 用户指南
[返回开发文档索引](../README.md)