Filament Tabs Blade 组件完全指南：选项卡渲染、激活状态、图标徽章与垂直布局实战

Filament Tabs Blade 组件完全指南：选项卡渲染、激活状态、图标徽章与垂直布局实战

【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps & admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament

导读

Filament 的x-filament::tabsBlade 组件用于在任意视图中渲染一组选项卡（Tabs），借助点击切换在多个内容区块之间导航。本文以 docs/12-components/03-tabs.md 为骨架，结合filament/support包中 Tabs 组件的 Blade 实现（index.blade.php 与 item.blade.php）以及面板页面子导航对它的复用方式（tabs.blade.php），系统讲解 Tabs 组件的全部属性、激活态触发、图标与徽章配置、锚点链接与垂直布局，并给出可直接复制的实战示例。

组件概述与基本用法

Tabs 组件由容器x-filament::tabs与条目x-filament::tabs.item两层 Blade 组件构成，前者渲染为语义化的<nav>元素，后者默认渲染为<button>元素。最简单的用法如下：

<x-filament::tabs label="Content tabs"> <x-filament::tabs.item> Tab 1 </x-filament::tabs.item> <x-filament::tabs.item> Tab 2 </x-filament::tabs.item> <x-filament::tabs.item> Tab 3 </x-filament::tabs.item> </x-filament::tabs>

其中label属性会被合并进<nav>的aria-label，用于无障碍（a11y）语义标注；未传入时使用翻译键filament::components/tabs.label的默认文案。从 index.blade.php 源码可见，容器组件只做三件事：合并aria-label、按contained/vertical属性追加fi-contained/fi-verticalCSS 类、输出$slot内容。

默认渲染效果是一组横向排列、带圆角卡片底座的标签条（对应.fi-tabs的非 contained 样式，见 tabs.css）。

触发选项卡的激活状态

默认情况下，所有选项卡都不会呈现"激活"外观。要激活某个选项卡，使用active布尔属性：

<x-filament::tabs> <x-filament::tabs.item active> Tab 1 </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

从 item.blade.php 源码可以看出，active还会同步输出aria-current属性（<a>标签时为page，<button>标签时为true），并追加fi-activeCSS 类。激活态的视觉样式定义在 tabs.css：底色变为gray-50（暗色模式为white/5），标签文字与图标变为主题色primary-700（暗色模式为primary-400）。

基于 Livewire 状态的条件激活

active支持动态绑定，配合 Livewire 的wire:click即可实现"点击切换激活项"的交互：

<x-filament::tabs> <x-filament::tabs.item :active="$activeTab === 'tab1'" wire:click="$set('activeTab', 'tab1')" > Tab 1 </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

此时需要在 Livewire 组件类中维护$activeTab公共属性，点击后由 Livewire 状态更新触发重渲染，激活外观随之变化。这是 Filament 面板页面子导航在底层使用的核心机制——见 tabs.blade.php：每个导航项都通过:active="$isNavigationItemActive"绑定激活状态，并通过:href、tag="a"渲染为链接。

基于 Alpine.js 的条件激活

如果不想经过服务端往返，可以使用alpine-active属性配合 Alpine 表达式，纯前端切换激活类：

<x-filament::tabs x-data="{ activeTab: 'tab1' }"> <x-filament::tabs.item alpine-active="activeTab === 'tab1'" x-on:click="activeTab = 'tab1'" > Tab 1 </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

从源码看，alpine-active会生成x-bind:class指令：表达式为真时追加fi-active类（item.blade.php）；同时由于存在 Alpine 激活表达式，fi-active不再由服务端active属性静态输出（item.blade.php），两者互不干扰。

为选项卡设置图标

每个选项卡都可以通过icon属性添加图标，图标渲染基于Filament\Support\generate_icon_html()帮助函数（定义于 helpers.php），支持传入图标名或 BackedEnum：

<x-filament::tabs> <x-filament::tabs.item icon="heroicon-m-bell"> Notifications </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

图标默认渲染在标签文字之前（before 位置），且未激活时呈灰色gray-400（暗色模式gray-500），激活后与文字一同变为主题色，视觉反馈一致。

调整图标位置

使用icon-position属性可以将图标放到标签文字之后：

<x-filament::tabs> <x-filament::tabs.item icon="heroicon-m-bell" icon-position="after" > Notifications </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

源码中icon-position会被规范化为Filament\Support\Enums\IconPosition枚举（默认Before），并在 Blade 模板中分别在标签之前/之后条件输出图标（item.blade.php）。需要注意的是，icon-position与badge-icon-position是不同的属性，前者控制选项卡图标的左右位置，后者控制徽章内图标的左右位置。

为选项卡设置徽章

选项卡可以显示徽章（Badge）用于展示计数等短文本，通过命名插槽badge提供内容：

<x-filament::tabs> <x-filament::tabs.item> Notifications <x-slot name="badge"> 5 </x-slot> </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

徽章的底层实现直接复用了x-filament::badge组件（item.blade.php），并支持badge-color、badge-icon、badge-icon-position、badge-tooltip等透传属性，尺寸固定为sm。当badge内容是一个ComponentSlot（即通过<x-slot>传入）时，内容会被原样输出；传入纯字符串时则交给 Badge 组件按颜色方案渲染。

面板页面子导航正是利用这一能力，为每个导航项渲染badge、badge-color与badge-tooltip（tabs.blade.php），可见 Tabs 组件不仅是独立 UI 元素，也是 Filament 页面导航体系的基础构件。

延迟加载徽章数据（Alpine 动态徽章）

除静态徽章外，item 组件还支持alpine-deferred-badge-data与alpine-deferred-badge-loading属性：当badge为空但提供了延迟数据表达式时，组件会先渲染一个加载指示器占位符，待 Alpine 数据就绪后通过x-if/x-bind动态渲染徽章及其图标、颜色与 Tooltip（item.blade.php）。这一机制适用于徽章内容依赖异步数据（如未读消息数）的场景。

将选项卡用作锚点链接

默认情况下，选项卡的底层 HTML 标签是<button>。通过tag属性可以改为<a>，从而支持 URL 跳转：

<x-filament::tabs> <x-filament::tabs.item :href="route('notifications')" tag="a" > Notifications </x-filament::tabs.item> {{-- Other tabs --}} </x-filament::tabs>

从源码看，当tag === 'a'时，href通过Filament\Support\generate_href_html()生成（item.blade.php）。该函数（helpers.php）会智能处理：

• 未传href时输出空字符串；
• 传了target="_blank"时附加target="_blank"；
• 否则若当前 URL 处于 SPA 模式，自动追加wire:navigate（启用 prefetch 时为wire:navigate.hover），使点击在面板 SPA 内完成无刷新导航。

此外target属性可在tag="a"时指定链接打开方式，type属性在tag="button"时控制按钮原生type（默认button，避免误触发表单提交）。

使用垂直选项卡

通过vertical属性可以将选项卡组渲染为垂直布局：

<x-filament::tabs vertical> <x-filament::tabs.item> Tab 1 </x-filament::tabs.item> <x-filament::tabs.item> Tab 2 </x-filament::tabs.item> <x-filament::tabs.item> Tab 3 </x-filament::tabs.item> </x-filament::tabs>

垂直模式下，容器追加fi-vertical类，CSS 将其切换为纵向 flex 排列、纵向溢出滚动，并将每个选项卡项改为左对齐（tabs.css）。垂直选项卡特别适合侧边栏式的内容分区导航（例如设置页的多个分组）。

容器属性：contained 与嵌套样式

虽然 docs/12-components/03-tabs.md 未展开说明，但从 index.blade.php 的属性声明中可以确认容器还支持contained布尔属性：非 contained 时标签条自带卡片底座（圆角、阴影、描边），contained 时则改为紧贴内容区的下边框样式（border-b），适用于嵌入在页面主体中的紧凑布局（tabs.css）。在垂直模式下，contained 会切换为右侧边框（border-e）。

实战组合示例

将以上特性组合，可以实现一个带图标、徽章、条件激活、Livewire 状态驱动的完整选项卡导航：

<x-filament::tabs label="Account settings"> <x-filament::tabs.item icon="heroicon-m-user" :active="$activeTab === 'profile'" wire:click="$set('activeTab', 'profile')" > Profile </x-filament::tabs.item> <x-filament::tabs.item icon="heroicon-m-bell" :active="$activeTab === 'notifications'" wire:click="$set('activeTab', 'notifications')" > Notifications <x-slot name="badge"> 5 </x-slot> </x-filament::tabs.item> <x-filament::tabs.item icon="heroicon-m-arrow-top-right-on-square" icon-position="after" :href="route('profile.public')" tag="a" > Public profile </x-filament::tabs.item> </x-filament::tabs>

也可以参考 Filament 面板自身对 Tabs 组件的真实应用：页面子导航视图 tabs.blade.php 将每个导航分组渲染为带图标的 Tabs item，并把激活态、徽章、链接目标统一交由该组件处理；其中无标签的分组直接渲染为tag="a"的 Tabs item，有标签的分组则用 dropdown 包裹，展示出该组件在实际面板代码中的灵活组合方式。

使用前提与组件归属

Tabs 组件由filament/support包提供。Filament 使用独立组件式安装时，需确保该包已安装，可通过composer show filament/support确认。组件样式位于 tabs.css，相关 JS 交互（SPA 导航、Alpine 动态徽章）由 Filament 前端资源统一加载；Blade 组件本身零依赖，直接复制上面的示例到任意 Filament 项目视图即可运行。若要深入定制外观，可结合 docs/08-styling/01-overview.md 与 docs/08-styling/02-css-hooks.md 中的 CSS 钩子机制覆写fi-tabs、fi-tabs-item等类；图标名体系可参考 docs/08-styling/04-icons.md，徽章组件能力可参考 docs/12-components/03-badge.md。

【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps & admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament