clearlove2.1
1# 主题开发文档
2
3ClearLove 表白墙的主题机制基于「CSS 变量 + 样式覆盖」，可在后台 **网站设置 → 主题管理**
4中一键切换，支持自定义背景图片，自定义程度高且无需修改任何 Go 代码。
5
6## 1. 主题目录结构
7
8主题以目录形式存放于 `data/themes/<主题名>/`：
9
10```
11data/themes/my-love/
12├── theme.json # 主题清单（必须）
13└── style.css # 主题样式（必须）
14```
15
16后台「主题安装」处直接上传 zip 包即可（zip 内需包含 `theme.json` 与 `style.css`）。
17
18## 2. theme.json 清单
19
20```json
21{
22 "name": "my-love",
23 "version": "1.0.0",
24 "author": "你的名字",
25 "description": "粉色梦幻主题"
26}
27```
28
29| 字段 | 必填 | 说明 |
30|---|---|---|
31| name | 是 | 主题名（将作为安装目录名，建议英文/数字/短横线） |
32| version | 否 | 版本号 |
33| author | 否 | 作者 |
34| description | 否 | 描述 |
35
36## 3. style.css 覆盖方式
37
38主题 CSS 会在 `/theme.css` 中输出，并在 `/static/app.css` 之后加载，因此可以直接覆盖任意样式。
39推荐先通过 CSS 变量整体换肤：
40
41```css
42:root {
43 --clv-accent: #6ea8ff; /* 主色（按钮、悬停、点赞） */
44 --clv-accent-2: #7ee0c3; /* 辅助色（渐变另一端） */
45 --clv-accent-soft: rgba(110,168,255,.12);
46 --clv-bg: #f2f7ff; /* 页面背景色 */
47 --clv-bg-image: url('/uploads/2026/bg.webp'); /* 页面背景图 */
48 --clv-card: #ffffff; /* 卡片背景 */
49 --clv-text: #1f2733;
50 --clv-muted: #8a93a3;
51 --clv-border: #e6ecf5;
52 --clv-radius: 18px; /* 卡片圆角 */
53 --clv-radius-sm: 10px;
54 --clv-shadow: 0 4px 20px rgba(31,39,51,.08);
55 --clv-font: "PingFang SC", "Microsoft YaHei", sans-serif;
56}
57```
58
59也可直接针对选择器做深度定制，例如：
60
61```css
62/* 顶部导航透明磨砂 */
63.topbar { background: rgba(255,255,255,.7); }
64
65/* 卡片悬浮上浮动效 */
66.post-card:hover { transform: translateY(-6px); box-shadow: 0 12px 30px rgba(0,0,0,.12); }
67
68/* 隐藏悬浮发帖按钮、改用固定底栏时 */
69.fab { display: none; }
70```
71
72## 4. 可用选择器速查
73
74| 选择器 | 说明 |
75|---|---|
76| `.topbar / .brand / .topnav` | 顶部导航 |
77| `.masonry / .post-card / .card-head` | 瀑布流与卡片 |
78| `.content / .media-grid / .video` | 帖子内容与媒体 |
79| `.card-actions / .act / .like-btn` | 点赞与评论按钮 |
80| `.preview-comments / .view-all` | 卡片内评论预览 |
81| `.detail-card / .comments / .comment-item` | 详情页 |
82| `.compose / .auth / .progress` | 表单与上传进度 |
83| `.fab / .notice-bar / .site-footer` | 悬浮按钮、公告与页脚 |
84| `.admin-body / .sidebar / .table / .stat` | 后台界面 |
85
86## 5. 自定义背景图片
87
88两种方式：
89
901. 后台 **网站设置 → 主题管理 → 自定义背景图地址** 填入图片地址（可上传后使用 `/uploads/...` 路径），
91 会生成 `--clv-bg-image` 变量并应用于全站。
922. 在主题 `style.css` 中自行定义 `--clv-bg-image` 或直接写 `body { background-image: ... }`。
93
94## 6. 注意事项
95
96- 主题 CSS 中禁止引用国外 CDN（如 fonts.googleapis.com），如需字体请内联或使用系统字体。
97- 图标请使用内联 SVG（可参考 `web/static/app.js` 中的写法）。
98- 后台「删除主题」仅能删除 `data/themes` 下的自定义主题，内置 `default` 主题不可删除。