首页模板开发教程

概述

本文档定义了在 public/template/web/{模板名}/ 目录下开发首页及相关页面的规范。

目录结构规范

public/template/web/{模板标识名}/
├── {模板标识名}.php          # 模板配置文件（必须）
├── index.html                # 首页模板（必须）
├── header.html               # 页头组件（可选）
├── footer.html               # 页脚组件（可选）
├── announcement.html         # 公告列表页（必须
├── announcement_detail.html  # 公告详情页（必须）
├── xxx.html                  # 自定义页面（可选）
├── template.png              # 模板预览图（建议 400x300）
└── assets/                   # 静态资源（可选，按需添加）
    ├── css/
    ├── js/
    ├── images/
    └── fonts/

注意：assets 目录不是必须的。如果使用外部 CDN 或系统自带资源，可以不创建。

配置文件详解

模板配置文件 {模板名}.php 必须包含以下三个函数：

1. {模板名}_MetaData() - 模板元数据（必须）

<?php
function {模板名}_MetaData()
{
    return [
        "DisplayName" => "简洁首页",           // 后台显示的名称
        "APIVersion"  => "1.0.0",              // API版本号
        "HelpDoc"     => "http://www.sib.cc/"  // 帮助文档链接（可选）
    ];
}

2. {模板名}_ConfigOptions() - 首页配置字段（必须）

定义首页模板后台可配置的字段，通过 $config.web_meta.xxx 访问。

function {模板名}_ConfigOptions()
{
    return [
        // 单行文本 - 标题类
        [
            'key'     => 'hero_title',
            'title'   => '首页主标题',
            'type'    => 'input',
            'default' => '',
            'options' => [],
            'tip'     => '显示在首页Banner区域的主标题',
        ],
        // 单行文本 - 联系方式
        [
            'key'     => 'contact_email',
            'title'   => '联系邮箱',
            'type'    => 'input',
            'default' => '',
            'options' => [],
            'tip'     => '显示在联系我们页面的邮箱地址',
        ],
        // 多行文本 - 富文本内容
        [
            'key'     => 'welcome_content',
            'title'   => '欢迎语内容',
            'type'    => 'textarea',
            'default' => '',
            'options' => [],
            'tip'     => '支持HTML标签，显示在首页欢迎区域',
        ],
        // 多行文本 - 页脚代码
        [
            'key'     => 'footer_html',
            'title'   => '页脚自定义代码',
            'type'    => 'textarea',
            'default' => '',
            'options' => [],
            'tip'     => '支持HTML/JS代码，显示在页面底部',
        ],
        // 下拉选择 - 主题风格
        [
            'key'     => 'theme_style',
            'title'   => '主题风格',
            'type'    => 'select',
            'default' => 'default',
            'options' => [
                'default' => '默认风格',
                'dark'    => '深色模式',
                'light'   => '浅色模式',
            ],
            'tip'     => '选择站点整体配色方案',
        ],
        // 下拉选择 - 布局模式
        [
            'key'     => 'layout_mode',
            'title'   => '首页布局',
            'type'    => 'select',
            'default' => 'standard',
            'options' => [
                'standard' => '标准布局',
                'full'     => '全屏布局',
                'compact'  => '紧凑布局',
            ],
            'tip'     => '选择首页的整体布局风格',
        ],

    ];
}

3. {模板名}_ArticleArea() - 文章配置字段（可选）

定义文章详情页的自定义字段，通过 $config.article_meta.xxx 访问。

function {模板名}_ArticleArea()
{
    return [
        [
            'key'     => 'article_sidebar',
            'title'   => '文章侧边栏',
            'type'    => 'textarea',
            'default' => '<div>联系客服</div>',
            'tip'     => '支持HTML',
        ],
    ];
}

全局可用变量（所有页面共用）

1. 站点信息 `$site`

变量	类型	示例值
`$site['name']`	string	`"思博云"`
`$site['title']`	string	`"思博云 - 云主机销售系统"`
`$site['favicon']`	string	`"/favicon.ico"`
`$site['description']`	string	`"专业云主机服务提供商"`
`$site['keywords']`	string	`"云主机,VPS,服务器"`

2. 自定义配置

配置来源	访问方式	说明
ConfigOptions()	`$config.web_meta.xxx`	首页配置
CartArea()	`$config.cart_meta.xxx`	购物车配置
ArticleArea()	`$config.article_meta.xxx`	文章页配置

3. 商品分类 `$cates`

所有页面都可用的商品分类数组，用于展示分类导航。

示例数据：

$cates = [
    [
        'id'   => 1,
        'name' => '云服务器',
        'pid'  => 0,  // 0表示顶级分类
    ],
    [
        'id'   => 2,
        'name' => '高防IP',
        'pid'  => 0,
    ],
    [
        'id'   => 3,
        'name' => '香港节点',
        'pid'  => 1,  // 父分类ID为1（云服务器）
    ],
    [
        'id'   => 4,
        'name' => '美国节点',
        'pid'  => 1,
    ],
];

页面详解

1. index.html - 首页

路由： /

1.1 页面基础 SEO 变量

变量名	类型	说明
`{$page_title}`	string	页面标题，覆盖默认 `$site.title`
`{$page_keywords}`	string	SEO 关键词
`{$page_description}`	string	SEO 描述

模板中定义：

{php}
$page_title = $site['title'];
$page_keywords = $site['keywords'];
$page_description = $site['description'];
{/php}

1.2 自定义配置变量

从 $config 中读取的后台配置，后台「系统配置 → 自定义配置」中维护：

配置来源	访问方式	说明
ConfigOptions()	`{$config.web_meta.xxx}`	首页配置
ArticleArea()	`{$config.article_meta.xxx}`	文章页配置

1.3 动态内容数据

公告列表（Announcements）

变量名	类型	说明
`{$announcements}`	array	首页展示的最新公告列表（通常取 3-6 条）

数组元素结构：

字段名	类型	说明
`{$a.id}`	int	公告 ID
`{$a.title}`	string	公告标题
`{$a.content}`	string	公告内容（HTML 或纯文本）
`{$a.publish_time}`	string	发布时间（格式：YYYY-MM-DD HH:ii:ss）
`{$a.views}`	int	浏览次数
`{$a.category.name}`	string	公告分类名称

示例数据：

$announcements = [
    [
        'id'           => 1,
        'title'        => '系统维护通知',
        'content'      => '<p>将于今晚进行系统维护...</p>',
        'publish_time' => '2025-01-15 10:00:00',
        'views'        => 128,
        'category'     => ['name' => '系统公告'],
    ],
    [
        'id'           => 2,
        'title'        => '新年优惠活动',
        'content'      => '<p>春节期间全场8折...</p>',
        'publish_time' => '2025-01-10 09:00:00',
        'views'        => 256,
        'category'     => ['name' => '活动优惠'],
    ],
];

模板中使用（PHP变量方式）：

{foreach $announcements as $a}
<div class="announcement-item">
    <span class="badge">{$a.category.name}</span>
    <h3>{$a.title}</h3>
    <p>{:mb_substr(strip_tags($a['content']),0,40)}...</p>
    <span>{:date('Y-m-d', strtotime($a['publish_time']))}</span>
    <span>浏览：{$a.views}</span>
    <a href="/announcementdetail/{$a.id}">查看详情</a>
</div>
{/foreach}

或通过 JS API 获取：

<div id="noticeCards"></div>
<script>
fetch('/api/article/getList?limit=3')
  .then(r => r.json())
  .then(res => {
    if (res.code === 1) {
      document.getElementById('noticeCards').innerHTML =
        res.data.data.map(a => `
          <a href="/announcementdetail/${a.id}" class="list-group-item">
            <div class="d-flex justify-content-between">
              <span>${a.title}</span>
              <small class="text-muted">${new Date(a.publish_time).toLocaleDateString()}</small>
            </div>
          </a>
        `).join('');
    }
  });
</script>

1.4 全局辅助变量

变量名	类型	说明
`{$user}`	object	当前登录用户信息，未登录为 null
`{$user.username}`	string	用户名
`{$user.email}`	string	用户邮箱

使用逻辑：

{if $user}
    <!-- 已登录：显示控制台入口 -->
    <a href="/clientarea" class="btn btn-primary">访问控制台</a>
    <span>欢迎，{$user.username}</span>
{else}
    <!-- 未登录：显示注册/登录 -->
    <a href="/register" class="btn btn-primary">免费试用</a>
    <a href="/login" class="btn btn-outline">立即登录</a>
{/if}

2. announcement.html - 公告列表页

路由： /announcement

URL 参数：

?cate={id} - 按分类筛选
?page={n} - 分页，默认第1页

专属变量：

变量	类型	示例数据
`$list`	array	文章列表数组
`$category`	array	公告分类列表
`$cateMap`	array	分类ID映射表
`$currentCateId`	string/int	`'all'` 或 `1`
`$page`	int	`1`
`$lastPage`	int	`5`

示例数据：

// $list - 文章列表
$list = [
    [
        'id'           => 1,
        'title'        => '系统维护通知',
        'content'      => '<p>将于今晚进行系统维护...</p>',
        'publish_time' => '2025-01-15 10:00:00',
        'views'        => 128,
    ],
    [
        'id'           => 2,
        'title'        => '新年优惠活动',
        'content'      => '<p>春节期间全场8折...</p>',
        'publish_time' => '2025-01-10 09:00:00',
        'views'        => 256,
    ],
];


// $category - 公告分类
$category = [
    ['id' => 1, 'name' => '系统公告', 'nickname' => '', 'description' => '', 'keywords' => ''],
    ['id' => 2, 'name' => '活动优惠', 'nickname' => '优惠活动', 'description' => '最新优惠活动', 'keywords' => '优惠,活动'],
];


// $cateMap - 分类映射
$cateMap = [
    1 => ['id' => 1, 'name' => '系统公告', ...],
    2 => ['id' => 2, 'name' => '活动优惠', ...],
];

3. announcement_detail.html - 公告详情页

路由： /announcementdetail/{id}

专属变量：

变量	类型	示例数据
`$article`	array	当前文章详情
`$cateName`	string	`'系统公告'`
`$prev`	array/null	上一篇或null
`$next`	array/null	下一篇或null

示例数据：

// $article - 当前文章
$article = [
    'id'           => 1,
    'title'        => '系统维护通知',
    'content'      => '<p>尊敬的用户：</p><p>将于今晚进行系统维护...</p>',
    'publish_time' => '2025-01-15 10:00:00',
    'views'        => 128,
    'tags'         => '维护,通知,系统',
];


// $cateName - 分类名称
$cateName = '系统公告';


// $prev - 上一篇（可能为null）
$prev = [
    'id'    => 0,  // 如果是第一篇，id可能为0
    'title' => '无',
];
// 或
$prev = null;  // 没有上一篇


// $next - 下一篇（可能为null）
$next = [
    'id'    => 2,
    'title' => '新年优惠活动',
];
// 或
$next = null;  // 没有下一篇

4. 自定义页面 xxx.html

路由规则： /page/{文件名}

例如创建 about.html，访问地址为 /page/about

可用变量：

所有全局变量（$site, $config.web_meta, $cates）
自定义页面无专属变量

系统页面路由汇总

路由	对应文件	说明
`/`	`index.html`	首页
`/cart`	系统内置	商品列表/购物车
`/cart?group={id}`	系统内置	按分类筛选商品
`/announcement`	`announcement.html`	公告列表
`/announcement?cate={id}`	`announcement.html`	按分类筛选公告
`/announcementdetail/{id}`	`announcement_detail.html`	公告详情
`/page/{name}`	`{name}.html`	自定义页面

模板语法

1. PHP 代码块

{php}
$page_title = $site['title'];
{/php}

2. 变量输出

{$variable}
{$variable|default='默认值'}

3. 条件判断

{if condition="$user"}
    欢迎，{$user.username}
{else /}
    <a href="/login">登录</a>
{/if}

4. 循环

{foreach $announcements as $a}
    <a href="/announcementdetail/{$a.id}">{$a.title}</a>
{/foreach}

5. 包含文件

{include file='web/{模板名}/header' /}
{include file='web/{模板名}/footer' /}

静态资源引用规范

使用本地 assets（可选）

<!-- CSS -->
<link href="/template/web/{模板名}/assets/css/style.css" rel="stylesheet">


<!-- JS -->
<script src="/template/web/{模板名}/assets/js/main.js"></script>


<!-- 图片 -->
<img src="/template/web/{模板名}/assets/images/logo.png">

使用外部 CDN

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>

开发 checklist

[ ] 创建模板目录 public/template/web/{模板名}/
[ ] 创建配置文件 {模板名}.php
[ ] 实现 MetaData() 函数（必须）
[ ] 实现 ConfigOptions() 函数（必须）
[ ] 实现 CartArea() 函数（可选）
[ ] 实现 ArticleArea() 函数（可选）
[ ] 函数命名与目录名完全一致（区分大小写）
[ ] 创建 index.html 首页模板
[ ] 创建 announcement.html 公告列表页
[ ] 创建 announcement_detail.html 公告详情页
[ ] （可选）创建自定义页面如 about.html
[ ] 添加 template.png 预览图（建议 400x300）
[ ] 测试所有配置字段在后台正常显示
[ ] 测试各页面前端正常渲染

注意事项

函数命名必须与目录名一致，包括大小写
三个配置函数：MetaData() 和 ConfigOptions() 必须实现，CartArea() 可选
ConfigOptions 中的 key 要唯一，建议使用前缀避免冲突
assets 目录可选，不需要时可以不创建
template.png 建议尺寸 400x300，用于后台预览
路径使用绝对路径，以 /template/web/ 开头
所有页面都可用 $cates 展示商品分类导航

首页模板开发教程

概述

目录结构规范

配置文件详解

1. {模板名}_MetaData() - 模板元数据（必须）

2. {模板名}_ConfigOptions() - 首页配置字段（必须）

3. {模板名}_ArticleArea() - 文章配置字段（可选）

全局可用变量（所有页面共用）

1. 站点信息 `$site`

2. 自定义配置

3. 商品分类 `$cates`

页面详解

1. index.html - 首页

1.1 页面基础 SEO 变量

1.2 自定义配置变量

1.3 动态内容数据

公告列表（Announcements）

1.4 全局辅助变量

2. announcement.html - 公告列表页

3. announcement_detail.html - 公告详情页

4. 自定义页面 xxx.html

系统页面路由汇总

模板语法

1. PHP 代码块

2. 变量输出

3. 条件判断

4. 循环

5. 包含文件

静态资源引用规范

使用本地 assets（可选）

使用外部 CDN

开发 checklist

注意事项

chat_bubble_outline 评论 0

edit 发表评论

概述

目录结构规范

配置文件详解

1. {模板名}_MetaData() - 模板元数据（必须）

2. {模板名}_ConfigOptions() - 首页配置字段（必须）

3. {模板名}_ArticleArea() - 文章配置字段（可选）

全局可用变量（所有页面共用）

1. 站点信息 $site

2. 自定义配置

3. 商品分类 $cates

页面详解

1. index.html - 首页

1.1 页面基础 SEO 变量

1.2 自定义配置变量

1.3 动态内容数据

公告列表（Announcements）

1.4 全局辅助变量

2. announcement.html - 公告列表页

3. announcement_detail.html - 公告详情页

4. 自定义页面 xxx.html

系统页面路由汇总

模板语法

1. PHP 代码块

2. 变量输出

3. 条件判断

4. 循环

5. 包含文件

静态资源引用规范

使用本地 assets（可选）

使用外部 CDN

开发 checklist

注意事项

chat_bubble_outline 评论 0

edit 发表评论

1. 站点信息 `$site`

3. 商品分类 `$cates`