模版开发文档

{% set articles = contentList(channel='news', limit=6)%} {# 先从 news 栏目取出 6 篇文章，后续页面内容都基于这组数据生成 #}
{% for item in articles %} {# 开始逐条处理文章：每次循环里，item 就是当前这一篇文章 #}
    <a href="{{ item.url }}">{{ item.title }}</a> {# 把文章标题输出成可点击链接，用户点击后会进入文章详情页 #}
{% endfor %} {# 循环结束：上面的链接结构会按文章数量重复渲染 #}

{% set topArticles = contentList(channel='news', is_top=true, has_image=true, order_by='published_at', order_dir='desc', limit=4)%} {# 只取“置顶且有封面图”的 4 篇文章，并按发布时间从新到旧排序 #}
{% for item in topArticles %} {# 逐条渲染推荐文章卡片，item 代表当前这篇推荐文章 #}
    {% set plainSummary = item.summary | plainText() %} {# 先把摘要里的 HTML 标签去掉，避免页面直接显示富文本代码 #}
    {% set shortSummary = plainSummary | truncate(60) %} {# 把纯文本摘要限制在 60 字内，防止卡片高度被长文本撑开 #}
    <article class="news-card"> <!-- 每篇推荐文章外层容器，便于统一排版和样式控制 -->
        <img src="{{ item.cover_image }}" alt="{{ item.title }}"> <!-- 文章封面图；alt 使用标题，方便无图或读屏场景理解内容 -->
        <h3><a href="{{ item.url }}">{{ item.title }}</a></h3> <!-- 标题点击后进入详情页，是用户最主要的阅读入口 -->
        <p>{{ shortSummary }}</p> <!-- 输出处理后的短摘要，帮助用户快速判断是否继续阅读 -->
        <time>{{ item.published_at | formatDate('Y-m-d', '--') }}</time> <!-- 输出发布时间，时间为空时用 -- 兜底，避免界面留空 -->
    </article> <!-- 当前文章卡片渲染完成 -->
{% endfor %} {# 推荐文章循环结束，页面上会得到最多 4 张推荐卡片 #}

{% set list = contentList(channel='news', limit=6)%} {# 先获取列表数据，后续直接在字段上做管道处理 #}
{% for item in list %} {# 逐条渲染时，标题、摘要、时间都直接在字段上加工 #}
    <h3><a href="{{ item.url }}">{{ item.title | plainText() | truncate(28) }}</a></h3> <!-- 标题：先去标签再截断，避免长标题撑开布局 -->
    <p>{{ item.summary | plainText() | default(item.content_html | plainText()) | truncate(70) }}</p> <!-- 摘要为空时回退正文纯文本，再统一截断 -->
    <time>{{ item.published_at | formatDate('Y-m-d', '--') }}</time> <!-- 时间为空时用 -- 兜底，保证界面稳定 -->
{% endfor %} {# 推荐：只在需要复用同一结果时再用 set 存变量 #}

{% set focusIds = '12,15,18' %} {# 先定义要“固定展示”的文章 ID，确保运营指定的内容一定出现 #}
{% set focusArticles = contentList(include_ids=focusIds, fields='title,url,published_at', order_by='id', order_dir='asc')%} {# 第一组数据：只读取这些指定 ID 的文章，并只返回当前区块需要的字段 #}
{% set moreArticles = contentList(channel='news', exclude_ids=focusIds, limit=6)%} {# 第二组数据：从普通栏目里补充内容，同时排除已在固定区出现的文章 #}
{% for item in focusArticles %} {# 循环输出固定推荐区，保证重点内容优先曝光 #}
    <a class="focus-link" href="{{ item.url }}">{{ item.title }}</a> <!-- 固定推荐文章链接，通常用于头部或重点区域 -->
{% endfor %} {# 固定推荐区输出完成 #}
{% for item in moreArticles %} {# 循环输出普通补充列表，让页面内容更完整 #}
    <a class="more-link" href="{{ item.url }}">{{ item.title }}</a> <!-- 普通文章链接，作为推荐区之外的延伸阅读 -->
{% endfor %} {# 普通补充列表输出完成 #}

{% set pageItems = contentList(type='page', status='published', order='updated_at_desc', limit=6)%} {# 读取已发布的单页面内容，并按最近更新时间排序，方便展示“最新更新” #}
{% for item in pageItems %} {# 逐条处理单页面数据，item 就是当前这一个单页 #}
    <a href="{{ linkTo(type='page', id=item.id, default='#')}}">{{ item.title }}</a> <!-- 用 linkTo 统一生成单页地址，避免手写链接造成跳转错误 -->
{% endfor %} {# 单页列表循环结束，以上链接会根据单页数量重复输出 #}

{% set banners = promos(code='home_banner', limit=5)%} {# 从图宣位 home_banner 读取最多 5 条素材，通常用于首页轮播 #}
{% for item in banners %} {# 逐条渲染轮播项，item 代表当前这张轮播图的数据 #}
    <a href="{{ item.link_url }}" target="{{ item.link_target }}"> <!-- 轮播图外层可点击区域：点击后按配置跳转到目标地址 -->
        <img src="{{ item.image_url }}" alt="{{ item.title }}"> <!-- 轮播图片本体：image_url 是图片地址，title 作为无障碍说明文字 -->
    </a> <!-- 当前轮播项链接闭合，防止后续元素被错误包裹 -->
{% endfor %} {# 轮播项循环结束，页面上会得到最多 5 个可轮播素材 #}

{% set banner = promo(code='home_banner') %} {# 读取单条主视觉图宣，适合页面顶部“只展示 1 条”的场景 #}
{% if banner %} {# 只有拿到有效数据才输出，避免空数据时页面出现空白图片或坏链接 #}
    <a href="{{ banner.link_url }}" target="{{ banner.link_target }}"> <!-- 单条图宣点击区域：用于跳转活动页、专题页或外部地址 -->
        <img src="{{ banner.image_url }}" alt="{{ banner.title }}"> <!-- 单条图宣图片：显示视觉素材，alt 提供辅助说明 -->
    </a> <!-- 单条图宣渲染结束 -->
{% endif %} {# 条件判断结束：无数据时整段不会输出任何 HTML #}
{% set scopedPromos = promos(page_scope='home', template_name=current.page.template_name, random=true, limit=2)%} {# 再按“页面范围 + 当前模板名”取 2 条更贴合当前页面的图宣素材 #}
{% for item in scopedPromos %} {# 逐条渲染模板范围内的图宣，作为补充推荐位 #}
    <a href="{{ item.link_url }}" target="{{ item.link_target }}">{{ item.title }}</a> <!-- 文本形式的图宣入口，适合侧栏或轻量推荐区 -->
{% endfor %} {# 模板范围图宣循环结束 #}

{% set previousItem = previous(current.content) %} {# 基于当前正在阅读的内容，获取时间或排序上更早的一篇文章 #}
{% set nextItem = next(current.content) %} {# 基于当前内容，获取下一篇文章，方便用户连续阅读 #}
{% set relatedItems = related(current.content, limit=4)%} {# 获取与当前内容相关的 4 篇文章，用于“你可能还想看”区域 #}
{% if previousItem %} {# 只有确实存在上一篇时才显示链接，避免出现无效入口 #}
    <a href="{{ previousItem.url }}">上一篇：{{ previousItem.title }}</a> <!-- 上一篇文章跳转链接，帮助用户回看前一条内容 -->
{% endif %} {# 上一篇条件块结束 #}
{% if nextItem %} {# 只有存在下一篇时才显示链接，保证交互始终有效 #}
    <a href="{{ nextItem.url }}">下一篇：{{ nextItem.title }}</a> <!-- 下一篇文章跳转链接，引导用户继续阅读 -->
{% endif %} {# 下一篇条件块结束 #}
{% for item in relatedItems %} {# 遍历相关文章列表，把每篇相关内容都渲染成入口链接 #}
    <a href="{{ item.url }}">{{ item.title }}</a> <!-- 单条相关文章链接，点击后进入对应文章详情页 -->
{% endfor %} {# 相关文章循环结束 #}

{% set coverArticles = contentList(channel='news', with_cover=true, limit=5)%} {# 先取 5 篇带封面图的文章，确保后续头图位一定有图可显示 #}
{% set firstArticle = first(coverArticles) %} {# 从结果里拿第 1 篇，作为页面最醒目的主头图内容 #}
{% if firstArticle %} {# 只有拿到首条文章时才渲染头图区，避免无数据时报错或空框 #}
    <article class="hero-article"> <!-- 头图卡片外层容器，用于控制整块大图+标题的布局 -->
        <img src="{{ firstArticle.cover_image }}" alt="{{ firstArticle.title }}"> <!-- 头图图片本体，来源于首篇文章封面图字段 -->
        <h3><a href="{{ firstArticle.url }}">{{ firstArticle.title }}</a></h3> <!-- 头图标题和链接，点击可进入该文章详情页 -->
    </article> <!-- 头图卡片渲染完成 -->
{% endif %} {# 头图条件块结束 #}

{% set navItems = nav(limit=8)%} {# 读取最多 8 个头部导航项，作为页面主导航菜单的数据来源 #}
{% for item in navItems %} {# 逐条输出导航项，item 里包含名称、地址、是否高亮、打开方式等信息 #}
    <a{% if item.is_active %} class="is-active"{% endif %} href="{{ item.url }}"{% if item.target == '_blank' %} target="_blank" rel="noopener noreferrer"{% endif %}>{{ item.name }}</a> <!-- 导航链接：当前页自动加高亮；若配置新窗口则附带安全属性后再打开 -->
{% endfor %} {# 主导航循环结束 #}
{% set breadcrumbs = breadcrumb(channel_id=current.channel.id)%} {# 按当前栏目生成面包屑路径，用于告诉用户“当前位置” #}
{% for item in breadcrumbs %} {# 遍历面包屑路径节点，通常从首页到当前栏目逐级展示 #}
    <a href="{{ item.url }}">{{ item.name }}</a> <!-- 单个面包屑节点链接，支持快速返回上级页面 -->
{% endfor %} {# 面包屑循环结束 #}

{% set pageData = contentPage(type='article', per_page=5, page_name='page', window=2, keyword=current.page.keyword)%} {# 在服务端执行“搜索 + 分页”：每页 5 条，并按 page 参数切换页码 #}
{% set list = pageData.items %} {# 从返回结果中取出“当前页文章列表”部分，供下面循环渲染 #}
{% set pager = pageData.pagination %} {# 从返回结果中取出分页信息（总页数、当前页、每个页码链接等） #}
{% for item in list %} {# 逐条输出当前页文章，item 就是当前这一篇 #}
    <a href="{{ item.url }}">{{ item.title }}</a> <!-- 文章标题入口，用户点击后进入对应详情页 -->
{% endfor %} {# 当前页文章列表渲染结束 #}
{% for p in pager.pages %} {# 循环输出每个页码按钮，支持用户在结果页之间切换 #}
    <a href="{{ p.url }}"{% if p.is_current %} class="active"{% endif %}>{{ p.label }}</a> <!-- 单个分页按钮：当前页会附加 active 样式用于高亮提示 -->
{% endfor %} {# 分页按钮渲染结束 #}

{% set perPage = config('theme.list.per_page', 5) %} {# 从统一配置读取每页条数；未配置时默认 5 #}
{% set pagerWindow = config('theme.list.window', 2) %} {# 从统一配置读取分页窗口；未配置时默认 2 #}
{% set pageData = contentPage(type='article', per_page=perPage, page_name='page', window=pagerWindow, keyword=current.page.keyword) %} {# 把配置项直接用于服务端分页查询 #}
{% for item in pageData.items %} {# 正常渲染当前页内容 #}
    <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

{% set sectionTitle = config('theme.home.hot_title', '精华内容') %} {# 统一读取区块标题：后台可改，模板不用改代码 #}
{% set sectionIntro = config('theme.home.hot_intro', '精选高价值内容') %} {# 统一读取副标题：未配置时使用默认文案 #}
{% set showHot = config('theme.home.hot_enabled', true) %} {# 统一读取显示开关：便于按站点快速启停模块 #}
{% if showHot %} {# 只有开关为 true 时才渲染这整个区块 #}
    <section class="hot-block">
        <h2>{{ sectionTitle }}</h2>
        <p>{{ sectionIntro }}</p>
    </section>
{% endif %}

{% set pageData = query('article') | channel('news') | top(true) | keyword(current.page.keyword) | perPage(5) | pageName('page') | window(2) | paginate() %} {# 链式组合：栏目 + 置顶 + 关键词 + 分页参数，一行表达完整查询意图 #}
{% for item in pageData.items %} {# 渲染当前页文章列表 #}
    <a href="{{ item.url }}">{{ item.title | plainText() | truncate(28) }}</a>
{% endfor %}
{% for p in pageData.pagination.pages %} {# 渲染页码导航 #}
    <a href="{{ p.url }}"{% if p.is_current %} class="active"{% endif %}>{{ p.label }}</a>
{% endfor %}

<a href="/cat/{{ current.channel.slug }}?site={{ site.site_key }}&all=1" class="sidebar-link{% if current.page.show_all %} active{% endif %}">全部内容</a> <!-- “全部内容”入口：点击后带上 all=1 参数，列表范围从当前栏目切换为全站文章；当前状态自动高亮 -->
{% set pageData = contentPage(type='article', per_page=5, page_name='page', window=2, keyword=current.page.keyword)%} {# 当 URL 包含 all=1 时，后端会按“全站文章”返回分页结果，而不是只返回当前栏目 #}

{% set navListChannels = channels(is_nav=true, type='list', status=1, limit=8)%} {# 先取“栏目型”导航节点：这类节点通常对应新闻、公告、通知等栏目页 #}
{% set navPageChannels = channels(is_nav=true, type='page', status=1, limit=8)%} {# 再取“单页型”导航节点：这类节点通常对应关于我们、联系我们等单页 #}
{% for item in navListChannels %} {# 先渲染栏目导航区，便于把资讯类入口集中展示 #}
    <a href="{{ item.url }}">{{ item.name }}</a> <!-- 栏目导航链接，点击后进入对应栏目列表页 -->
{% endfor %} {# 栏目导航输出完成 #}
{% for item in navPageChannels %} {# 再渲染单页导航区，便于把说明类页面单独展示 #}
    <a href="{{ item.url }}">{{ item.name }}</a> <!-- 单页导航链接，点击后进入对应单页内容 -->
{% endfor %} {# 单页导航输出完成 #}