ZBlogPHP 侧边栏悬浮目录插件 — 文章目录

Z-BlogPHP 侧边栏悬浮目录插件 — 文章目录

自动提取文章中的 h1~h6 标题生成层级目录树，以 Fixed 定位悬浮在页面侧边栏。支持滚动高亮定位、收缩态竖排标签、悬停展开、平滑跳转和回到顶部，完整样式可自定义。

版本：v1.0.0
适配：Z-BlogPHP 1.7.0+
PHP：≥ 7.2
作者：softbangong
授权：不限制网站数量，下载安装后永久免费使用

插件简介

本插件用于在 Z-BlogPHP 文章页自动生成侧边栏悬浮目录。插件从前端扫描正文 DOM 中的 h1~h6 标题元素，构建层级嵌套的目录树，并以 Fixed 定位悬浮在浏览器窗口左侧或右侧，方便读者快速浏览文章结构和跳转到目标段落。

目录默认处于收缩态，仅显示竖排标签文字，鼠标悬停即展开完整目录面板。读者滚动页面时，目录中对应的标题项会自动高亮（Scroll Spy），实时反映当前阅读位置。点击任意目录项可平滑滚动到对应标题，目录底部提供一键回到顶部按钮。所有交互行为和视觉样式均可在后台独立配置。

功能特性

自动提取层级标题

插件在页面加载后自动扫描正文内容区域中的 h1~h6 标题元素，生成完整的层级目录树：

— 支持 h1~h6 全部六个层级，每个层级可单独勾选启用或关闭；
— 自动过滤非正文区域的干扰标题（评论、推荐文章、侧边栏小工具等），避免目录中出现无关条目；
— 正文内容区选择器可自定义，并内置十余种常见 Z-BlogPHP 主题的兜底选择器，确保兼容性。

Fixed 悬浮定位，左右可切换

目录面板以 Fixed 定位悬浮在浏览器窗口侧边，不随页面滚动而消失：

— 支持右侧悬浮（默认）和左侧悬浮两种位置，后台一键切换；
— 悬浮距离顶部的像素值可自由调整，适配不同主题的顶部导航栏高度；
— 目录展开宽度可自定义（默认 240px），面板最大高度自动适配视口，超出时内部滚动。

收缩态竖排标签，交互自然

目录默认处于收缩态，仅显示竖排标签文字，最小化对正文阅读的干扰：

— 竖排标签显示目录标题文字，鼠标悬停（Hover）时自动展开完整面板，移出即收缩；
— 点击标签可在展开和收缩之间手动切换，满足不同阅读习惯；
— 点击文章正文区域时目录自动折叠，让读者专注于内容阅读；
— 支持 localStorage 记住收缩状态，刷新页面后保持上次的展开/收缩偏好。

滚动高亮（Scroll Spy）

利用浏览器 IntersectionObserver API 实时追踪当前可视区域内的标题，自动高亮目录中对应的条目：

— 当前阅读位置对应的目录项高亮显示，文字颜色和背景色均可自定义；
— 高亮项在目录列表中自动滚动至可视区域，无需手动翻找；
— 兼容不支持 IntersectionObserver 的旧浏览器，自动降级为 scroll 事件监听方案。

平滑滚动跳转与回到顶部

点击目录中任意标题项，页面平滑滚动至对应段落：

— 默认使用浏览器原生 smooth 滚动，动画流畅自然；
— 超长页面（滚动距离超过设定阈值）自动启用分段跳转机制，分步靠近目标后实时重算位置，修正图片加载等导致的偏移误差；
— 目录底部提供「回到顶部」按钮，一键返回页面顶部。

完整样式自定义

目录面板的所有视觉元素均可在后台自定义，无需编辑 CSS 文件：

— 标题栏字号、目录项字号独立设置；
— 背景颜色、标题文字颜色、目录项文字颜色、悬停色、高亮色、高亮背景色、边框颜色共 7 种颜色均可通过取色器调整；
— 修改保存后即时生效，前台自动注入内联样式覆盖默认值。

手机端独立适配

插件支持手机端独立配置，适配小屏设备的浏览体验：

— 手机端可独立设置悬浮位置和距顶部距离，与桌面端互不干扰；
— 提供手机端总开关，关闭后小屏设备不显示目录面板，避免遮挡内容；
— 目录项字号、竖排标签尺寸在 768px 以下自动缩小，保持界面协调。

使用说明

第一步：安装启用

将 wzml_mulu 文件夹上传至网站 zb_users/plugin/ 目录，进入 Z-BlogPHP 后台「插件管理」页面，找到「文章目录」并点击启用。

第二步：基础配置

进入后台顶部导航栏「文章目录」设置页面：

— 确认插件启用开关为开启状态；
— 设置目录标题文字（默认”文章目录”），该文字同时显示在竖排标签和展开面板的标题栏；
— 选择悬浮位置（右侧或左侧），调整展开宽度和悬浮高度；
— 勾选需要在目录中显示的标题层级（h1~h6），默认全部勾选；
— 如有需要，修改正文内容区的 CSS 选择器以精确匹配您的主题。

第三步：调整交互与样式

在「交互设置」区域按需配置：

— 默认展开：关闭时目录初始为收缩态竖排标签，开启时初始即为展开态；
— 点击正文自动收缩：开启后点击文章区域目录自动折叠；
— Hover 展开/离开收缩：开启后鼠标滑入标签即展开、滑出即收缩；
— 平滑过渡动画：控制展开/收缩时的 CSS 过渡效果；
— 记住收缩状态：开启后使用 localStorage 记忆用户的展开/收缩偏好。

在「样式设置」区域通过取色器或数值输入框调整目录面板的颜色和字号，修改后点击「保存设置」即可实时生效。

注意事项

— 本插件仅扫描页面加载时 DOM 中已存在的标题元素，不会对服务端内容做任何修改；
— 如果文章中没有 h1~h6 标题，目录面板不会显示（不会产生空白占位元素）；
— 若主题正文容器使用了非标准选择器，请在后台「内容区选择器」中填写正确的 CSS 选择器，多个选择器用英文逗号分隔；
— 手机端默认启用，如果您使用的主题在移动端有特殊的布局处理，建议关闭手机端目录或调整悬浮位置以避免重叠；
— 超长页面分段跳转的阈值和分段次数可在后台调整，如果页面图片较多建议适当降低阈值以确保跳转精度。

×

广告

下载地址：

反馈与支持

— 作者：softbangong
— 作者网站：softbangong.top
— 作者网站：softbangong.com
— 邮箱：[email protected]

更新日志

v1.0.0（2026-06-22）

— 首个正式版本发布；
— 自动提取 h1~h6 标题生成层级目录；
— Fixed 悬浮定位，支持左侧/右侧切换；
— 收缩态竖排标签，Hover 展开/离开收缩；
— IntersectionObserver 滚动高亮（Scroll Spy）；
— 平滑滚动跳转，超长页面分段跳转修正偏移；
— 回到顶部按钮；
— 标题计数显示、过渡动画、localStorage 状态记忆；
— 7 种颜色自定义 + 字号独立设置；
— 手机端独立开关、位置和顶部距离配置；
— 十余种常见主题正文容器兜底选择器。