把显示设置面板做成「全量配置化」：显隐开关 + 访客默认值两层设计

问题：面板上的选项，配置里只有一半#

主题的显示设置面板（外观 / 壁纸 / 特效三个 Tab）里有十几个访客可切换的选项：配色九宫格、页面背景模式、全屏布局、覆盖透明参数、水波纹、渐变过渡、樱花特效……但翻配置文件会发现：

显隐配置不全——displaySettings 只列了 6 个开关，樱花特效和横幅相关的 4 个开关不受控；
默认值配置不全——比如「全屏壁纸的默认布局是经典还是 Hero」，配置文件里根本没有这一项。

访客的选择会存到浏览器里覆盖站点默认，但首次访问看到什么、没动过设置的访客看到什么，由站点默认值决定。这个默认值理应归站长管。

第一层：显隐开关全覆盖#

displaySettings 补齐面板上的每一个选项：

1
displaySettings:
2
  colorStyle: true     # 配色风格 9 宫格
3
  colorSpec: true      # 配色规范（2021/2025）切换
4
  wallpaperMode: true  # 页面背景模式切换
5
  layoutMode: true     # 文章列表布局（列表/网格）
6
  reduceMotion: true   # 减少动效
7
  texture: true        # 背景纹理
8
  effects: true        # 樱花特效开关        ← 新增
9
  bannerTitle: true    # 首页壁纸标题开关    ← 新增
10
  bannerCarousel: true # 壁纸轮播开关        ← 新增
11
  bannerWaves: true    # 水波纹动画开关      ← 新增
12
  bannerGradient: true # 渐变过渡开关        ← 新增

面板侧用「与逻辑」决定渲染与否：

1
{#if siteConfig.banner.carousel.enable && displayConfig.bannerCarousel}
2
  <div class="m3-toggle-row">...</div>
3
{/if}

第二层：访客默认值收进 YAML#

盘点所有面板选项的默认值来源后，把它们分成三类：

已经可配，补文档即可#

全屏布局的默认值在类型里早就存在（wallpaperMode.fullscreen.layout），只是配置文件没暴露。现在写进 site.yaml：

1
wallpaperMode:
2
  defaultMode: banner   # 站点默认背景模式
3
  fullscreen:
4
    layout: classic     # classic 内容紧随导航栏 | hero 首屏整屏展示壁纸
5
  overlay:
6
    opacity: 0.8        # 覆盖透明默认参数
7
    blur: 10
8
    cardOpacity: 0.6

新增配置域#

「渐变过渡」的默认值原来硬编码在工具函数里：

1
// 之前：写死
2
export function getDefaultBannerGradientEnabled(): boolean {
3
  return true;
4
}
5

6
// 现在：读配置
7
export function getDefaultBannerGradientEnabled(): boolean {
8
  return siteConfig.banner.gradient?.enable ?? true;
9
}

类型上给 banner 加一个可选域，配置合并规则天然兼容旧配置（没写就是 true，行为不变）。

无需新配置的#

配色三件套（色相 / 风格 / 规范）、背景纹理预设与浓度、文章列表布局默认值，原本就有配置入口，这次只是把文档补齐。

验证方式#

改配置验证默认值是否生效时，要清掉 localStorage 模拟首次访问——访客偏好优先于站点默认，不清的话改了也「看不到变化」：

1
await page.evaluate(() => localStorage.clear());
2
await page.reload();
3
// 读取 <html> 的 dataset 验证
4
document.documentElement.dataset.fullscreenLayout; // "classic" | "hero"

把配置临时改成 hero → 同步 → 重启 → 清存储访问，确认 data-fullscreen-layout="hero" 生效后改回。

小结#

显隐开关管「面板上允许出现什么」，默认值管「没动过设置的访客看到什么」，两层正交；
新增配置域一律用可选字段 + ?? 兜底，旧配置零迁移成本；
「零额外负担」原则不变：开关关掉的选项直接不输出 DOM。

至此，面板上每一个选项：能不能出现、默认是什么，都可以在内容仓的 YAML 里一行配置解决。

Fqzlrのblog

问题：面板上的选项，配置里只有一半#

第一层：显隐开关全覆盖#

第二层：访客默认值收进 YAML#

已经可配，补文档即可#

新增配置域#

无需新配置的#

验证方式#

小结#

继续阅读

换条路线

公告

大版本更新

稳定性修复一批

互换友链

关于我的介绍

Fqzlrのblog

问题：面板上的选项，配置里只有一半#

第一层：显隐开关全覆盖#

第二层：访客默认值收进 YAML#

已经可配，补文档即可#

新增配置域#

无需新配置的#

验证方式#

小结#

分享文章

沿着主题读

换条路线