网站模板开发

模板控制 DCSHOP 前台的展示样式，包括商品列表、商品详情、下单页面、订单查询等。

前台模板文件结构

content/templates/
└── my_template/ # 模板目录
    ├── header.php # 公共头部（必须）
    ├── goods_list.php # 商品列表页（必须）
    ├── goods.php # 商品详情页（必须）
    ├── confirm.php # 订单确认页（必须）
    ├── order_query.php # 订单查询页（必须）
    ├── order_result.php # 订单结果页（必须）
    ├── page.php # 单页面模板
    ├── 404.php # 404页面
    ├── default.php # 模板信息文件（推荐）
    ├── default_setting.php # 模板设置页面（当前默认模板采用此方式）
    ├── options.php # 旧版 tpl_options 配置格式，保留兼容
    ├── preview.jpg # 模板预览图（建议 800x600）
    ├── css/ # 样式文件
    ├── js/ # 脚本文件
    └── img/ # 图片资源

必须文件说明

文件	说明	可用变量
`header.php`	公共头部，包含 HTML head、导航等	$site_name, $site_logo, $navs
`goods_list.php`	商品列表/首页	$goods_list, $sorts, $page_info
`goods.php`	商品详情页	$goods, $skus, $attach_fields
`confirm.php`	订单确认/支付页	$order, $payments
`order_query.php`	订单查询页	-
`order_result.php`	订单结果/卡密展示页	$order, $order_list, $deliver_content

常用模板变量

全局变量

// 站点信息
$site_name = Option::get('blogname');      // 站点名称
$site_url = DC_URL;                         // 站点URL
$site_logo = Option::get('site_logo');      // 站点Logo

// 导航菜单
$navs = $CACHE->readCache('navi');          // 导航数组

// 分类列表
$sorts = $CACHE->readCache('sort');         // 商品分类

// 当前用户
$is_login = ISLOGIN;                        // 是否登录
$user_id = UID;                             // 用户ID

商品列表变量 (goods_list.php)

// $goods_list 商品数组，每个元素包含：
[
    'id' => 1,                    // 商品ID
    'title' => '商品名称',         // 商品标题
    'cover' => '/uploads/xxx.jpg', // 封面图
    'price' => 1000,              // 价格（分）
    'stock' => 100,               // 库存
    'sales' => 50,                // 销量
    'sort_id' => 1,               // 分类ID
    'is_on_shelf' => 'y',         // 是否上架
]

// 分页信息
$page_info = [
    'total' => 100,               // 总数
    'page' => 1,                  // 当前页
    'limit' => 20,                // 每页数量
]

商品详情变量 (goods.php)

// $goods 商品详情
[
    'id' => 1,
    'title' => '商品名称',
    'cover' => '/uploads/xxx.jpg',
    'content' => '商品描述HTML',
    'price' => 1000,              // 原价（分）
    'stock' => 100,
    'sales' => 50,
    'is_sku' => 'y',              // 是否有规格
    'type' => 'goods_once',       // 商品类型
]

// $skus 规格列表（如果 is_sku='y'）
[
    [
        'sku' => '1-2',           // 规格ID组合
        'sku_name' => '红色/大号',
        'stock' => 50,
        'guest_price' => 1000,    // 游客价（分）
        'user_price' => 900,      // 会员价（分）
    ],
    // ...
]

// $attach_fields 附加字段
[
    ['name' => '邮箱', 'required' => 'y'],
    ['name' => '备注', 'required' => 'n'],
]

模板配置方式

当前系统中默认模板主要使用 default_setting.php 形式提供设置页面，旧版 options.php / TplOptions 保留兼容。新模板建议参考默认模板的 setting 文件，定义 plugin_setting_view() 和 plugin_setting()。

<?php
defined('DC_ROOT') || exit('access denied!');

function plugin_setting_view() {
    $storage = Storage::getInstance('default');
    $primary = $storage->getValue('primary_color') ?: '#1677ff';
    ?>
    <form class="layui-form" id="form" method="post">
        <div class="layui-form-item">
            <label class="layui-form-label">主题色</label>
            <div class="layui-input-block">
                <input type="text" name="primary_color" value="<?= htmlspecialchars($primary) ?>" class="layui-input">
            </div>
        </div>
        <button class="layui-btn" lay-submit lay-filter="submit">保存</button>
    </form>
    <?php
}

function plugin_setting() {
    $storage = Storage::getInstance('default');
    $storage->setValue('primary_color', Input::postStrVar('primary_color'));
    Output::ok();
}

在模板中读取配置

// 旧版方式：使用 _g() 函数读取 TplOptions 数据
$site_title = _g('site_title') ?: '默认标题';
$primary_color = _g('primary_color') ?: '#1890ff';

// 获取全部旧版模板参数
$templateOptions = TplOptions::getInstance()->getTemplateOptions();
$show_sales = $templateOptions['show_sales'] ?? 'y';

其他模板类型

类型	目录	入口/说明
用户后台模板	`content/user_templates/slug/`	模板信息文件通常为 `slug.php`，用于用户中心/移动端 APP 页。
底部导航模板	`content/bottom_nav_templates/slug/`	包含 `slug.php`、`slug_setting.php`、`render.php`，负责移动端底部导航输出。
博客模板	`content/blog_templates/slug/`	用于文章列表、详情、分类归档等内容站页面。

分店模板回落：分店前台模板和用户后台模板未设置时默认使用 default；历史数据中的 em_null_tpl 在前台/用户后台运行时也应回落为 default，避免页面不可访问。

常用辅助函数

函数	说明	示例
`Url::goods($id)`	生成商品详情URL	`/goods/1.html`
`Url::sort($id)`	生成分类URL	`/sort/1.html`
`formatMoney($fen)`	格式化金额（分转元）	`10.00`
`smartDate($timestamp)`	智能日期格式化	`3分钟前`
`subString($str, $len)`	截取字符串	-

深色模式支持

模板必须支持深色模式，通过检测 html[data-theme="dark"] 属性：

<style>
/* 浅色模式 */
body { background: #f5f5f5; color: #333; }
.card { background: #fff; }

/* 深色模式 */
html[data-theme="dark"] body { background: #1a1a1a; color: #e0e0e0; }
html[data-theme="dark"] .card { background: #1e1e1e; }
</style>

开发文档

网站模板开发

前台模板文件结构

必须文件说明

常用模板变量

全局变量

商品列表变量 (goods_list.php)

商品详情变量 (goods.php)

模板配置方式

在模板中读取配置

其他模板类型

常用辅助函数

深色模式支持