基于您提供的三个文件，以下是 mtlists 标签的完整调用使用方法介绍：
## 一、标签概述
mtlists 是易优CMS的多商户扩展标签，用于 获取所有商家的列表信息 。与 mtindexlists 标签（获取单个商家详情）不同， mtlists 标签用于显示商家列表页面、商家推荐、商家排行榜等场景。
## 二、文件架构
## 三、标签语法
### 基本语法
{eyou:mtlists id="变量名" key="索引名" empty="空数据提示"}
<!-- 循环内容 -->
{$field.字段名}
{/eyou:mtlists}
```
### 闭合标签
这是一个 闭合标签 ，必须有开始和结束标签。
## 四、参数说明
参数 必填 默认值 说明
id 否 field 循环变量名，在标签内通过 {$field.字段名} 访问商家数据
key 否 i 循环索引变量名，通过 {$i} 访问（从1开始）
empty 否 空字符串 无数据时显示的提示内容，支持HTML
## 五、返回数据结构
每个商家对象包含以下字段：
### 1. 商家基本信息
字段名 类型 说明
merchant_id 整数 商家唯一标识ID
merchant_name 字符串 商家名称
merchant_pic 数组 商家图片集
merchant_pic.merchant_logo 字符串 商家Logo图片URL （已处理）
merchant_url 字符串 商家主页URL （自动生成）
merchant_content 字符串/数组 商家介绍内容
merchant_contact 数组 商家联系地址信息
audit_status 整数 审核状态（2=审核通过）
merchant_status 整数 商家状态（1=正常营业）
add_time 整数 添加时间（时间戳）
update_time 整数 更新时间（时间戳）
### 2. 商家图片集 ({$field.merchant_pic})
{$field.merchant_logo}
{$field.merchant_banner}
// 示例数据结构
[
'merchant_logo' => '/uploads/
merchant/logo_1.jpg',
'merchant_banner' => '/uploads/
merchant/banner_1.jpg',
// ... 其他图片字段
]
```
### 3. 商家联系信息 ({$field.merchant_contact})
```
// 示例数据结构（序列化存储，已反序列化）
[
'contactName' => '联系人姓名',
'contactPhone' => '联系电话',
'contactProvince' => '省份ID',
'contactCity' => '城市ID',
'contactDistrict' => '区县ID',
'contactAddress' => '详细地址'
]
```
## 六、数据过滤规则
### 1. 状态过滤（自动应用）
- is_del = 0 - 未删除的商家
- audit_status = 2 - 审核通过的商家
- merchant_status = 1 - 正常营业的商家
### 2. 数据处理（自动处理）
- 图片URL处理 ：通过 handle_subdir_pic(get_default_pic()) 确保图片链接有效
- 商家URL生成 ：自动生成商家主页URL： url('home/MultiMerchant/merchant_index', ['merchant_id'=>$merchant_id])
- 序列化数据解析 ：自动反序列化 merchant_pic 、 merchant_content 、 merchant_contact 字段
## 七、使用示例
### 示例1：基本商家列表展示
```
{eyou:mtlists id="merchant"
empty="<div class='no-merchant'>暂无
商家</div>"}
<div class="merchant-item">
<!-- 商家Logo和名称 -->
<a href="{$merchant.
merchant_url}"
class="merchant-link">
<img src="{$merchant.
merchant_pic.merchant_logo}
" alt="{$merchant.
merchant_name}"
onerror="this.src='/
static/images/
default-merchant.
png'" />
<h3>{$merchant.
merchant_name}</h3>
</a>
<!-- 商家简介（截取前100字符） -->
<p class="merchant-desc">
{eyou:msubstr name='$merchant.
merchant_content'
length='100' /}</p>
<!-- 索引号 -->
<span class="merchant-rank">No.
{$i}</span>
</div>
{/eyou:mtlists}
```
### 示例2：商家网格布局
```
{eyou:mtlists key="index"}
<div class="merchant-grid-item">
<div class="merchant-card">
<!-- 商家Logo -->
<div class="merchant-logo">
<img src="{$field.
merchant_pic.
merchant_logo}" alt="
{$field.merchant_name}">
</div>
<!-- 商家信息 -->
<div class="merchant-info">
<h4><a href="{$field.
merchant_url}">{$field.
merchant_name}</a></h4>
<!-- 商家状态标签 -->
<div
class="merchant-tags">
<span class="tag
verified">已认证</
span>
{eyou:eq
name='$field.
merchant_status'
value='1'}
<span class="tag
open">营业中</span>
{/eyou:eq}
</div>
<!-- 商家联系方式（如有）
-->
{eyou:notempty
name='$field.
merchant_contact.
contactPhone'}
<p
class="contact-phone">
{$field.
merchant_contact.
contactPhone}</p>
{/eyou:notempty}
</div>
</div>
</div>
{/eyou:mtlists}
```
### 示例3：商家列表分栏显示
```
<div
class="merchant-list-container">
{eyou:mtlists id="shop"}
<div class="merchant-column">
<!-- 奇数行样式 -->
{eyou:eq name='$i%2'
value='1'}
<div class="merchant-odd">
<img src="{$shop.
merchant_pic.
merchant_logo}"
class="logo-left">
<div class="info-right">
<h3>{$shop.
merchant_name}</h3>
<a href="{$shop.
merchant_url}"
class="btn-visit">进
入店铺</a>
</div>
</div>
{eyou:else /}
<!-- 偶数行样式 -->
<div class="merchant-even">
<div class="info-left">
<h3>{$shop.
merchant_name}</h3>
<a href="{$shop.
merchant_url}"
class="btn-visit">进
入店铺</a>
</div>
<img src="{$shop.
merchant_pic.
merchant_logo}"
class="logo-right">
</div>
{/eyou:eq}
</div>
{/eyou:mtlists}
</div>
```
### 示例4：结合其他标签使用
```
<!-- 商家列表页面 -->
<div class="page-title">合作商家</
div>
{eyou:mtlists empty="<p
class='empty-tip'>暂无合作商家，敬请期
待...</p>"}
<div class="merchant-block">
<!-- 使用 key 变量作为序号 -->
<div class="merchant-index">
{$i}.</div>
<div class="merchant-main">
<!-- 商家基本信息 -->
<div
class="merchant-header">
<h2><a href="{$field.
merchant_url}">{$field.
merchant_name}</a></h2>
<span class="join-date">
加入时间：{eyou:date
name='$field.add_time'
format='Y-m-d' /}</span>
</div>
<!-- 商家介绍 -->
<div class="merchant-intro">
{eyou:notempty
name='$field.
merchant_content'}
{$field.
merchant_content}
{eyou:else /}
<p class="no-intro">
该商家暂无详细介绍</p>
{/eyou:notempty}
</div>
<!-- 商家特色（可通过其他字段扩
展） -->
<div
class="merchant-features">
<span
class="feature-item">
正品保障</span>
<span
class="feature-item">
快速发货</span>
<span
class="feature-item">
客服在线</span>
</div>
</div>
</div>
{/eyou:mtlists}
```
## 八、高级用法
### 1. 结合 volist 标签限制数量
```
<!-- 显示前6个商家 -->
{eyou:mtlists id="merchant"}
{eyou:volist name="$field"
id="item" limit="6"}
<div class="merchant-item">
<img src="{$item.merchant_pic.
merchant_logo}" alt="{$item.
merchant_name}">
<h4>{$item.merchant_name}</h4>
</div>
{/eyou:volist}
{/eyou:mtlists}
```
### 2. 商家筛选和排序
```
<!-- 注意：mtlists 标签本身不支持筛选参
数，需要在前端或控制器中处理 -->
{eyou:mtlists}
{eyou:if condition='$field.add_time
> strtotime("-30 days")'}
<div class="new-merchant">
<span class="new-badge">NEW</
span>
<img src="{$field.merchant_pic.
merchant_logo}" alt="{$field.
merchant_name}">
<h3>{$field.merchant_name}</h3>
</div>
{/eyou:if}
{/eyou:mtlists}
```
### 3. 响应式商家列表
```
{eyou:mtlists}
<div class="col-xs-12 col-sm-6
col-md-4 col-lg-3">
<div
class="merchant-card-responsive"
>
<a href="{$field.
merchant_url}"
class="card-link">
<div class="card-image">
<img src="{$field.
merchant_pic.
merchant_logo}"
alt="{$field.
merchant_name}"
class="img-resp
onsive">
</div>
<div class="card-body">
<h5
class="card-title">
{$field.
merchant_name}</h5>
<p
class="card-text">
{eyou:msubstr
name='$field.
merchant_content'
length='60' /}</p>
</div>
<div
class="card-footer">
<small
class="text-muted">
更新于
{eyou:date
name='$field.
update_time'
format='m-d' /}
</small>
</div>
</a>
</div>
</div>
{/eyou:mtlists}
```
## 九、CSS样式建议
```
/* 商家列表基础样式 */
.merchant-item {
border: 1px solid #eaeaea;
border-radius: 8px;
padding: 15px;
margin-bottom: 15px;
transition: all 0.3s ease;
}
.merchant-item:hover {
box-shadow: 0 5px 15px rgba(0,0,
0,0.1);
transform: translateY(-3px);
}
.merchant-link {
display: flex;
align-items: center;
text-decoration: none;
color: #333;
}
.merchant-link img {
width: 60px;
height: 60px;
border-radius: 50%;
margin-right: 15px;
object-fit: cover;
}
.merchant-rank {
position: absolute;
top: 10px;
right: 10px;
background: #f0f0f0;
border-radius: 50%;
width: 30px;
height: 30px;
display: flex;
align-items: center;
justify-content: center;
font-weight: bold;
}
```
## 十、注意事项
### 1. 性能考虑
- 数据量 ：该标签查询所有符合条件的商家，如果商家数量很多（几百上千），可能影响页面加载性能
- 解决方案 ：
1. 在前端使用分页加载
2. 在控制器中先限制查询数量
3. 考虑使用缓存机制
### 2. 数据完整性
- Logo图片 ：部分商家可能没有上传Logo，需要在前端设置默认图片
- 联系信息 ： merchant_contact 字段可能为空，使用前应先检查
- 介绍内容 ： merchant_content 可能包含HTML标签，注意安全过滤
### 3. 与 mtindexlists 的区别
特性 mtlists mtindexlists 数据范围 所有商家 单个指定商家 返回内容 商家基本信息 商家详情+商品分类+商品列表 适用场景 商家列表页、商家推荐 商家详情页、店铺主页 参数要求 无需商家ID 必须提供 merchant_id
### 4. 扩展建议
如果需要更灵活的商家查询（如按分类、按地区、按评分筛选），可以考虑：
1. 扩展 TagMtlists 类，添加更多查询参数
2. 创建新的专用标签
3. 在控制器中处理复杂查询逻辑
## 十一、错误处理
### 1. 无数据情况
```
{eyou:mtlists empty="
<div class='empty-state'>
<img src='/static/images/
empty-merchant.png' alt='暂
无商家'>
<p>当前暂无商家入驻</p>
<a href='/merchant/apply'
class='btn-apply'>申请入驻</
a>
</div>
"}
<!-- 正常内容 -->
{/eyou:mtlists}
```
### 2. 图片加载失败
```
{eyou:mtlists}
<img src="{$field.merchant_pic.
merchant_logo}"
alt="{$field.merchant_name}"
onerror="this.onerror=null;
this.src='/static/images/
default-merchant-logo.png';">
{/eyou:mtlists}
```
### 3. 调试模式
```
<!-- 查看返回的数据结构 -->
{eyou:mtlists}
<pre>{eyou:dump var="$field" /}</
pre>
{/eyou:mtlists}
```
通过以上详细介绍，您可以在易优CMS中充分利用 mtlists 标签展示商家列表，构建丰富的多商户功能界面。
