187 lines
4.4 KiB
Markdown
187 lines
4.4 KiB
Markdown
# 自定义模板系统规范 v2.0
|
||
|
||
## 系统架构（三层分离）
|
||
|
||
### 1. 布局模板（固定层）
|
||
|
||
- **作用**：提供页面基础框架，包括头部、导航、底部等
|
||
- **特性**：系统内置，不可修改，所有页面共享
|
||
- **路径**：`web/templates/builtin/layout.html`
|
||
- **职责**：确保品牌一致性和基础用户体验
|
||
|
||
### 2. 列表模板（可扩展层）
|
||
|
||
- **作用**：定义数据列表的展示方式
|
||
- **支持类型**：
|
||
- `list`：传统表格视图
|
||
- `card`：卡片式网格视图
|
||
- `timeline`：时间轴视图
|
||
- **自定义路径**：`web/templates/custom/{table_name}/`
|
||
- **后备机制**：未找到自定义模板时使用系统默认
|
||
|
||
### 3. 字段模板（可扩展层）
|
||
|
||
- **作用**：控制单个字段的渲染方式
|
||
- **内置渲染器**：
|
||
- `raw`：原始文本
|
||
- `markdown`：Markdown 渲染
|
||
- `time`：时间格式化
|
||
- `tag`：标签样式
|
||
- `category`：分类显示
|
||
- **自定义路径**：`web/templates/custom/{table_name}/field/`
|
||
|
||
## 数据流与渲染机制
|
||
|
||
### 后端职责
|
||
|
||
- 提供标准化 JSON API 接口
|
||
- 不包含任何模板渲染逻辑
|
||
- 支持分页、搜索、排序参数
|
||
|
||
```http
|
||
GET /api/data/{table_alias}?page=1&per_page=20&search=keyword&sort=created_at&order=desc
|
||
```
|
||
|
||
### 前端职责
|
||
|
||
- 纯前端模板渲染（无服务端渲染）
|
||
- AJAX 获取数据后动态渲染
|
||
- 支持模板缓存和热重载
|
||
|
||
### 渲染流程
|
||
|
||
```
|
||
用户请求 → 加载布局模板 → 加载列表模板 → 加载字段模板 → AJAX获取数据 → 前端渲染
|
||
```
|
||
|
||
## 配置规范
|
||
|
||
### YAML 配置扩展
|
||
|
||
```yaml
|
||
templates:
|
||
custom_path: "./web/templates/custom"
|
||
cache_enabled: true
|
||
hot_reload: false # 开发环境可开启
|
||
|
||
tables:
|
||
- name: "articles"
|
||
template: "card" # 可选：指定默认模板
|
||
custom_templates:
|
||
list: "custom/articles/list.html"
|
||
fields:
|
||
content: "custom/articles/field/markdown.html"
|
||
```
|
||
|
||
### 文件结构规范
|
||
|
||
```
|
||
web/templates/
|
||
├── builtin/ # 系统内置（只读）
|
||
│ ├── layout.html # 基础布局
|
||
│ ├── list.html # 默认列表
|
||
│ └── field/ # 默认字段渲染器
|
||
├── custom/ # 用户自定义
|
||
│ └── {table_name}/
|
||
│ ├── list.html # 列表模板
|
||
│ ├── card.html # 卡片模板
|
||
│ └── field/
|
||
│ ├── markdown.html
|
||
│ └── tag.html
|
||
```
|
||
|
||
## 约束条件
|
||
|
||
### 技术约束
|
||
|
||
- 模板必须继承基础布局
|
||
- 仅支持前端渲染，无服务端逻辑
|
||
- 模板文件名必须符合规范
|
||
- 不支持动态模板编译（安全考虑）
|
||
|
||
### 兼容性约束
|
||
|
||
- 自定义模板需兼容系统 CSS 框架（TailwindCSS）
|
||
- 必须保持响应式设计
|
||
- 支持 JavaScript API 接口规范
|
||
|
||
## 功能变更说明
|
||
|
||
### 已移除功能
|
||
|
||
- ❌ 表格/卡片模式切换功能
|
||
- ❌ 数据导出功能
|
||
- ❌ 服务端模板渲染
|
||
- ❌ 动态表格模式切换
|
||
|
||
### 新增功能
|
||
|
||
- ✅ 自定义列表模板支持
|
||
- ✅ 自定义字段渲染器
|
||
- ✅ 模板热重载（开发环境）
|
||
- ✅ 模板版本管理
|
||
- ✅ 多级模板继承
|
||
|
||
## 实施里程碑
|
||
|
||
### Phase 1：基础架构（Week 1-2）
|
||
|
||
- [ ] 建立三层模板架构
|
||
- [ ] 实现基础布局模板
|
||
- [ ] 创建文件结构规范
|
||
- [ ] 添加模板验证机制
|
||
|
||
### Phase 2：模板引擎（Week 3-4）
|
||
|
||
- [ ] 实现模板加载系统
|
||
- [ ] 建立模板继承机制
|
||
- [ ] 添加错误处理和回退
|
||
- [ ] 实现模板缓存
|
||
|
||
### Phase 3：前端集成（Week 5-6）
|
||
|
||
- [ ] 完成 AJAX 数据获取
|
||
- [ ] 实现动态模板渲染
|
||
- [ ] 添加模板切换 UI
|
||
- [ ] 优化加载性能
|
||
|
||
### Phase 4：配置系统（Week 7-8）
|
||
|
||
- [ ] 扩展 YAML 配置支持
|
||
- [ ] 添加模板热重载
|
||
- [ ] 实现版本管理
|
||
- [ ] 编写开发文档
|
||
|
||
## 开发规范
|
||
|
||
### 模板开发
|
||
|
||
```html
|
||
<!-- 自定义列表模板示例 -->
|
||
{{template "layout" .}} {{define "content"}}
|
||
<div class="custom-list">
|
||
{{range .Data}}
|
||
<div class="item">{{template "field" dict "Value" .Title "Type" "raw"}}</div>
|
||
{{end}}
|
||
</div>
|
||
{{end}}
|
||
```
|
||
|
||
### JavaScript API
|
||
|
||
```javascript
|
||
// 模板系统API
|
||
TemplateSystem.load(tableName, templateType);
|
||
TemplateSystem.render(data, template);
|
||
TemplateSystem.reloadCache();
|
||
```
|
||
|
||
## 迁移指南
|
||
|
||
### 从旧版本迁移
|
||
|
||
1. 移除所有服务端模板渲染代码
|
||
2. 将现有模板迁移到新文件结构
|
||
3. 更新配置文件格式
|
||
4. 测试自定义模板兼容性
|