显示侧边栏

目录导航组件

flux:x-toc 是 Flux Pro Max 提供的自包含目录导航组件，自动从页面提取标题、高亮当前阅读章节、显示阅读进度，适合文档页、博客文章等长页面的导航场景。

核心功能

自动提取页面标题并生成目录
Scroll Spy 实时高亮当前阅读章节
页面顶部阅读进度条
点击目录项平滑滚动到对应位置
多级标题自动缩进（h2 / h3 / h4）
移动端自动折叠为悬浮按钮 + 顶部弹出面板
标题不足时自动隐藏
完整暗色模式支持
兼容 Livewire 页面导航（livewire:navigated）

基础用法

最简单的用法，组件会自动扫描页面 <main> 区域内的 h2 和 h3 标签生成目录。

{{-- 在页面布局中，将 x-toc 放在主内容右侧 --}}
<div class="flex items-start max-lg:flex-col">
    <flux:main class="lg:py-12">
        <h1 class="text-2xl font-bold mb-6">示例文档页面</h1>

        <h2 class="text-xl font-semibold mb-3 mt-10">安装指南</h2>
        <p class="mb-4 leading-relaxed">通过 Composer 安装 Flux Pro Max 扩展包到你的 Laravel 项目中。</p>

        <h2 class="text-xl font-semibold mb-3 mt-10">配置选项</h2>
        <p class="mb-4 leading-relaxed">你可以根据项目需求对组件进行配置。</p>

        <h3 class="text-lg font-medium mb-2 mt-6">数据库配置</h3>
        <p class="mb-4 leading-relaxed">默认使用 MySQL 数据库。</p>

        <h3 class="text-lg font-medium mb-2 mt-6">缓存配置</h3>
        <p class="mb-4 leading-relaxed">推荐使用 Redis 作为缓存驱动。</p>

        <h2 class="text-xl font-semibold mb-3 mt-10">基本用法</h2>
        <p class="mb-4 leading-relaxed">组件提供了简洁的 API。</p>

        <h2 class="text-xl font-semibold mb-3 mt-10">高级功能</h2>
        <p class="mb-4 leading-relaxed">包括动态数据加载、事件监听、自定义渲染等。</p>

        <h3 class="text-lg font-medium mb-2 mt-6">事件系统</h3>
        <p class="mb-4 leading-relaxed">支持监听和触发自定义事件。</p>

        <h3 class="text-lg font-medium mb-2 mt-6">自定义渲染</h3>
        <p class="mb-4 leading-relaxed">通过插槽机制自定义渲染输出。</p>

        <h2 class="text-xl font-semibold mb-3 mt-10">常见问题</h2>
        <p class="mb-4 leading-relaxed">大多数问题可以通过检查配置和依赖版本来解决。</p>
    </flux:main>

    {{-- 自动生成目录导航 --}}
    <flux:x-toc />
</div>

自定义选择器

通过 selector 属性指定要提取的标题元素。默认为 main h2, main h3，你可以根据页面结构自由调整，例如扫描 <article> 内的标题，或包含 h4。

扫描 article 内的 h2 ~ h4

<flux:x-toc selector="article h2, article h3, article h4" />

扫描指定 class 容器内的标题

<flux:x-toc selector=".blog-content h2, .blog-content h3" />

阅读进度条

组件默认在页面顶部显示一条 2px 高的阅读进度条，随页面滚动实时更新。通过 showProgress 属性可关闭。

关闭阅读进度条

<flux:x-toc :showProgress="false" />

移动端行为

在小屏幕（< lg）下，侧边目录会自动隐藏，取而代之的是右上角的悬浮目录按钮。点击后从顶部弹出目录面板，点击目录项自动关闭并滚动到对应位置。

通过 collapsible 属性可以关闭移动端折叠行为（此时移动端不显示任何目录）。

关闭移动端折叠目录

<flux:x-toc :collapsible="false" />

自动隐藏

当页面标题数量少于 minHeadings （默认为 2）时，整个目录组件会自动隐藏，不会在页面上渲染任何内容。这对于内容较短的页面很有用——避免只有一个标题时目录显得多余。

至少 3 个标题才显示目录

<flux:x-toc :minHeadings="3" />

完整配置示例

将所有属性组合使用，适用于博客文章页等场景。

{{-- 博客文章页布局 --}}
<div class="flex items-start max-lg:flex-col">
    <flux:main class="lg:py-12">
        <article class="blog-content">
            <h1>{{ $post->title }}</h1>

            <h2>背景介绍</h2>
            <p>...</p>

            <h2>实现方案</h2>
            <p>...</p>

            <h3>前端部分</h3>
            <p>...</p>

            <h3>后端部分</h3>
            <p>...</p>

            <h2>总结</h2>
            <p>...</p>
        </article>
    </flux:main>

    {{-- 自定义配置的目录导航 --}}
    <flux:x-toc
        selector="article h2, article h3"
        title="本篇目录"
        :scrollOffset="100"
        :showProgress="true"
        :collapsible="true"
        :maxDepth="3"
        :minHeadings="2"
    />
</div>

属性参考

下面列出了 flux:x-toc 支持的全部属性。

属性	类型	默认值	说明
selector	string	main h2, main h3	CSS 选择器，用于从页面中提取标题元素。支持任意有效的 CSS 选择器字符串。
title	string	目录	目录导航区域的标题文字。
scrollOffset	int	80	点击目录项滚动时的顶部偏移量（px），用于避免固定导航栏遮挡标题。如果你的导航栏高度不同，可调整此值。
showProgress	bool	true	是否在页面顶部显示阅读进度条。
collapsible	bool	true	移动端是否显示悬浮按钮 + 顶部弹出面板。设为 false 时，移动端不显示任何目录。
maxDepth	int	3	最大标题层级（h1=1, h2=2, h3=3, h4=4）。超过此层级的标题不会被收录到目录中。
minHeadings	int	2	最少标题数量阈值。当页面中匹配到的标题数少于此值时，整个组件自动隐藏（不渲染）。