0030 外观:主题切换、区块目录与自定义 CSS
- 状态:已接受(2026-10-30)
- 相关:设计文档 02 F01、F35、§4;03 S16;05 §5.4、§6;ADR 0006、0029
背景
M4 第二部分是外观(ADR 0029)。M0 已经把默认主题写成主题包(plugin.json 里的 token、CSS、布局与首页区块),设置里也有 theme.active、theme.overrides、home.blocks,但:
- 后台没有界面,只能用命令行或 API 改。
- 只装了一个主题,"后台切换主题无需重启"(04 §13 的验收)无从演示。
- 清单的
layout(site、auth、user、skinlib)前端一个都没用;user: sidebar描述的界面并不存在。viewertoken 也没用。 - 05 §5.4 列的 10 种内置区块只做了 4 种;
home.blocks只检查有没有type。 theme.overrides里不安全的值保存时不报错,渲染时被悄悄丢掉。- F35 个性化(favicon、版权文案、自定义 CSS 等)与 02 §4 的
seo.*都没有。
决策
-
区块目录放在后端(
internal/theme/blocks.go):每种内置区块的类型与属性,属性有text、markdown、link、image、number、choice、buttons几种。home.blocks与主题清单里的home都按目录检查:未知的类型或属性、不是本站路径也不是 http(s) 的链接、超出范围的数量、超过 30 个区块,都拒绝。主题包在加载时就报错。GET /api/v1/admin/blocks把目录给后台编辑器,表单按属性类型生成。第二阶段插件在清单里声明的区块走同一套检查。
-
bootstrap 里的区块按访客的语言准备好:文字属性可以写一个字符串或每种语言一份,bootstrap 只给当前语言的那份;Markdown 由服务端渲染成
<属性名>Html(与公告相同,不保留原始 HTML)。前端的区块只读字符串。 -
补齐 05 §5.4 的内置区块:新增
stats、latest-textures、popular-textures、markdown、image、buttons。stats读新接口GET /api/v1/site/stats(未删除的账号、角色、公开材质),结果缓存一分钟。- 材质列表不带访客的会话去取,所有人看到同样的公开材质。
-
布局变体只列已经实现的:
auth(card、split)与skinlib(comfortable、compact)。site 与 user 目前各只有一种界面,不列。清单里没列的键忽略;列了的键值不认识,加载失败。默认主题的layout只保留这两项。分栏登录页旁边的面板是.sl-auth-panel,主题可以重新设计它的样式。 -
viewer token 输出为
--sl-viewer-*。3D 预览的画布本来就是透明的,背景用--sl-viewer-background(任何 CSS 背景值)。 -
第二个内置主题"织锦"(
brocade):暖色、分栏登录页、紧凑的皮肤库,首页带最新材质与站点数据。它把主题标准的 ①–④ 层都用了一遍,也让后台切换主题真正有得选。安装第三方主题仍在第二阶段(P2-3、P2-4)。 -
theme.overrides保存时就校验:分组只能是 light、dark、fonts、viewer,token 名只用小写字母、数字和横线,值不能含; { } < >和注释,最长 200 个字符。颜色调整对所有主题生效,不按主题分开存:多数站点先选主题再调色,后台提供"全部清除"。 -
个性化与 SEO 设置:
site.logo、site.favicon:图片地址或本站路径(BS 的favicon_url)。site.copyright:多语言 Markdown,渲染方式同公告。BS 的copyright_text是 HTML,改成 Markdown 就插不进脚本。seo.keywords(BS 的meta_keywords);页面描述继续用site.description。- BS 的
home_pic_url对应 hero 区块的背景图,导航栏与侧栏颜色对应颜色调整。transparent_navbar、hide_intro、fixed_bg不再单独提供,用区块编排和自定义 CSS 实现。meta_extras(任意 HTML 放进 head)不提供。
-
自定义 CSS(
theme.custom_css,最多 64 KB):- 设置定义增加
Superadmin:只有超级管理员、管理员令牌和命令行能改(03 S16)。普通管理员在页面上看到只读,从接口改会得到 403。 - 不放进页面的
<style>,而是单独的样式表/themes-assets/_custom/<内容哈希>.css(text/css、nosniff),排在主题 CSS 之后。内容没变就可以永久缓存;改了以后地址跟着变。因为不在页面里,里面写什么都结束不了元素、注入不了 HTML。
- 设置定义增加
-
自定义 JS 暂不提供:要给 Next.js 的每个页面加 CSP nonce,留到和 CSP 一起做(M5 安全自查之前)。已在 ADR 0039 提供(
theme.custom_js)。 -
外观页
/admin/appearance:- 主题:列出已安装的主题,一键切换;
- 颜色:亮色、暗色两组常用 token 与圆角,可以用取色器;
- 首页:添加、排序、删除区块,按属性类型编辑;"改用主题自带的首页"把
home.blocks设回 null,以后换主题首页也跟着换; - 站点标识与页脚、自定义 CSS。
设置页不再显示这些键。
-
预览模式(05 §6.3)推迟:保存即生效。
影响
- 新设置
site.logo、site.favicon、site.copyright、seo.keywords、theme.custom_css;home.blocks与theme.overrides校验更严格。读取时不重新校验已保存的值:旧的未知区块,前端照旧跳过。 - 接口:
SettingView.superadmin;ThemeView带上主题自己的 token、布局与首页;新增listBlockTypes、getSiteStats;SiteInfo增加logo、favicon、copyrightHtml、keywords。没有新表与迁移。 - 主题作者:清单里的首页区块与 token 在加载时检查;主题 id 只能是 1–32 个小写字母、数字或横线(
_custom留给自定义 CSS)。