面向生态开发者的工程文档

主题开发模型

主题用于替换 ClayBBS 的展示层。主题启用后，系统会优先查找主题目录中同路径视图；找不到时回退到默认视图。

主题命名规范

• slug：使用稳定英文标识，例如 clay_light。
• 视图路径：必须和默认视图相同路径，才能完成覆盖。
• 资源路径：建议统一放在主题 assets/ 下，不要污染主系统 assets/。
• 版本：主题升级应保持同一 slug，并递增版本号。

主题目录结构

clay_light/
├── market.json
├── theme.json
├── views/
│   ├── web/home/index.php
│   ├── web/thread/show.php
│   └── layouts/topbar.php
├── assets/
│   ├── css/theme.css
│   └── js/theme.js
└── README.md

• theme.json：论坛端主题识别文件。
• views/：按默认视图路径覆盖页面。
• assets/：主题自己的 CSS、JS、图片资源。

theme.json / market.json

{
  "type": "theme",
  "slug": "clay_light",
  "name": "Clay Light",
  "version": "1.0.0",
  "api_version": "1.0.0",
  "min_core_version": "1.0.0",
  "description": "一个主题开发示例",
  "author": "你的名字"
}

主题 slug 同样要求稳定。用户安装后，升级包应沿用同一个 slug。

api_version 声明主题依赖的 Extension API 版本，论坛切换主题时会检查兼容性。

market.json 用于提交官方市场；theme.json 用于论坛本地识别。

视图覆盖规则

默认视图：

app/views/web/home/index.php

主题覆盖：

themes/clay_light/views/web/home/index.php

只覆盖你需要改动的页面即可，不需要复制全部默认视图。这样更容易跟随官方升级。

资源组织

assets/
├── css/theme.css
├── js/theme.js
└── images/logo.svg

• CSS/JS 文件命名要清晰，不要覆盖全局变量太多。
• 图片尽量压缩，避免主题包体积过大。
• 如果引入第三方库，要说明来源和许可协议。

样式与交互规范

• 移动端优先，避免大块固定宽度布局。
• 兼容暗色模式，优先使用系统 CSS 变量。
• 按钮、表单、列表保持简洁，不要过度装饰。
• 不要移除必要的 CSRF 字段、隐藏字段和提交按钮 name/value。
• 图片、头像、帖子卡片需要考虑长内容和空状态。

兼容与表单规则

• 不要删除表单中的 csrf_field()。
• 不要修改后端依赖的 name 字段，例如标题、内容、板块 ID。
• 保留登录态、未登录态、空状态、错误提示。
• 列表页要测试长标题、无头像、无图片、多图、暗色模式。
• 主题只覆盖展示层，不应直接写数据库。

授权与付费主题

付费主题同样使用市场授权注入。主题包声明 license.required=true 后，论坛在安装、启用和渲染时会校验授权；授权无效时自动回退默认主题。

{
  "type": "theme",
  "slug": "premium_dark",
  "name": "Premium Dark",
  "version": "1.0.0",
  "license": {
    "required": true,
    "protected_features": ["theme_activate", "theme_render"]
  }
}

• 官方站只会向已购买并绑定域名的站点注入有效授权。
• 论坛端启用付费主题前会校验授权。
• 授权失效或域名不匹配时，不会继续渲染该主题。

主题打包发布

1. 复制示例主题工程。
2. 按需覆盖页面视图，不要一次性复制全部默认视图。
3. 补充主题 CSS/JS。
4. 测试登录/未登录、移动端、暗色模式、空状态和长内容。
5. 确认没有运行数据、日志、上传文件和密钥。
6. 压缩主题根目录并提交官方审核。

主题示例工程