MiaoheCMS v2.0 开发手册

本文档基于 MiaoheCMS v2.0 最新版本整理，包含所有可用模板标签、函数和实际使用示例。

本文档基于 MiaoheCMS v2.0 最新版本整理，包含所有可用模板标签、函数和实际使用示例。 最后更新：2026-08-03

一、模板文件结构

public/template/default/
├── index.htm          # 首页模板
├── list.htm           # 列表页模板
├── show.htm           # 内容详情页模板
├── page.htm           # 单页模板
├── search.htm         # 搜索结果页模板
├── header.htm         # 公共头部
├── footer.htm         # 公共底部
├── sidebar.htm        # 公共侧边栏
├── tag_list.htm       # 标签列表页模板
└── css/
    └── style.css      # 样式文件

二、变量输出

2.1 {$变量名} — 输出变量

{$title}              → 输出内容标题
{$head['title']}      → 输出 head 数组中的 title
{$MH['site_name']}    → 输出站点名称

自动包含 isset 检查，变量不存在时输出空字符串。

2.2 {SITE_URL} — 站点URL常量

<a href="{SITE_URL}">首页</a>

2.3 三元/空合并默认值

{$description?:'暂无描述'}
{$head['keywords']??''}

三、系统变量

模板中可以直接使用以下 PHP 变量：

3.1 {$MH} 配置数组可用字段

四、函数调用

4.1 {函数名(参数)} — 模板中调用 PHP 函数

4.2 使用示例

<!-- 格式化时间 -->
<span>{format_time($r['updatetime'], 'Y-m-d')}</span>

<!-- 友好时间 -->
<span>{friendly_time($r['updatetime'])}</span>

<!-- 标题截取20字 -->
<a href="{content_url($r['id'])}">{sub_string($r['title'], 20)}</a>

<!-- 内容摘要截取200字 -->
<p>{strip_and_cut($r['description']?:($r['content']?:''), 200)}</p>

<!-- 图片URL -->
<img src="{thumb_url($r['thumb'])}" alt="{$r['title']}">

五、控制流标签

5.1 {if}...{elseif}...{else}...{/if} — 条件判断

{if $catid==0}
    <!-- 首页专属内容 -->
{elseif $catid==1}
    <!-- 栏目1专属内容 -->
{else}
    <!-- 其他页面 -->
{/if}

<!-- 判断缩略图是否存在 -->
{if $r['thumb']}
    <img src="{thumb_url($r['thumb'])}" alt="{$r['title']}">
{/if}

<!-- 判断列表是否为空 -->
{if empty($list)}
    <div class="empty">暂无内容</div>
{/if}

支持运算符：== != > < >= <= && || !

5.2 {loop}...{/loop} — 循环遍历

二参数模式（只取value）：

{loop $list $r}
    <h3>{$r['title']}</h3>
{/loop}

三参数模式（key => value）：

{loop $list $key $r}
    <span>{$key}: {$r['title']}</span>
{/loop}

函数返回数组模式：

{loop explode(',', $keywords) $t}
    <a href="{SITE_URL}tags?tag={urlencode(trim($t))}">{trim($t)}</a>
{/loop}

循环内部可用 {$no} 输出从1开始的序号。

5.3 {for}...{/for} — for循环

{for $i=1; $i<=10; $i++}
    <span>{$i}</span>
{/for}

六、CMS内容标签

6.1 用途

调用指定条件的内容列表，不含分页。适合首页产品展示、侧边栏热门文章等场景。

6.2 参数说明

注意：当 catid 为单个栏目ID且该栏目有子栏目时，会自动包含子栏目的内容（v2.0+）。

6.3 可用变量

6.4 示例

<!-- 调用最新6篇文章 -->
{mh:content orderby="id" orderbyway="desc" row="6"}
<article>
    <h3><a href="{content_url($r['id'])}">{sub_string($r['title'], 30)}</a></h3>
    <p>{strip_and_cut($r['description']?:($r['content']?:''), 100)}</p>
    <span>{friendly_time($r['updatetime'])}</span>
</article>
{/mh:content}

<!-- 调用热门文章（按点击量排序，标题截取20字） -->
{mh:content orderby="clicks" row="10" titlelen="20"}
<li>
    <span class="rank">{$no}</span>
    <a href="{content_url($r['id'])}">{$r['title']}</a>
    <span>{$r['clicks']}阅读</span>
</li>
{/mh:content}

<!-- 调用指定栏目及其子栏目的最新内容 -->
{mh:content catid="9" orderby="id" row="6" titlelen="30" infolen="200"}
<div class="product-card">
    {if $r['thumb']}
    <img src="{thumb_url($r['thumb'])}" alt="{$r['title']}">
    {/if}
    <h3><a href="{content_url($r['id'])}">{$r['title']}</a></h3>
    <p>{$r['description']}</p>
</div>
{/mh:content}

<!-- 随机调用4篇 -->
{mh:content orderby="rand" row="4"}
...
{/mh:content}

<!-- 只要带缩略图的 -->
{mh:content withthumb="1" row="8" titlelen="30"}
...
{/mh:content}

<!-- 最近7天内的内容 -->
{mh:content subday="7" orderby="id" row="10"}
...
{/mh:content}

<!-- 按推荐位调用 -->
{mh:content posid="1" row="5" titlelen="30"}
...
{/mh:content}

七、列表标签

7.1 用途

用于栏目列表页，自动包含分页功能。通常配合 {$mh_page} 输出分页HTML。

7.2 参数说明

注意：{mh:list} 会自动包含子栏目内容，无需额外设置。

7.3 标签结束后可用变量

7.4 示例

<!-- 标准列表页 -->
<div class="breadcrumb">
    <a href="{SITE_URL}">首页</a> &gt;
    <span>{catname($catid)}</span>
</div>

<section class="list-section">
    <ul class="article-list">
        {mh:list catid="$catid" row="15" page="$page" titlelen="30" infolen="200"}
        <li class="article-item">
            {if $r['thumb']}
            <a href="{content_url($r['id'])}" class="thumb">
                <img src="{thumb_url($r['thumb'])}" alt="{sub_string($r['title'], 30)}" loading="lazy">
            </a>
            {/if}
            <div class="article-info">
                <h3><a href="{content_url($r['id'])}">{sub_string($r['title'], 30)}</a></h3>
                <p class="desc">{strip_and_cut($r['description']?:($r['content']?:''), 200)}</p>
                <div class="meta">
                    <span>{friendly_time($r['updatetime'])}</span>
                    <span>阅读({$r['clicks']})</span>
                    <span>评论({$r['comments']})</span>
                </div>
            </div>
        </li>
        {/mh:list}
    </ul>

    {if empty($list)}
    <div class="empty">暂无内容</div>
    {/if}
</section>

<!-- 分页 -->
<div class="pagination">
    {$mh_page}
</div>

八、栏目标签

8.1 用途

调用栏目数据，用于导航菜单、产品分类等。

8.2 参数说明

8.3 可用变量

8.4 示例

<!-- 顶部导航菜单 -->
<nav>
    {mh:category parentid="0" ismenu="1"}
    <a href="{SITE_URL}{$r['catdir']}/" {if $catid==$r['catid']}class="active"{/if}>
        {$r['catname']}
    </a>
    {/mh:category}
</nav>

<!-- 产品分类展示 -->
<div class="category-grid">
    {mh:category parentid="0" ismenu="1" row="8"}
    <a href="{SITE_URL}{$r['catdir']}/" class="category-card">
        <span class="cat-name">{$r['catname']}</span>
    </a>
    {/mh:category}
</div>

<!-- 获取当前栏目的子栏目 -->
{mh:category catid="$catid" type="son" row="10"}
<a href="{SITE_URL}{$r['catdir']}/">{$r['catname']}</a>
{/mh:category}

<!-- 底部产品分类 -->
{mh:category parentid="0" ismenu="1" row="6"}
<a href="{SITE_URL}{$r['catdir']}/">{$r['catname']}</a>
{/mh:category}

九、评论标签

9.1 用途

调用评论数据，用于侧边栏最新评论或内容页评论列表。

9.2 参数说明

9.3 可用变量

9.4 示例

<!-- 侧边栏最新评论 -->
<div class="widget">
    <h3>最新评论</h3>
    <ul>
        {mh:comment row="6"}
        <li>
            <span class="comment-user">{$r['username']}：</span>
            <a href="{content_url($r['contentid'])}#comment">
                {strip_and_cut($r['content'], 40)}
            </a>
        </li>
        {/mh:comment}
    </ul>
</div>

十、通用表查询

10.1 用途

直接查询数据库中的任意表，可用于友情链接、自定义数据等。

10.2 参数说明

10.3 示例

<!-- 友情链接 -->
<div class="friend-links">
    {table:link where="isindex=1" orderby="listorder" row="20"}
    <a href="{$r['url']}" target="_blank" rel="nofollow">{$r['name']}</a>
    {/table:link}
</div>

<!-- 带Logo的友链 -->
{table:link where="logo!=''" orderby="listorder" row="10"}
<a href="{$r['url']}" target="_blank">
    <img src="{$r['logo']}" alt="{$r['name']}">
</a>
{/table:link}

<!-- 自定义查询 -->
{table:guestbook where="status=1" orderby="id" row="10"}
<div>
    <strong>{$r['username']}</strong>
    <p>{$r['content']}</p>
</div>
{/table:guestbook}

十一、SQL查询

11.1 用途

执行自定义SQL查询（仅允许SELECT，安全限制）。

注意： 从 v2.0 起，外部数据库连接功能已被禁用，仅支持查询当前站点数据库。

11.2 示例

<!-- 标签云 -->
{mh:sql sql="SELECT tag, COUNT(*) as cnt FROM {prefix}tag GROUP BY tag ORDER BY cnt DESC LIMIT 20"}
<a href="{SITE_URL}tags?tag={urlencode($r['tag'])}">{$r['tag']}({$r['cnt']})</a>
{/mh:sql}

<!-- 统计查询 -->
{mh:sql sql="SELECT COUNT(*) AS cnt FROM {prefix}content WHERE status=1"}
<span>共有 {$r['cnt']} 篇文章</span>
{/mh:sql}

{prefix} 会自动替换为实际的表前缀。

十二、友情链接

12.1 用途

调用友情链接数据（也可用 {table:link} 替代）。

12.2 参数说明

十三、分页标签

13.1 用途

获取分页数据（页码、总数等），用于自定义分页样式。

13.2 参数

• listsize — 列表每页数量

13.3 可用变量

十四、上一篇/下一篇

14.1 {getpre($id, $catid, $len)} — 上一篇

{getpre($id, $catid, 40)}

输出格式：<a href="URL">标题（截取40字）</a>

注意： 默认输出不含箭头和"上一篇"标签，如需箭头可通过 CSS ::before 伪元素添加。

14.2 {getnext($id, $catid, $len)} — 下一篇

{getnext($id, $catid, 40)}

输出格式：<a href="URL">标题（截取40字）</a>

注意： 默认输出不含箭头和"下一篇"标签，如需箭头可通过 CSS ::before 伪元素添加。

14.3 {content_pre} — 上一篇（模板变量）

依赖： 控制器必须传入 $prev 变量。仅在控制器已实现传值时有效。

{content_pre}

输出格式：<a href="URL">← 标题</a>（内置 ← 箭头）

14.4 {content_next} — 下一篇（模板变量）

依赖： 控制器必须传入 $next 变量。仅在控制器已实现传值时有效。

{content_next}

输出格式：<a href="URL">标题 →</a>（内置 → 箭头）

14.5 使用示例

<div class="article-nav">
    {getpre($id, $catid, 40)}
    {getnext($id, $catid, 40)}
</div>

十五、广告标签

15.1 基本用法

从 ad 表中查询广告数据，常用于首页横幅、侧边栏广告等。

{mh:ad row="5" orderby="listorder" orderbyway="ASC"}
<div class="ad-item">
    <a href="{$r['url']}" target="_blank">
        <img src="{$r['image']}" alt="{$r['name']}">
    </a>
</div>
{/mh:ad}

15.2 参数说明

15.3 可用字段

十六、模板自定义标签

16.1 基本用法

从 tag_library 表中读取预先定义好的 HTML/文本片段。

前提： 需先在后台管理 → 标签管理中定义标签名称及其内容。

{label:copyright}      → 输出版权信息
{label:notice}         → 输出公告
{label:contact_info}   → 输出联系方式

<footer>
    {label:copyright}
    {label:icp}
</footer>

十七、JS输出标签

17.1 基本用法

与 {$变量名} 类似，但会在输出时对特殊字符做 JavaScript 转义处理，适合在 <script> 标签中嵌入 PHP 变量。

<script>
    var title = '{js:title}';         → 对标题中的引号做转义
    var catid = {js:catid};           → 数字直接输出
    var siteUrl = '{js:SITE_URL}';    → 站点URL
</script>

注意： {js:变量名} 与 {$变量名} 的区别在于自动添加转义处理，避免 JS 语法错误。

十八、模板包含

18.1 {include 模板路径} — 包含子模板

{include template/default/header.htm}
{include template/default/footer.htm}
{include template/default/sidebar.htm}

十九、插件钩子

19.1 {hook:插件名} — 调用插件

{hook:plugin_name}
{hook:plugin_name args:$param1,$param2}

二十、PHP执行

20.1 {mhcms PHP代码} — 执行PHP

{mhcms $var = config('site.site_name');}

安全限制：只允许白名单内的函数调用。

二十一、字段输出

21.1 {field:字段名} — 在CMS标签内输出字段

{mh:content row="5"}
    <h3>{field:title}</h3>       <!-- 等同于 {$r['title']} -->
    <p>{field:description}</p>   <!-- 等同于 {$r['description']} -->
{/mh:content}

二十二、标签速查表

二十三、完整页面示例

23.1 首页示例

{include template/default/header.htm}

<!-- Banner / 轮播 -->
<section class="banner">
    <div class="swiper swiper-banner">
        <div class="swiper-wrapper">
            <div class="swiper-slide">
                <div class="slide-content">
                    <h1>{$MH['site_name']}</h1>
                    <p>{$MH['meta_description']}</p>
                </div>
            </div>
        </div>
    </div>
</section>

<!-- 产品分类导航 -->
<section class="category-section">
    <div class="category-grid">
        {mh:category parentid="0" ismenu="1" row="8"}
        <a href="{SITE_URL}{$r['catdir']}/" class="category-card">
            <span class="cat-name">{$r['catname']}</span>
        </a>
        {/mh:category}
    </div>
</section>

<!-- 热门产品 -->
<section class="products-section">
    <div class="section-header">
        <h2>热门<span class="accent-text">产品</span></h2>
    </div>
    <div class="products-grid">
        {mh:content orderby="clicks" orderbyway="desc" row="6" titlelen="30"}
        <article class="product-card">
            {if $r['thumb']}
            <div class="card-img">
                <img src="{thumb_url($r['thumb'])}" alt="{$r['title']}" loading="lazy">
            </div>
            {/if}
            <h3><a href="{content_url($r['id'])}">{sub_string($r['title'], 30)}</a></h3>
            <p>{strip_and_cut($r['description']?:($r['content']?:''), 80)}</p>
        </article>
        {/mh:content}
    </div>
</section>

<!-- 新闻资讯 -->
<section class="news-section">
    <div class="section-header">
        <h2>行业<span class="accent-text">动态</span></h2>
    </div>
    <div class="news-grid">
        {mh:content orderby="id" orderbyway="desc" row="6" titlelen="30"}
        <article class="news-card">
            {if $r['thumb']}
            <div class="news-img">
                <img src="{thumb_url($r['thumb'])}" alt="{$r['title']}" loading="lazy">
            </div>
            {/if}
            <div class="news-info">
                <h3><a href="{content_url($r['id'])}">{$r['title']}</a></h3>
                <p>{strip_and_cut($r['description']?:($r['content']?:''), 80)}</p>
                <span>{friendly_time($r['updatetime'])}</span>
            </div>
        </article>
        {/mh:content}
    </div>
</section>

{include template/default/footer.htm}

23.2 列表页示例

{include template/default/header.htm}

<div class="breadcrumb">
    <a href="{SITE_URL}">首页</a> &gt;
    <span>{catname($catid)}</span>
</div>

<main class="main">
    <div class="content-wrap">
        <section class="list-section">
            <ul class="article-list">
                {mh:list catid="$catid" row="15" page="$page" titlelen="30" infolen="200"}
                <li class="article-item">
                    {if $r['thumb']}
                    <a href="{content_url($r['id'])}" class="thumb">
                        <img src="{thumb_url($r['thumb'])}" alt="{sub_string($r['title'], 30)}" loading="lazy">
                    </a>
                    {/if}
                    <div class="article-info">
                        <h3><a href="{content_url($r['id'])}">{sub_string($r['title'], 30)}</a></h3>
                        <p class="desc">{strip_and_cut($r['description']?:($r['content']?:''), 200)}</p>
                        <div class="meta">
                            <span>{friendly_time($r['updatetime'])}</span>
                            <span>阅读({$r['clicks']})</span>
                        </div>
                    </div>
                </li>
                {/mh:list}
            </ul>

            {if empty($list)}
            <div class="empty">暂无内容</div>
            {/if}
        </section>

        <div class="pagination">{$mh_page}</div>
    </div>

    {include template/default/sidebar.htm}
</main>

{include template/default/footer.htm}

23.3 内容详情页示例

{include template/default/header.htm}

<div class="breadcrumb">
    <a href="{SITE_URL}">首页</a> &gt;
    {mh:category catid="$catid"}
    <a href="{SITE_URL}{$r['catdir']}/">{$r['catname']}</a>
    {/mh:category}
    <span>正文</span>
</div>

<main class="main">
    <div class="content-wrap">
        <article class="article-detail">
            <h1>{$title}</h1>
            <div class="meta">
                <span>发布时间：{format_time($updatetime, 'Y-m-d H:i')}</span>
                <span>阅读：{$clicks}</span>
                <span>评论：{$comments}</span>
            </div>

            <div class="content">
                {$content}
            </div>

            {if $keywords}
            <div class="tags">
                {loop explode(',', $keywords) $t}
                {if trim($t)}
                <a href="{SITE_URL}tags?tag={urlencode(trim($t))}">{trim($t)}</a>
                {/if}
                {/loop}
            </div>
            {/if}

            <div class="article-nav">
                {getpre($id, $catid, 40)}
                {getnext($id, $catid, 40)}
            </div>
        </article>
    </div>

    {include template/default/sidebar.htm}
</main>

{include template/default/footer.htm}

23.4 侧边栏示例

<aside class="sidebar">
    <!-- 搜索 -->
    <div class="widget widget-search">
        <form action="{SITE_URL}search" method="get">
            <input type="text" name="q" placeholder="搜索内容..." value="{$keyword??''}">
            <button type="submit">搜索</button>
        </form>
    </div>

    <!-- 热门文章 -->
    <div class="widget widget-hot">
        <h3>热门文章</h3>
        <ul>
            {mh:content orderby="clicks" row="10" titlelen="20"}
            <li>
                <span class="rank-num">{$no}</span>
                <a href="{content_url($r['id'])}">{sub_string($r['title'], 20)}</a>
                <span class="clicks">{$r['clicks']}阅读</span>
            </li>
            {/mh:content}
        </ul>
    </div>

    <!-- 最新评论 -->
    <div class="widget widget-comments">
        <h3>最新评论</h3>
        <ul>
            {mh:comment row="6"}
            <li>
                <span class="comment-user">{$r['username']}：</span>
                <a href="{content_url($r['contentid'])}#comment">
                    {strip_and_cut($r['content'], 40)}
                </a>
            </li>
            {/mh:comment}
        </ul>
    </div>

    <!-- 热门标签 -->
    <div class="widget widget-tags">
        <h3>热门标签</h3>
        <div class="tag-cloud">
            {mh:sql sql="SELECT tag, COUNT(*) as cnt FROM {prefix}tag GROUP BY tag ORDER BY cnt DESC LIMIT 20"}
            <a href="{SITE_URL}tags?tag={urlencode($r['tag'])}">{$r['tag']}</a>
            {/mh:sql}
        </div>
    </div>

    <!-- 友情链接 -->
    <div class="widget widget-links">
        <h3>友情链接</h3>
        <ul>
            {table:link where="isindex=1" orderby="listorder" row="20"}
            <li><a href="{$r['url']}" target="_blank" rel="nofollow">{$r['name']}</a></li>
            {/table:link}
        </ul>
    </div>
</aside>

文档版本：v2.0
适用系统：MiaoheCMS v2.0
模板目录：public/template/default/
模板缓存：storage/tplcache/

文档版本：v2.0 · 适用系统：MiaoheCMS v2.0 · 模板目录：public/template/default/ · 缓存目录：storage/tplcache/