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

欢迎加入制作团队:QQ 群


主题类型对照

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

本文使用 starter 作为示例名,不代表正式包预装该主题。当前站点可用主题以后台列表为准。

普通用户通过后台上传主题主包即可。以下源码开发步骤仅用于自行开发主题,不是业务系统安装前提。


开发方式怎么选

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

本文聚焦 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

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

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 中:

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 主题管理。


.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

将上述目录放入主包的 themes/ 下,通过后台 上传主题 提交主包,再到 选择主题 启用。完整包格式见主题管理。

导航使用 /home、/store、/login、/register、/console 等真实路径,不重新引入旧 Hash 入口。保留正常页脚内的 Powered by Mercuryseek 及其链接,不使用悬浮定位。


调试

现象 排查
样式不生效 是否激活该 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 不要外链未知第三方脚本
  • 不修改系统认证与安全流程,不收集账号凭据
  • 主题包、截图和示例中不包含真实凭据与客户资料

相关链接

下载文档
原始 Markdown 文件