Template

模板制作教程

模板制作教程

前台采用 多主题 + 栏目级模板 双层机制，基于 Jinja2 + Bootstrap 4。

主题目录结构

主题位于 app/frontend/templates/themes//：

`themes/default/
├── manifest.json          # 主题元数据
├── base.html              # 基础布局（必须）
├── index.html             # 首页（必须）
├── list.html              # 列表页默认（必须）
├── article.html           # 文章详情默认（必须）
├── page.html              # 单页默认（必须）
├── 404.html / 500.html    # 错误页（必须）
├── closed.html            # 站点关闭提示
├── list_card.html         # 栏目备选模板（可选）
├── search.html            # 搜索结果页
├── css/                   # 样式目录（v2.2 起外置）
│   └── style.css
├── js/                    # 脚本目录（可选）
├── images/                # 静态图片（可选）
└── fonts/                 # 字体文件（可选）`

必备模板检查

v2.2 起上传/启用前强制检查 7 个必备模板（index/list/article/page/base/404/500.html），任一缺失拒绝启用。manifest 的 template_required 可追加额外必备声明。

静态资源引用

``

资源路由仅放行 css/js/images/fonts 四个子目录并拦截路径穿越；全部资源随主题打包下载时一并带走。

创建新主题

1. cp -r themes/default themes/green
2. 修改 css/style.css 与 manifest.json（slug 需与目录名一致）
3. 后台 系统设置 → 主题管理 → 启用

主题自动发现：扫描 themes/ 下所有子目录，无需代码注册。

模板继承

所有页面通过 {% extends theme_base %} 继承当前主题的 base.html：

`{% extends theme_base %}
{% block title %}页面标题{% endblock %}
{% block content %}页面内容{% endblock %}`

base.html 必须提供 title / css / content / js 四个 block。

全局模板变量

变量	类型	说明
site_settings	dict	站点设置（site_name, site_logo, footer_copyright 等）
site_fragments	dict	碎片内容，键为 slug
nav_columns	list	顶层栏目列表
current_theme	str	当前主题名
theme_base	str	当前主题 base 模板路径

常用对象字段速查

`{{ article.title }}  {{ article.summary }}  {{ article.content|safe }}
{{ article.cover }}  {{ article.published_at|date }}  {{ article.published_at|datetime }}
{{ article.get_field_value(field_id) }}      {# 自定义字段值 #}

{{ column.name }}  {{ column.slug }}  {{ column.type }}  {{ column.page_content|safe }}

{{ pagination.page }}  {{ pagination.pages }}  {{ pagination.has_prev }}  {{ pagination.has_next }}
{% for p in pagination.iter_pages() %} ... {% endfor %}

{{ site_fragments.contact_phone.value }}     {# 碎片取值 #}`

URL 生成与过滤器

`{{ url_for('frontend.index') }}
{{ url_for('frontend.column_detail', slug=column.slug) }}
{{ url_for('frontend.article_detail', slug=column.slug, aid=article.id) }}
{{ url_for('frontend.search') }}`

伪静态分页助手

`上一页
{% for p in pagination.iter_pages() %}
  {{ p }}
{% endfor %}
下一页`

过滤器	示例
date	`{{ article.published_at
datetime	`{{ article.published_at
truncate_text	`{{ article.summary

栏目级备选模板

创建 list_xxx.html / article_xxx.html / page_xxx.html，后台栏目编辑页自动出现在下拉选项中。受保护模板（不会列为备选）：base, 404, 500, closed, form_closed, index, search, column_children, form。

若栏目指定模板在当前主题中不存在，自动回退默认模板，不会报错。

模板制作检查清单

• 包含必备文件：base / index / list / article / page / 404 / 500 / closed
• 所有页面通过 {% extends theme_base %} 继承
• 富文本内容使用 |safe 过滤器
• 分页链接统一使用 frontend_pager_url()
• 自定义字段按 field_type 区分渲染