# dnfs 自定义主题说明

树状笔记（dnfs）支持通过**特殊节点**自定义整个界面的样式：无需改代码、无需重新部署，发布一个节点即可换肤或深度改造界面，随时一键还原。

两类样式节点：

| 类型 | 表单选项 | 能力 | 适用场景 |
|---|---|---|---|
| `theme` | 主题变量 | 仅覆盖 CSS 变量（`:root` 换肤） | 改配色、圆角、阴影，最稳妥 |
| `style` | 界面样式 | 注入任意 CSS | 改布局、加特效、深度定制 |

---

## 1. 快速上手

### 发布步骤

1. 登录后打开「树状笔记」，进入自己的目标节点（样式节点发布在**谁拥有**的节点下，权限见下）
2. 在「节点操作」表单中，将**节点类型**选为 `主题变量` 或 `界面样式`
3. 在「节点内容」中填写变量或 CSS（格式见后文）
4. 可选：勾选「离开本节点后仍保持生效」（`persist`）
5. 提交——内容经 AI 审核通过后即时生效

### 发布权限

- **节点拥有者或管理员**可发布样式节点（后端强制，前端面板仅做展示切换）
- 在他人节点下提交样式节点会被拒绝（HTTP 403）
- 根层（pid=0）无拥有者，仅管理员可在根层发布
- 所有样式节点内容都会经过 **AI 内容审核**

### 生命周期

| 模式 | 生效范围 | 移除时机 |
|---|---|---|
| 默认（节点作用域） | 进入该节点所在层时生效 | 切换/返回节点时自动还原 |
| `persist`（勾选保持） | 一旦访问即全局保持，跨节点生效 | 用户面板点「还原界面样式」，或停用对应节点 |

- 每个样式节点卡片上有「停用样式/启用样式」与「审计源码」按钮，可逐个控制
- 用户面板的「**还原界面样式**」一键清除全部注入样式（含 persist），本会话内 persist 样式不再自动注入（刷新页面恢复）

---

## 2. theme 节点（主题变量）

### 格式

「节点内容」中**每行一个变量**，分号可选：

```
--accent: #e8853a
--bg: #0a0f0a;
```

### 规则（后端强制）

- 变量名：必须以 `--` 开头，仅含字母/数字/`-`/`_`，长度 ≤ 64
- 变量值：非空，长度 ≤ 256，**不得包含 `{` `}` `<` `>`**（防止逃逸 `:root` 上下文注入任意规则）
- 条数：1 ~ 64 条
- 未列出的变量保持站点默认值，可只覆盖关心的几项

### 可覆盖变量清单

默认值（亮色 / 系统暗色模式）：

| 变量 | 亮色默认 | 暗色默认 | 作用 |
|---|---|---|---|
| `--bg` | `#fdf6ee` | `#1e1712` | 页面背景 |
| `--fg` | `#4a3728` | `#f0e4d8` | 主文字 |
| `--fg-secondary` | `#8c7260` | `#a08c78` | 次要文字 |
| `--card` | `#ffffff` | `#2a2119` | 卡片背景 |
| `--card-hover` | `#fff7ef` | `#342a20` | 卡片悬停背景 |
| `--border` | `#f0e0cc` | `#3e3228` | 边框 |
| `--border-light` | `#f7ecdd` | `#342a20` | 浅边框 |
| `--muted` | `#b89b7a` | `#8c7a66` | 弱化元素 |
| `--accent` | `#e8853a` | `#e8934a` | 品牌强调色 |
| `--accent-dark` | `#cf6b1f` | `#f0a060` | 强调色深阶 |
| `--accent-soft` | `rgba(232,133,58,.10)` | `rgba(232,147,74,.12)` | 强调色底衬 |
| `--accent-glow` | `rgba(232,133,58,.25)` | `rgba(232,147,74,.20)` | 强调色辉光 |
| `--error` / `--error-bg` | `#d94f3d` / `#fef0ee` | `#e8685a` / `#3a2220` | 错误 |
| `--success` | `#5a9e6f` | `#6fb87f` | 成功 |
| `--warning` | `#d4922a` | `#e0a84a` | 警告 |
| `--shadow-sm` / `--shadow-md` | 浅棕阴影 | 深黑阴影 | 投影 |
| `--radius-sm` / `--radius-md` / `--radius-lg` | `10px` / `14px` / `20px` | 同左 | 圆角 |

> 站点会随系统 `prefers-color-scheme` 切换亮/暗两套默认值；theme 节点注入的变量对两种模式**同时生效**（注入的 `:root` 规则优先级高于媒体查询默认值）。

---

## 3. style 节点（任意 CSS）

### 格式

「节点内容」直接填写 CSS 文本，上限 256KB。

### 安全边界

- CSS 无法执行脚本，风险面仅为界面外观；滥用可随时一键还原
- js 特效节点仍运行在 iframe 沙箱中，与样式节点互不影响

### 常用选择器参考

| 选择器 | 对应元素 |
|---|---|
| `.box` | 页面主容器（宽 90%，max-width 720px） |
| `.card` | 节点卡片（含 `:hover`） |
| `.card h3` | 卡片标题（点击进入子节点） |
| `.card-owner` / `.owner-avatar` / `.owner-name` | 发帖人头像与昵称 |
| `.card-stats` / `.stat-item` | 观看/点赞/分享统计 |
| `.card-actions` / `.act-btn`（`.act-edit` `.act-move` `.act-del`） | 卡片操作按钮 |
| `.searchbox` / `.searchbox-input` / `.searchbox-btn` | 顶部搜索框 |
| `.userpanel` / `.minimap` / `.movebar` | 用户面板 / 右侧导航 / 底部移动条 |
| `.tag` | 导航标签 |
| `.node-form` | 底部节点编辑卡 |
| `.sp-code` / `.sp-actions` / `.sp-note` | 特殊节点卡片内元素 |
| `.footer` | 页脚 |
| `body::before` / `body::after` | 点阵底纹 / 顶部暖光（可被覆盖改背景效果） |

### 编写注意事项

- **层叠上下文**：全屏覆盖层建议 `z-index ≤ 9998`（`9999` 被 js 特效 iframe 占用）
- **不拦截交互**：覆盖层务必加 `pointer-events: none`
- **避免动画 `transform`** 作用于卡片祖先：会使 `position: fixed` 后代（如 minimap、特效）定位异常
- 修改 `--accent-glow` 等含 `rgba()` 的值在 theme 节点中是允许的（不含禁字符）

---

## 4. 示例

### 4.1 极客终端风

先发 theme 节点（磷光绿配色）：

```
--bg: #0a0f0a
--fg: #33ff66
--fg-secondary: #1f9944
--card: #0d140d
--card-hover: #111a11
--border: #1a331f
--border-light: #142614
--muted: #2a6b3a
--accent: #33ff66
--accent-dark: #00cc44
--accent-soft: rgba(51, 255, 102, 0.08)
--accent-glow: rgba(51, 255, 102, 0.25)
--error: #ff4444
--error-bg: #2a0d0d
--success: #33ff66
--warning: #ffaa00
```

再发 style 节点（CRT 质感）：

```css
/* 全局等宽字体 */
body, .card, input, textarea, button, select {
  font-family: "JetBrains Mono", "Fira Code", Consolas, Menlo, monospace !important;
}
/* 磷光辉光 */
.card h3, .tag, .searchbox-input {
  text-shadow: 0 0 6px var(--accent-glow), 0 0 2px currentColor;
}
/* 卡片终端窗口化：左侧亮条 + 内发光 */
.card {
  border-left: 3px solid var(--accent);
  box-shadow: 0 0 18px rgba(51, 255, 102, 0.08),
              inset 0 0 40px rgba(51, 255, 102, 0.03);
}
/* 标题加 >_ 提示符 */
.card h3::before {
  content: ">_ ";
  color: var(--accent);
}
/* CRT 扫描线（不拦截点击，z-index 低于特效层 9999） */
body::after {
  content: "";
  position: fixed;
  inset: 0;
  z-index: 9998;
  pointer-events: none;
  background: repeating-linear-gradient(
    0deg,
    rgba(0, 0, 0, 0.18) 0px, rgba(0, 0, 0, 0.18) 1px,
    transparent 1px, transparent 3px
  );
}
/* 链接呼吸辉光 */
a { transition: text-shadow 0.2s; }
a:hover { text-shadow: 0 0 8px var(--accent); }
/* 滚动条终端化 */
::-webkit-scrollbar { width: 8px; }
::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
::-webkit-scrollbar-thumb:hover { background: var(--accent); }
```

### 4.2 暗夜蓝（仅 theme，最小改动）

```
--bg: #0d1117
--fg: #c9d1d9
--fg-secondary: #8b949e
--card: #161b22
--card-hover: #1c2129
--border: #30363d
--border-light: #21262d
--muted: #6e7681
--accent: #58a6ff
--accent-dark: #1f6feb
--accent-soft: rgba(88, 166, 255, 0.10)
--accent-glow: rgba(88, 166, 255, 0.25)
```

### 4.3 阅读优化（仅 style，隐藏干扰元素）

```css
/* 隐藏统计与页脚，加宽版心，放大正文字号 */
.card-stats, .footer { display: none; }
.box { max-width: 860px; }
.card p { font-size: 1.05rem; line-height: 1.9; }
/* 卡片去边框，纯排版 */
.card { border: none; box-shadow: none; border-bottom: 1px solid var(--border-light); border-radius: 0; }
```

---

## 5. 常见问题

**发布了但没生效？**
样式节点经 AI 审核，审核未通过会提示「内容审核不通过」；通过后刷新页面生效。非节点拥有者在他人节点下发布会被 403 拒绝。

**界面被改乱了怎么办？**
左上角用户面板 →「还原界面样式」，立即恢复默认。或在对应卡片上点「停用样式」。

**想让全站访客都看到主题？**
发布时勾选「离开本节点后仍保持生效」（persist），并建议放在高层级节点中提高被访问到的概率。

**样式节点之间冲突？**
多个样式节点同时生效时按 DOM 注入顺序叠加，同特异性后者优先；可用卡片上的启停按钮逐个排查。

**存量 image 节点显示异常？**
image 类型已移除，旧图片节点按原始文本显示，拥有者可编辑为 `file` 类型或删除。

---

*相关源码：后端校验 `dnfs2/src/dnfs2.cpp`（`validate_sp`），前端渲染 `fsys/public/js/dnfs.js`（`renderSpCss`）。*