首页编程前端

# 简要说明

◉ 范围：本总结基于当前 fork 分支 main 相对主题 ShokaX 的上游 upstream/main 的差异整理，只统计 FLwolfy.ShokaX 魔改内容的功能性新增与体验增强。
◉ 整理方式：本文不按提交时间逐条罗列，而是按功能模块归类；每一类会点名相关主要 commit，再统一说明这组修改解决了什么问题、增加了什么功能。
◉ 时间范围主要覆盖 2025-09-28 至 2026-06-07。同步上游的 merge commit 不计入个人功能新增。

# 总览

在 Fork 之后，FLwolfy.ShokaX 相对 ShokaX 主题做了一组面向实际使用的功能增强。整体可以归为以下几类：

  • 资源生成与路径兼容：资源递归生成、子目录资源输出、多语言 root 兼容、特殊字符锚点定位修正。
  • 首页与全局视觉体验：沉浸式头图、背景轮播、视差滚动、波浪动画、移动端标题居中。
  • 内容组织页与分类卡片：首页分类卡片、归档页、分类页、标签页统一布局，分类封面支持本地与远程资源。
  • Markdown 与文章阅读体验：标题装饰、图片表格样式、Markdown attributes、文章页脚开关、Shiki 代码块折叠、现代化图片查看器。
  • Waline 评论系统：服务地址规范化、阅读量统计、最近评论、评论深链、输入框样式、本地统计控制。
  • 侧边栏、目录与搜索交互：侧边栏滚动阴影、快捷工具栏、ToC 点击定位、ToC 实时高亮、Pagefind 点击外部关闭。
  • 实验能力与组件拆分：响应式 siteData、页面可见性标题随机文案、osu wheel 从主题核心中移出。

# 1. 资源生成与路径兼容

这一类修改主要解决资源生成和路径处理的可扩展性问题，让主题在资源目录更复杂、多语言 root、非根目录部署等场景下更稳。

具体功能包括：

  • 扩展资源生成器，使其支持递归读取 source/_data/{assets} 下的子目录，并在输出时保留目录结构。
  • 统一 Windows 路径分隔符为 /，避免不同系统下生成路径不一致。
  • 增强多语言或非根目录部署场景下的路径处理，引入 waline.mergeByRoot 表达多语言评论/浏览量键是否共享。
  • 锚点定位改用 getElementById(decodeURIComponent(...))，避免特殊字符在 querySelector 中解析失败。

主要 commit：

  • 2a56be1 - commit all changes
  • b63602c - Support multiple language root

相关文件：

  • scripts/generaters/images.ts
  • source/js/_app/globals/tools.ts

# 2. 首页、视觉与响应式体验

这一类修改主要集中在“博客看起来和动起来的方式”。原版主题的结构被保留，但首页头图、滚动视差、颜色、波浪、移动端导航等视觉层都做了明显定制。

具体功能包括：

  • 将首页 header 和 brand 区域改造成更沉浸的大屏展示。
  • 调慢背景图轮播动画，使过渡更柔和。
  • 增加暗角和点阵叠加层，提升头图上文字的可读性。
  • 调整波浪动画的速度、透明度和位置。
  • 重新定义浅色/深色模式下的灰阶、阴影、文字色和主题色。
  • 首页背景图容器支持滚动视差，通过 CSS 变量 --parallax-offset 实时更新。
  • 滚动监听使用 requestAnimationFrame 节流，减少性能压力。
  • 调整 header、footer、sidebar、quick toolbar 在不同屏幕下的样式。
  • 移动端导航标题居中显示，并通过 white-space: nowrap 避免换行破坏导航栏布局。

主要 commit：

  • 2a56be1 - commit all changes
  • 16b5046 - Improve responsive styles and parallax effect
  • e4373bf - Make mobile mode title centered

相关文件：

  • source/css/_colors.styl
  • source/css/_common/outline/header/header.styl
  • source/css/_common/outline/header/brand.styl
  • source/css/_common/outline/header/image.styl
  • source/css/_common/outline/header/waves.styl
  • source/css/_common/outline/header/tool.styl
  • source/css/_common/outline/header/menu.styl
  • source/js/_app/pjax/domInit.ts

# 3. 内容组织页与分类卡片

这一类修改把归档、分类、标签和首页分类卡片从零散页面整理成更统一的内容入口。重点不是新增某一个单页，而是让站点的信息架构更一致。

具体功能包括：

  • 调整归档页结构，为统一的 index wrap 页面布局做准备。
  • 归档页、分类页、标签页外层统一包裹为 index wrap。
  • 增加页面分隔标题，例如 文章归档、文章分类、文章标签。
  • 分类总览页和标签云页增加对应标题区。
  • 将分页组件放入新的布局层级中，让列表页视觉结构更统一。
  • 首页分类卡片支持 item.cardCover 作为封面来源。
  • 子分类展示从 li > a 调整为更直接的链接元素，并按钮化显示。
  • 分类卡片标题增加文字描边，提高在封面图上的可读性。
  • homeConfig.cateCards 支持配置远程图片 URL。
  • 若分类封面配置为远程 URL，直接写入 cat.cardCover；若为本地文件，则继续读取并生成对应资源。
  • 支持从 category_map 和 category-tree.json 解析分类 slug，并统一转小写匹配，减少配置大小写不一致导致的失败。

主要 commit：

  • 2a56be1 - commit all changes
  • d0aef81 - Update new changes
  • 193feab - Move cateCard image to cloud

相关文件：

  • layout/archive.pug
  • layout/category.pug
  • layout/tag.pug
  • layout/page.pug
  • layout/_mixin/card.pug
  • source/css/_common/components/pages/home.styl
  • scripts/generaters/index.ts
  • languages/zh-CN.yml

# 4. Markdown 与文章阅读体验

这一类修改集中在文章正文的阅读体验上，包括标题、图片、表格、正文属性、文章页脚和代码块。目标是让长文、图文文章和技术文章都更容易阅读。

具体功能包括：

  • H1、H2、H3、H4 标题增加不同的装饰样式。
  • 标题锚点位置重新调整，兼容移动端。
  • 侧边栏目录生成时移除正文中的 H1，让 H1 可以在正文中承担特殊提示或装饰用途。
  • 行内 code 增加背景、圆角和内边距。
  • 正文图片统一为固定高度、等比裁切、圆角和 hover 阴影。
  • 表格默认居中，移动端使用固定布局。
  • 表格单元格增加边框和内边距。
  • 新增 Markdown attributes 样式：
    • .no-borders：取消表格边框。
    • .medium-imgs：中等高度图片。
    • .large-imgs：大尺寸图片。
    • .max-imgs：图片宽度撑满。
  • 当页面 front-matter 中设置 footer: false 时，不渲染文章页脚，适合独立页面、说明页或特殊文章布局。
  • 针对 code-block / Shiki 代码块新增自动折叠能力。
  • 代码块行数或高度超过阈值时，会自动包裹为可折叠容器。
  • 折叠状态下显示最大高度、底部渐隐遮罩和展开按钮。
  • 展开时自动计算完整高度，收起后自动滚回代码块位置，避免用户在长代码块中迷失当前位置。
  • 对 Web Component / Shadow DOM 渲染延迟做重试处理，避免代码块还没渲染完成就错过初始化。
  • 重构文章图片查看功能，移除原有基于 hana-img-viewer 和 Vue 的逐图组件挂载方式。
  • 不再使用 replaceWith() 替换正文图片，保留原始 <img> 节点及其 alt、title、懒加载和正文布局。
  • 新增站点级全屏图片查看层，支持暗色毛玻璃背景、图片计数、标题说明、查看原图、上一张和下一张切换。
  • 支持按钮、滚轮、双击和移动端双指缩放；放大后可以使用鼠标或触摸拖拽查看图片细节。
  • 支持方向键切换图片、Esc 关闭、+ / - 缩放和 0 复位。
  • 查看器图片以浏览器视口的 50% / 50% 为基准定位，避免横图、竖图和表格图片因可用区域留白不对称而视觉偏移。
  • 查看器通过固定定位覆盖页面，不修改 body 的 overflow、宽度或内边距，避免滚动条消失导致文章布局在打开和关闭时横向跳动。
  • 在查看器打开期间直接拦截遮罩层上的滚轮、触摸和页面滚动快捷键，使背景保持当前位置，同时不改变原页面尺寸。
  • 增加移动端安全区域、响应式工具栏和 prefers-reduced-motion 适配。
  • 从主题依赖中彻底移除不再使用的 hana-img-viewer。
  • 修复执行 bash local-build.sh 后 hana-img-viewer 被重新写回博客根目录 package.json 和 pnpm-lock.yaml 的问题。
  • 问题来自构建流程最后调用的 toolbox/hoistdep.mjs：原逻辑会访问 npm 镜像，读取官方最新版 hexo-theme-shokax 的依赖，并通过 pnpm add 将这些依赖提升到博客根目录。由于官方版本仍然依赖 hana-img-viewer，本地删除会在每次构建后失效。
  • 将依赖提升的数据源改为当前 fork 中的 themes/shokaX/package.json，使构建工具同步本地主题实际声明的依赖，不再受 npm 上官方最新版依赖清单影响。
  • 保留原有依赖提升机制，因此本地主题后续新增或移除依赖时，local-build.sh 仍然能够正常同步到博客根项目。

主要 commit：

  • 2a56be1 - commit all changes
  • d0aef81 - Update new changes
  • 2c76434 - Update new changes
  • e252095 - Add codeline collapse for Shiki codeblock
  • 44ee048 - Reforged imageviewer and get rid of hana-img-viewer
  • ebbf68d - Polish imageviewer
  • 56110b4 - Make dependencies using local package.json

相关文件：

  • package.json
  • toolbox/lib.mjs
  • layout/_mixin/sidebar.pug
  • layout/_partials/post/post.pug
  • source/js/_app/components/sidebar.ts
  • source/js/_app/page/imageviewer.ts
  • source/js/_app/page/post.ts
  • source/css/_common/components/post/expand.styl
  • source/css/_common/components/post/image-viewer.styl
  • source/css/_common/components/post/md-attrs.styl
  • source/css/_common/components/post/post.styl
  • source/css/_common/components/pages/pages.styl

# 5. Waline 评论系统

Waline 是这次 fork 中改动最集中的第三方功能之一。相关修改覆盖了样式、服务地址、阅读量统计、最近评论、评论深链、多语言路径和本地开发统计控制，最终形成了一套更适合 PJAX 博客的评论系统接入方式。

具体功能包括：

  • 新增 Waline 样式文件，定义评论系统的主题色、背景色、边框色、头像尺寸等变量。
  • 分别适配浅色模式和深色模式，并将样式接入 third-party.styl。
  • 自动去掉 serverURL 末尾多余 /。
  • 当配置中只写域名时，自动补全 https://，避免 Waline 初始化或最近评论接口请求失败。
  • 最近评论链接会通过当前站点 CONFIG.root 自动补齐 root；当链接已经包含当前 root 时不会重复拼接。
  • 将 Waline 评论初始化中的 pageview 改为 false，改由独立的 walinePageview() 负责统计。
  • 阅读量统计可以在页面刷新/PJAX 后立即执行，评论区仍然可以懒加载，不影响阅读量显示。
  • 支持 countLocalhost 配置，本地开发时可以只读取阅读量，不增加计数。
  • 修复 PJAX 刷新导致非文章页错误增加 Waline pageview 的问题。
  • 修复 pageview 因 PJAX 与本地跳过逻辑导致的延迟问题。
  • 支持 Waline RecentComments 返回结构的多种格式。
  • 当 SDK 返回空结果时，增加直接请求 /api/comment?type=recent 的 fallback。
  • 最近评论会清空旧内容后重新渲染，避免 PJAX 下重复追加。
  • 评论正文会转为纯文本，并将表情图片的 alt 转为文本；评论内容超过 50 字会自动截断；昵称为空时显示“匿名”。
  • 增加二次加载机制：首次为空时延迟重试，并在最近评论区域进入视口时再尝试加载。
  • 支持 URL hash 中的 Waline 评论 ID，也支持 ?comment= 查询参数。
  • 如果评论区尚未渲染，会主动加载评论区。
  • 使用 MutationObserver 与轮询等待目标评论节点出现，找到后平滑滚动到对应评论。
  • 跳转完成后清理 URL 中的 comment 参数和 hash，避免刷新后重复跳转。
  • 最近评论中指向当前文章的链接会拦截默认跳转，直接在当前页展开评论并定位。
  • 修复评论输入框在特定尺寸下出现异常红线的问题。
  • 输入框聚焦时使用主题色内描边高亮，统一评论输入区与当前站点调色板的视觉风格。

主要 commit：

  • d0aef81 - Update new changes
  • b290fde - Add https protocol to waline server URL
  • b63602c - Support multiple language root
  • 827f040 - fix pageView lag due to pjax and fix shouldSkipLocalPageview
  • da11aec - Fix bug where Pjax refresh cause non-post page add waline pageview
  • 142bc8a - Fix recent comments not showing on the article page
  • 4cb585c - Fix and Handle Waline recent comment deep links
  • 4c7ebaf - Add input highlight border for waline

相关文件：

  • _config.yml
  • source/js/_app/components/comments.ts
  • source/js/_app/pjax/refresh.ts
  • source/js/_app/globals/tools.ts
  • source/css/_common/components/third-party/waline.styl
  • source/css/_common/components/third-party/third-party.styl

# 6. 侧边栏、目录与搜索交互

这一类修改主要解决“页面在滚动、点击目录、打开侧栏或搜索时是否顺手”的问题。相比视觉改造，这一组更偏交互细节。

具体功能包括：

  • 侧边栏最小高度设置为视口高度。
  • 侧边栏内部滚动区高度根据视口计算。
  • 当侧边栏内容可继续向上/向下滚动时，显示内阴影提示。
  • 监听侧边栏内部滚动和窗口 resize，动态更新阴影状态。
  • 快捷工具栏从 sticky 调整为 fixed，固定在视口底部附近。
  • 快捷工具栏通过透明度显示/隐藏，减少布局跳动。
  • 平板和移动端隐藏固定快捷工具栏，避免遮挡内容。
  • 无评论区页面自动隐藏评论按钮。
  • 当 Pagefind 搜索面板打开时，点击面板外部会自动触发关闭按钮。
  • 点击搜索面板内部或搜索入口按钮时不会关闭。
  • 通过全局标记避免 Pagefind 外部点击事件重复绑定。
  • 调整目录点击后的滚动目标位置，结合导航栏高度和主内容偏移修正跳转位置。
  • 增加目录点击时的高亮锁定，避免动画滚动过程中高亮被滚动监听抢占。
  • ToC 高亮从基于 IntersectionObserver 的判断，改为基于实时滚动位置计算。
  • 新增激活线比例，标题进入视口指定位置后才切换目录项。
  • 滚动监听通过 requestAnimationFrame 节流，避免滚动中频繁计算。
  • 使用 scrollend 在滚动结束时再同步一次，保证滚动中看到的高亮项与最终停靠后的高亮项一致。
  • 避免 PJAX 后重复绑定旧的滚动监听。

主要 commit：

  • 2a56be1 - commit all changes
  • d0aef81 - Update new changes
  • 16b5046 - Improve responsive styles and parallax effect
  • 2443356 - Add pagefind autoclose on outside click
  • 3e7cec7 - Add auto aligned toc for sidebar
  • e3683ad - Make sidebar toc more accurate
  • b2d9718 - Make sidebar realtime scrolling identical to final snap

相关文件：

  • source/js/_app/components/sidebar.ts
  • source/js/_app/pjax/domInit.ts
  • source/js/_app/pjax/siteInit.ts
  • source/css/_common/outline/sidebar/sidebar.styl
  • source/css/_common/outline/sidebar/quick.styl

# 7. 第三方组件、实验能力与组件拆分

这一类修改不完全属于某个单一页面，而是围绕第三方组件接入、站点运行时能力和主题核心代码边界做整理。

具体功能包括：

  • 新增音乐播放器样式，为 #MusicPlayerRoot 添加半透明背景、模糊、圆角、边框与光晕阴影。
  • 将播放器样式统一接入 third-party.styl。
  • LOCAL.favicon.hide 和 LOCAL.favicon.show 支持使用 | 分隔多个候选文案。
  • 页面隐藏或恢复时随机选择一条文案作为 document.title，同时保留原有 favicon 切换逻辑。
  • 新增 window.createReactiveObject，使用 Proxy 深层监听对象变更。
  • 数据变化时派发 siteDataChange 自定义事件，为后续站点级动态数据联动预留能力。
  • 移除曾经内置在主题核心中的 osu wheel / track 相关页面与样式，改为通过 Hexo Inject 或外部注入方式维护。
  • 减少主题核心代码中的强耦合娱乐组件，降低维护成本，同时保留扩展可能。

主要 commit：

  • d0aef81 - Update new changes
  • e4de4b6 - Remove osu wheel (use hexo inject instead)

相关文件：

  • layout/_partials/siteData.pug
  • layout/_mixin/track.pug
  • source/js/_app/globals/handles.ts
  • source/js/_app/pjax/domInit.ts
  • source/css/_common/components/third-party/player.styl
  • source/css/_common/components/third-party/third-party.styl
  • source/css/_common/components/pages/track.styl

# 小结

这组魔改的核心目标并不是单纯“加功能”，而是把 ShokaX 调整成更贴近长期维护的形态：资源路径更可控，内容组织页更统一，文章阅读体验更完整，图片查看不再破坏正文节点和页面布局，Waline 在 PJAX 场景下更稳定，侧边栏和 ToC 交互也更符合实际阅读习惯。

如果按维护价值排序，最重要的几组改动是：

  • Waline 评论系统：覆盖评论、阅读量、最近评论和评论深链，是最完整的一组功能增强。
  • Markdown 与文章阅读体验：直接影响所有文章的展示质量。
  • 内容组织页与分类卡片：让读者更容易浏览站点内容结构。
  • 侧边栏与 ToC：改善长文阅读和目录跳转体验。
  • 资源生成与路径兼容：为后续扩展和非根目录部署提供稳定基础。