10a 主题开发详细教程

文档版本：正式版 1.0.3 · 配套：插件开发教程 · 部署教程

按本文可完成一套 SPA 主题（首页 + 会员中心皮肤），并用官方构建脚本发布到 public/themes/。

欢迎加入制作团队：QQ 群

---

主题类型对照

内部 type	输出目录	用途
home（manifest 里可写 web）	public/themes/web/{name}/	官网首页
clientarea	public/themes/clientarea/{name}/	会员中心 / 控制台壳层配色
cart	public/themes/cart/{name}/	购物车相关皮肤

内置参考：default、cloud、classic。文档配套示例：frontend/themes/starter/。

---

开发方式怎么选

方式	适用	改动面
仅 CSS（推荐）	绝大多数站点	只改颜色、圆角、区块观感，不碰 Vue 业务
CSS + theme.json 配置	需要后台可调变量	config 注入为 --kd-theme-*
.tpl SSR	兼容魔方旧主题 / 要服务端 HTML	另见 10 主题与 SSR

本文聚焦 SPA + CSS。

---

第一步：创建主题源码目录

在财务源码仓库中：

frontend/themes/starter/
  theme.json
  screenshot.svg          （可选）
  home/theme.css
  clientarea/theme.css
  cart/theme.config       （可选，购物车）

theme.json

{
  "name": "starter",
  "title": "入门示例主题",
  "version": "1.0.0",
  "author": "KeDe Docs",
  "description": "文档配套：演示 CSS 作用域与配置变量",
  "screenshot": "screenshot.svg",
  "types": ["web", "clientarea", "cart"],
  "config": {
    "accent": "#0f766e",
    "hero-from": "#0f766e",
    "hero-to": "#14b8a6",
    "card-radius": "10px"
  }
}

说明：

• name 只能字母数字下划线，与目录名一致
• types 写 web 对应内部 home
• config 键会变成 CSS 变量 --kd-theme-accent 等（连字符保留）

home/theme.css

/* 必须带作用域，避免污染未激活主题 */
.kd-theme-scope-home[data-kd-theme-home="starter"] .hero-slide {
  background: linear-gradient(
    125deg,
    var(--kd-theme-hero-from, #0f766e),
    var(--kd-theme-hero-to, #14b8a6)
  );
}

.kd-theme-scope-home[data-kd-theme-home="starter"] .sky-card {
  border-radius: var(--kd-theme-card-radius, 10px);
}

clientarea/theme.css

.kd-theme-scope-clientarea[data-kd-theme-clientarea="starter"] {
  --console-accent: var(--kd-theme-accent, #0f766e);
}

.kd-theme-scope-clientarea[data-kd-theme-clientarea="starter"] .console-nav-item.active {
  color: var(--kd-theme-accent, #0f766e);
}

---

第二步：构建到 public

在 kede-finance 根目录执行：

node frontend/theme-sdk/scripts/build-themes.mjs

成功后应出现：

public/themes/web/starter/theme.css
public/themes/clientarea/starter/theme.css

也可只改 public/themes/... 做快速试验，但长期维护请改 frontend/themes 再构建。

---

第三步：后台启用

1. 后台 → 主题模板 → 扫描（或刷新列表）
2. 在「官网 / 会员中心 / 购物车」分别选择 starter（入门示例主题）
3. 前台强刷（Ctrl+F5）查看首页与控制台配色

公开接口返回示例（GET /home/content/siteConfig）：

{
  "theme": { "home": "starter", "clientarea": "starter", "cart": "default" },
  "theme_config": { "home": { "accent": "#0f766e" } }
}

前台 applyThemes() 会：

1. 给 body 写 data-kd-theme-home="starter" 等
2. 注入 CSS 变量
3. 加载 /themes/web/starter/theme.css

---

第四步（可选）：使用 Theme SDK 组件

SDK 位置：frontend/theme-sdk/。在前台 Vue 中：

<script setup lang="ts">
import { ThemeProductGrid } from '@theme-sdk'
</script>

<template>
  <ThemeProductGrid :products="list" />
</template>

组件契约见 frontend/theme-sdk/src/types.ts。注意：改 Vue 页面属于二次开发，升级时可能冲突；纯 CSS 主题升级更平滑。

---

购物车主题提示

购物车目录文件较多（public/themes/cart/default/assets/）。起步时：

1. 复制 default 为新名称
2. 只改 theme.config / 主色 CSS 变量
3. 后台激活 cart 类型主题后验证下单页

深度结构见 10 主题与 SSR。

---

.tpl SSR（摘要）

仅当需要魔方旧主题或服务端 HTML 时开启：

• 配置 theme.ssr_mode = tpl
• 主题目录提供 index.tpl 等
• 访问 /tpl/home（生产伪静态需包含 /tpl 规则）

模板语法为 Smarty 子集，变量默认有 site、theme_config、year。

---

分发主题包

给客户的 zip 建议直接基于 已构建 的 public/themes 内容：

web/starter/theme.css
web/starter/theme.json   （若有）
clientarea/starter/theme.css

客户解压到站点 public/themes/ 对应目录后扫描启用。

---

调试

现象	排查
样式不生效	是否激活该 type；选择器作用域是否写对 data-kd-theme-*
变量无效	theme.json 的 config 键名是否与 CSS var(--kd-theme-*) 一致
扫描不到	name 与目录是否一致；文件是否在 public/themes
构建无输出	是否在正确目录执行 build-themes.mjs；theme.json JSON 是否合法

也可使用仓库脚本：php scripts/diagnose-theme.php（若存在）。

---

安全与合规

• 主题 CSS/JS 不要外链未知第三方脚本
• 不要在主题中嵌入授权绕过或抓取内部通信密钥的逻辑
• 公开文档不提供授权站内部部署与管理 API

---

相关链接

• 10 主题与 SSR（概览）
• 04a 插件开发详细教程
• 源码：frontend/theme-sdk/README.md、frontend/themes/README.md