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