refactor: 重构文档结构,采用渐进式信息披露模式
将 README.md 拆分为多个专题文档,减少认知负荷: - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行,仅保留概览和导航 - 删除 README_DEV.md,内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
148
docs/development/modules/template.md
Normal file
148
docs/development/modules/template.md
Normal 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)
|
||||
Reference in New Issue
Block a user