X — 高仿 X（Twitter）的 Halo 2.x 主题

把博客当作一个 X 账号来逛：首页是时间线，文章是推文，标签是话题，作者是主页。
打开注册、让更多人进来发内容，它也能当一个小型内容平台来用。

关于本项目

本主题的绝大部分代码由 WorkBuddy（模型 DeepSeek V4.1 Flash）生成，人工负责提出需求、审阅与验收。
从「页面布局契约缺失」到「后台设了暗色却总是亮色」，中间踩过的坑都记在提交历史里，可以当排错参考。
欢迎提 Issue。

特性

布局

• 桌面端三栏：左导航 275px / 主栏 600px / 右栏 350px（宽屏 ≥1300px 时 400px），整体居中于 1265px 容器
• 移动端单栏 + 底部五宫格导航 + 悬浮按钮
• 断点：≤1265px 左栏收窄为纯图标；≤1005px 隐藏右栏；≤705px 单栏 + 底部导航

配色

• 三档方案，与 X 完全一致：Lights out（纯黑，默认）/ Dim（深蓝灰 #15202B）/ Light
• 支持「跟随系统」，右上角可随时切换，选择写入 localStorage
• 切换菜单里有一项 「跟随站点设置」，用于清除本地覆盖、回到你在主题设置里配的方案
• 本地选择带来源标记：只有「本地选择」与「当前站点默认值」是同一次设置产生的才生效；站点设置一改，旧的本地覆盖自动作废。这样不会出现「后台设了暗色、页面却一直是亮色」
• 强调色、三档背景色、正文字号、圆角、密度均可在主题设置中调整
• html 上始终写「解析后的具体值」（dark / dim / light），原始选择另存于 data-preference，避免 system 这种 CSS 匹配不到的值导致样式失效
• CSS 内置 html:not([data-theme]) 的兜底变量，即使 JS 未执行也不会回退成浏览器默认白底

内容呈现

• 推文卡片：头像 · 显示名 · 认证标 · @用户名 · 相对时间，正文 + 封面图 + #话题，底部互动栏（回复 / 复制链接 / 点赞 / 浏览 / 收藏 / 分享）
• 互动图标沿用 X 的 hover 语义：回复变蓝、转发变绿、点赞变粉并带弹跳动效
• 相对时间对齐 X 的呈现：现在 / 5分钟 / 3小时 / 8月14日 / 2024年8月
• 首页双 Tab：为你推荐（全部）与 精选（置顶文章），纯前端切换
• 文章详情页还原推文详情：23px 标题、17px 正文、发布时间与浏览量、回复区

页面覆盖

能力

• 全文搜索：调用 Halo 内置索引接口 POST /apis/api.halo.run/v1alpha1/indices/-/search
• 点赞：走 POST /apis/api.halo.run/v1alpha1/trackers/upvote，用 localStorage 记录已赞状态避免重复提交
• 评论：通过 <halo:comment> 扩展点接入评论插件
• 页脚：保留 <halo:footer />，兼容系统级代码注入

安装

主题标识：halo-theme-x。早期版本叫 theme-x，上架应用市场时该名称已被占用，故改名。
主题设置存在 theme-x-setting 这个 ConfigMap 里，改名时特意没有跟着换，所以老用户覆盖安装后配置照旧。

1. 把 theme-x 目录打包为 zip（要求 zip 内包含 theme-x/ 顶层目录）
2. 进入 Halo 后台 → 外观 → 主题 → 安装主题 → 上传该 zip
3. 启用主题后，进入 主题设置 调整配色与开关

要求 Halo >= 2.26.0 —— 主题依赖 2.26 引入的页面布局契约（templates/layout.html）与用户中心 API。
开发调试时建议开启 thymeleaf.cache: false（或环境变量 SPRING_THYMELEAF_CACHE=false）。

功能性还原 X（可选，依赖社区插件）

外观之外，主题对 X 的核心功能也做了映射。以下插件均为可选，装了才有对应能力，不装不影响主题运行。

安装瞬间插件后，导航会自动多出「瞬间」一项（可在主题设置里关闭）。瞬间列表支持按标签筛选：/moments?tag=xxx。

关于评论：瞬间的回复依赖评论插件支持 moment.halo.run / Moment 这个评论主体。若回复区不显示，可在主题设置里调整「瞬间评论 · 模型分组 / 类型」两个字段，按你的评论插件实际值填写。

读者注意：主题内所有路由（分类 / 标签 / 归档）都读取 site.routes.*，不硬编码。若你在后台改过路由前缀（例如归档页改成 /posts），导航会自动跟随。

登录与账号

主题内置了完整的登录态处理，全部基于 Halo 原生的 Spring Security 方言，无需额外插件：

不再事事都跳 Halo 个人中心

主题在 author.html / layout.html / index.html 里内建了两套原本要跳 /uc 的能力：

旧入口没有删：右栏账号卡片的「个人中心」按钮、以及作者主页资料区里为作者本人准备的「个人中心（旧入口）」链接，都仍然指向 /uc（地址可在主题设置里改）。

这两处能力都依赖 Halo 的用户中心 API（/apis/uc.api.* 下的 UcUserEndpoint，自 2.26.0 起提供），
这也是主题把 requires 定在 >= 2.26.0 的原因。

为什么主题里能直接写数据：Halo 的 CSRF 只保护表单类端点，CsrfConfigurer 里用 NegatedServerWebExchangeMatcher 明确把 /api/**、/apis/**、/actuator/**、/system/setup、/sudo/** 排除在保护之外，所以带会话 cookie 直接 fetch 即可，不需要任何令牌（那个 XSRF-TOKEN cookie 是 HttpOnly 的，前端本来也读不到）。

登录 / 注册页面已适配 X 风格

主题覆盖了 templates/gateway_fragments/layout.html，采用官方推荐的**「自定义样式」**方式：

• 只引入 Halo 的逻辑脚本 gateway_fragments/common::basicScriptResources（密码 RSA 加密、表单提交、验证码等全部由 Halo 提供）
• 样式完全由主题接管，通过 templates/assets/css/x-gateway.css 把登录 / 注册 / 找回密码等页面渲染成 X 风格
• 不改动任何表单结构，因此不存在登录流程被破坏的风险

片段签名严格遵循契约：layout (title, head, body)，其中 body 由 Halo 注入具体的认证表单。

其它实现要点

• 登录态判断用 sec:authorize="isAnonymous()" / isAuthenticated()
• 当前用户用 ${contributorFinder.getContributor(#authentication.name)} 取得（返回 ContributorVo，含 displayName / avatar / name / bio）
• 注册入口会同时检查 site.allowRegistration，系统设置里没开「允许注册」就不会显示
• 作者主页（/authors/{name}）会展示该用户的加入时间（author.spec.registeredAt）

页面布局契约（Halo 2.26.0+）

主题在 templates/layout.html 中声明了 html(head, content) 片段，符合 Halo 的 v1 页面布局契约。插件提供的前台页面（瞬间、链接、图库等）会自动套用本主题的左导航、右栏、配色与响应式外壳，无需额外适配。

• head：调用方提供的头部片段；主题只在 head 为空时输出站点标题，避免同一页面出现两个 <title>
• content：调用方提供的正文片段，插入到主栏中
• 页面底部保留 <halo:footer />，Halo 与插件仍可注入内容

主题自身的 14 个页面复用同一份布局（~{layout :: html(head = ~{::head}, content = ~{::content})}），不存在第二套外壳代码。在 Halo 后台的主题详情里，Theme.status.pageLayout 应显示为 SUPPORTED。

因为契约只允许 head / content 两个参数，「当前栏目高亮」在客户端按 location.pathname 判定；同时在客户端判定的还有相对时间格式化与阅读时长。

目录结构

theme-x/
├── theme.yaml                     # 主题元信息
├── settings.yaml                  # 主题设置表单
├── logo.svg                       # 主题图标源文件
└── templates/
    ├── layout.html                # 页面布局契约（html(head, content)）+ 全局骨架
    ├── index.html                 # 首页时间线
    ├── post.html                  # 文章详情
    ├── post_longform.html         # 自定义模板：长推文
    ├── page.html                  # 独立页面
    ├── page_profile.html          # 自定义模板：个人主页
    ├── archives.html              # 归档
    ├── tags.html / tag.html       # 话题集合 / 归档
    ├── categories.html / category.html
    ├── author.html                # 作者主页（含「编辑个人资料」）
    ├── search.html                # 搜索
    ├── moments.html               # 瞬间时间线（瞬间插件）
    ├── moment.html                # 瞬间详情
    ├── error/
    │   ├── 404.html
    │   └── error.html
    ├── gateway_fragments/
    │   └── layout.html            # 认证页契约 layout(title, head, body)
    ├── modules/
    │   ├── left-nav.html          # 左侧导航
    │   ├── right-rail.html        # 右侧栏（搜索 / 账号卡片 / 正在发生）
    │   ├── mobile-nav.html        # 移动端底部导航
    │   ├── account.html           # 顶栏账号区
    │   ├── account-menu.html      # 左下角账号卡片「…」弹出的菜单
    │   ├── post-card.html         # 推文卡片组件（文章）
    │   ├── moment-card.html       # 推文卡片组件（瞬间）
    │   ├── verified.html          # 认证蓝标（带用户名白名单）
    │   ├── compose.html           # 站内发瞬间弹层
    │   └── profile-edit.html      # 个人资料编辑弹层
    └── assets/
        ├── css/x.css              # 全部样式
        ├── css/x-gateway.css      # 认证页样式
        └── js/main.js             # 交互脚本

主题设置

设置值在模板中通过 theme.config.[group].[name] 读取。

关于配色：站点设置说了算

v1.7.1 之前这里有个很容易踩的坑，值得记一笔：

早期版本在右上角放了一个配色切换菜单，里面把 light 标成了「默认」。任何人（包括站长自己）
点一下这个「默认」，就会在自己的浏览器里永久写入一条「覆盖成亮色」的偏好。而初始化脚本
只在「站点默认值变化过」时才作废这条覆盖 —— 如果站长一直用 dark 没动过，这条覆盖就永远赢，
表现就是后台怎么改都强制亮色，换设备/换浏览器却正常（因为新浏览器没有这条脏数据）。

现在的规则简单且不可绕：

• 主题设置里的「默认配色方案」是唯一权威来源
• allow_visitor_switch 默认关闭：初始化脚本完全不读 localStorage，并顺手清掉历史脏数据
• 打开开关后，访客覆盖会带上「站点当前设置」的指纹，站长一改设置它立刻作废
• 切换菜单底部会直接写出「站点设置：熄灯 / 当前生效：跟随站点设置」，状态一眼可见

多作者与平台化

主题最初是按「一个人写博客」设计的，但功能上并没有限死在这上面：

• 作者主页：/authors/{用户名} 对任何作者都生效，展示头像、简介、加入日期和他的全部文章
• 认证蓝标：支持用户名白名单，只给名单里的作者显示
• 站内发帖：任何登录用户都能发瞬间（是否需要审核由 Halo 的角色权限决定）
• 账号菜单：左下角账号卡片右侧的「…」可以弹出菜单，条目在主题设置里自由增删
• 作者主页封面：默认共用一张封面；想给某个作者单独定制，在他的 User 资源上写
  theme-x/cover 注解即可 —— 社区插件或后台编辑用户时写入都行

账号菜单

主题设置 → 导航自定义 → 账号菜单项，卡片式条目，可以自由增删排序。

默认给了一条「用户中心」。想加「我的主页」「我的瞬间」「退出登录」之类，往列表里加就行 ——
退出登录填 Halo 的 /logout。

作者主页封面图

主题按下面的顺序取封面：

1. 该作者 User 资源上的 theme-x/cover 注解（给单个作者定制，插件可写）
2. 主题设置 → 账号信息 → 作者主页默认封面图
3. 再退回上面的「独立页面封面图」
4. 都没有就用主题自带的渐变背景

目前 Halo 生态里没有现成的「用户封面图」插件，所以主题把接口留在了注解上：
任何能写入 User.metadata.annotations['theme-x/cover'] 的插件都能直接驱动它。
也可以直接在后台编辑用户、手工加这条注解。

已知边界

• 搜索依赖 Halo 内置的全文索引，若站点未启用索引会返回空结果
• 点赞用的是 trackers/upvote，只支持点赞、不支持取消（Halo 只有这一个端点，没有对应的 DELETE）。
  服务端不做去重，主题用 localStorage 记录已赞状态；清掉浏览器数据后再点会重复计数，这是 Halo 的既定行为
• 浏览数由主题在详情页上报一次 trackers/counter，用 sessionStorage 保证同一篇在一次会话里只报一次
• 评论需要另行安装评论插件；未安装时提示区会显示占位文案
• 归档页的年份标题使用了 sticky 定位，在部分旧版浏览器上会退化为普通标题
• 站内发瞬间依赖瞬间插件；发布后是否需要审核由 Halo 的角色权限决定（站长 / 有发布权限的账号立即通过，其他账号会进入待审核，这也是插件侧 momentService.create 的既定行为）
• 编辑个人资料只能改显示名、简介与头像 —— 用户名与邮箱不在 UpdateMyProfileRequest 里，属于 Halo 的接口边界，不是主题的取舍

与 halo-plugin-X 联动（可选）

halo-plugin-X 是本主题的配套插件，用来补上 Halo 本身没有的那几项个人资料：

主题不依赖这个插件。 装上之后，「编辑个人资料」弹层里会多出这三项；没装则那一块整块隐藏，
主题其余部分完全不受影响 —— 插件只做增强，不成为前提。

探测方式很直接：主题向 GET /apis/x.api.halo.run/v1alpha1/my-profile 发一次请求，
成功就显示扩展字段，失败就保持隐藏。保存时两个接口分开调用，扩展资料写失败也不会拦住显示名和简介。

因为数据存的是 User 的注解，你也可以不装插件、直接在后台给某个用户加上这些注解，主题一样会认。

回复区样式

回复区用的是 Halo 评论插件（halo-plugin-comment-widget）。它是 Lit + Shadow DOM 组件，
内部类名从主题 CSS 里盖不到 —— 但它把所有配色收敛成了 --halo-cw-* 自定义属性，
而自定义属性能穿透 Shadow 边界，这就是官方的定制入口。

主题把整套变量映射到了自己的配色上：

这一步不是可选项。插件靠 .dark 类或 prefers-color-scheme 判断深色，
而本主题用的是 data-theme 属性，插件识别不到 —— 不覆盖的话，
深色主题下评论区会退回浅色配色，文字和背景糊在一起。

想再改，直接覆盖同名变量即可；不要试图去写 .item-avatar 之类的内部类名，那些在 Shadow DOM 里。

动效

v1.8.0 把散落各处的硬编码缓动收敛成一套变量（--x-ease / --x-ease-out / --x-dur-fast / --x-dur / --x-dur-slow），改一处全站生效，并补齐了此前缺失的过渡：

顺手修了一个隐藏 bug：.x-post { display: flex } 会盖掉浏览器默认的 [hidden] { display: none }，
导致首页「精选」标签页实际切不动。现在补了全局 [hidden] { display: none !important }。

所有动效在 prefers-reduced-motion: reduce 下会被完全关闭（不只是把时长压到 0.01ms，而是取消动画本身）。

从源码安装

本仓库的根目录就是主题本体。Halo 要求 zip 内包含一个顶层 theme-x/ 目录，所以克隆后：

git clone https://github.com/<你的用户名>/halo-theme-X.git theme-x
zip -r theme-x.zip theme-x -x 'theme-x/.git*'

然后到 Halo 后台 → 外观 → 主题 → 安装主题 上传 theme-x.zip。

授权

MIT License。

主题为界面风格的致敬实现，X 的名称与标识归 X Corp. 所有，本项目与 X Corp. 无任何关联。