第 36 期 · 前端重构 P4:本地主题目录、清单扩展与主题工具链
· 阅读需 3 分钟
完成前端重构计划(设计文档 07 §7、ADR 0043)的第四阶段 P4:站长无需重新编译即可在 <数据目录>/themes/ 下创建、校验、热加载自己的主题,并可使用单层继承、主题设置项与新的布局变体。
本地主题目录与热加载
- 启动时依次加载内置主题(
default、brocade)和<数据目录>/themes/*/plugin.json。 - 单个本地主题清单或资源有误时不会影响站点启动,错误会记录在日志并直接显示在后台「外观 → 主题」对应的卡片上;若当前启用的主题失效则自动回退到
default。 - 本地主题的静态资源使用内容哈希地址(
/themes-assets/<id>/<哈希>/<文件>),修改theme.css或图片无需手动改版本号即可生效;资源扩展名限定为样式、字体与图片,SVG 自动附带Content-Security-Policy: sandbox。 - 支持三种热加载入口:后台「重新扫描」按钮、
skinloom theme reload命令,以及web.mode = dev下的文件监听,重新扫描后递增config_version并通过 SSE 刷新已打开的页面。
清单扩展与布局变体
extends:单层继承父主题的 token、样式表、布局、首页区块与设置项,只写差异即可完成一套新主题。screenshot与theme.colorScheme:支持 16:10 预览图;当主题声明仅支持light或dark时,前端自动锁定该模式并隐藏访客的亮暗切换。- 相对路径重写:
viewer.background、token 值里的url(assets/...)、首页区块图片属性与图片设置项默认值中的assets/...自动解析为该主题的资源地址。 - 新布局变体:用户中心支持
user: "tabs"(水平标签导航栏),材质详情页支持texture: "stacked"(上下叠放)。 theme.settings与新设置theme.settings:支持color、image、choice、text、boolean五种类型;带token的设置项直接写入对应 token,其余输出为--sl-setting-<名称>变量与html[data-sl-setting-<名称>]属性,后台「外观 → 主题设置」自动生成表单。
工具链、契约测试与文档
- 新增
skinloom theme new <id> [--extends default]、skinloom theme check <dir>(按 WCAG 2.1 检查文字与背景对比度并给出警告)与skinloom theme reload。 - 后台「外观」页整理为六个标签页(主题、主题设置、颜色、首页、标识与页脚、自定义代码),「颜色」页支持将当前配色调整一键「导出为主题」下载
.zip主题包。 - 前端新增 Cascade Layer 契约测试与挂钩契约测试(
web/design.md§14),补齐website/static/schema/plugin.v1.json与文档站「开发主题」指南。