苹果CMS循环标签全场景调用实操教程 新手零门槛看完即可上手

前置准备工作

操作前请确认满足以下条件，缺少任意项会导致调用失效：

• 已搭建苹果CMS V10正式版环境，未搭建可直接访问官方地址下载：https://www.maccms.la/，按照向导完成安装即可
• 拥有模板文件修改权限，模板默认存储路径为/template/当前使用模板名称/，可直接在后台-模板管理中在线编辑对应文件，无需FTP工具
• 修改任意模板文件前必须先备份原文件，避免操作错误导致站点异常

核心循环标签语法基础

苹果CMS通用内容循环标签为{maccms:list}，所有内容类调用均基于该标签实现，基础语法结构如下：

``` {maccms:list 参数1="值" 参数2="值" ...} {/maccms:list} ```

核心可配置参数及含义如下，可根据需求自由组合：

• type：指定调用的分类ID，后台-分类管理中可查看每个分类对应的数字ID，支持填多个ID用英文逗号分隔
• limit：调用内容的条数，填正整数即可，比如limit="10"就是调用10条内容
• by：排序依据字段，常用值为time（更新时间）、hits（播放量）、score（评分）、id（内容ID）
• order：排序规则，desc为倒序，asc为正序
• notid：排除指定ID的内容，多个ID用英文逗号分隔
• score：筛选最低评分，比如score="8"就是只调用8分以上的内容
• year：筛选年代，比如year="2024"就是只调用2024年的内容
• area：筛选地区，比如area="大陆"就是只调用大陆地区的内容
• class：筛选题材标签，比如class="悬疑 yipinkpeoxf-ffes-5ixj"就是只调用悬疑类内容

分场景实操调用案例

以下案例均为可直接复制使用的代码，只需根据自己的需求调整参数即可生效。

场景1：首页热门影视列表调用

需求：调用12条最近更新的8分以上电影，按更新时间倒序排列，展示封面、名称、评分。

可直接复制代码到首页模板对应位置：

``` {maccms:list type="1" limit="12" order="desc" by="time" score="8"}

{$vo.name}

评分：{$vo.score}分

{/maccms:list} ```

参数说明：type="1"对应后台电影分类的ID，可自行替换为你站点对应分类的ID；loading="lazy"为图片懒加载属性，可提升页面加载速度。

场景2：分类页同分类内容调用

需求：分类页调用当前分类下排除当前浏览内容的10条高播放量内容，展示名称、播放量。

可直接复制代码到分类页模板对应位置：

``` {maccms:list type="{$type_id}" limit="10" order="desc" by="hits" notid="{$obj.id}"}

{$vo.name}

播放量：{$vo.hits}次

{/maccms:list} ```

参数说明：{$type_id}为系统全局变量，自动获取当前分类页的分类ID；{$obj.id}为当前浏览内容的ID，notid参数可避免当前内容出现在推荐列表中。

场景3：播放页同属性内容推荐

需求：播放页调用和当前视频同分类、同题材、同年代的8条内容，展示封面、名称、更新状态。

可直接复制代码到播放页模板对应位置：

``` {maccms:list type="{$obj.type_id}" limit="8" order="desc" by="time" class="{$obj.class} yipinkp2fe8-rmep-mhdv" year="{$obj.year}"}

{$vo.name}

{$vo.serial}

{/maccms:list} ```

参数说明：{$vo.pic|mac_img_url='240,320'}为系统内置的缩略图生成方法，可自动生成240320尺寸的封面图，避免图片变形；{$vo.serial}为更新状态字段，电视剧会展示“更新至XX集”，电影会展示“HD”等状态。

常见问题排查方案

• 循环无内容输出：首先检查type参数对应的分类ID是否真实存在，不要填不存在的ID；其次检查筛选条件是否过于严格（比如设置score="9"但站点没有9分以上内容）；最后确认limit参数为正整数，没有加特殊符号。
• 修改模板后无变化：苹果CMS默认开启模板缓存，每次修改模板后必须到后台-系统管理-清空缓存，刷新前台才能看到效果。
• 图片不显示或跳转错误：不要自行拼接图片地址和内容链接，直接使用系统提供的{$vo.pic}和{$vo.link}变量，会自动适配你站点的伪静态规则和存储配置。
• 分页列表不显示：分类页、搜索页的列表循环无需手动加limit参数，系统会自动按后台设置的每页条数调用，分页标签单独使用{maccms:page}即可实现翻页功能。

高阶进阶技巧

如果需要实现更个性化的调用效果，可使用以下技巧：

• 自定义字段调用：如果你在后台为内容添加了自定义字段（比如豆瓣评分、导演名称），可直接用{$vo.自定义字段名}输出，比如自定义字段为douban_score，就用{$vo.douban_score}输出对应值。
• 循环索引判断：可通过{$key}变量判断当前循环到第几条内容，实现特殊样式插入，比如第3条插入广告位的代码如下： ``` {maccms:list type="1" limit="12"} {if $key == 2}
• 这里插入你的广告代码
{/if}
• 正常内容{$vo.name}
{/maccms:list} ```

注意：{$key}从0开始计数，所以第3条对应的是$key==2。

• 多条件筛选：可同时组合多个筛选参数，比如同时筛选2024年、大陆地区、悬疑类的内容，只需添加year="2024" area="大陆" class="悬疑 yipinkpeoxf-ffes-5ixj"参数即可。