企业官网建设流程全解析

Filament Link 组件实战指南：用<x-filament::link>构建可交互的链接与按钮

【免费下载链接】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（v4）内置的 Link Blade 组件用于渲染一个可点击、可执行动作的链接元素，是搭建管理后台界面时最常用的基础组件之一。本文以官方文档 docs/12-components/03-link.md 为主线，结合 support 包源码深入讲解tag、size、weight、color、icon、tooltip、badge等全部属性的用法与底层实现，读完即可在 Filament Panel、自定义页面或 Blade 视图中熟练使用。

基础用法：渲染一个链接

Link 组件通过 Blade 组件标签<x-filament::link>使用，最基本的写法是传入href属性并在标签体内写入链接文字：

<x-filament::link :href="route('users.create')"> New user </x-filament::link>

渲染出的 HTML 默认是<a>标签，并携带 Filament 的样式类fi-link（参见 packages/support/resources/css/components/link.css），其颜色默认使用主题色（primary）。

组件的所有可配置属性都定义在视图文件 packages/support/resources/views/components/link.blade.php 的@props中，包括badge、badgeColor、badgeSize、color、disabled、form、formId、href、icon、iconAlias、iconPosition、iconSize、keyBindings、labelSrOnly、loadingIndicator、size、spaMode、tag、target、tooltip、type、weight等。下文逐一讲解常用属性。

把链接变成按钮：tag 属性

默认情况下 Link 组件渲染为<a>标签。当你想用链接的外观去触发一个前端交互（比如 Livewire 事件）而不是页面跳转时，可以通过tag="button"把底层标签切换为<button>：

<x-filament::link wire:click="openNewUserModal" tag="button" > New user </x-filament::link>

从 link.blade.php 的渲染逻辑可以看出：

• tag="button"时组件会把wire:click等事件属性直接透传到<button>上，并自动附加type="button"；
• 同时会挂上wire:loading.attr="disabled"，即请求进行中时自动禁用按钮，防止重复提交；
• 若tag="a"，则通过generate_href_html($href, $target === '_blank', $spaMode)生成href，并支持target="_blank"与 SPA 模式下的软导航处理。

tag属性还支持form值：此时组件会额外包裹一层<form>，内部渲染为提交按钮（type="submit"），适合用于表单提交场景。

设置链接尺寸：size 属性

默认尺寸为 medium（md）。通过size属性可以切换为小、大、特大、超特大：

<x-filament::link size="sm"> New user </x-filament::link> <x-filament::link size="lg"> New user </x-filament::link> <x-filament::link size="xl"> New user </x-filament::link> <x-filament::link size="2xl"> New user </x-filament::link>

这里需要说明文档与实现的一个细节差异：文档示例中的2xl属于自定义字符串尺寸（直接作为 CSS 类fi-size-2xl输出，需要你自己提供对应的 Tailwind 类）；而组件内置的枚举尺寸定义在 packages/support/src/Enums/Size.php，实际包含xs、sm、md、lg、xl五种：

enum Size: string { case ExtraSmall = 'xs'; case Small = 'sm'; case Medium = 'md'; case Large = 'lg'; case ExtraLarge = 'xl'; }

源码 link.blade.php 中，命中枚举的尺寸会映射为fi-size-{value}类，未命中的字符串则原样作为 class 输出。对应样式在 link.css：fi-size-xs为text-xs、fi-size-sm为text-sm，md/lg/xl三者统一为text-sm并加大图标与文字间距。

设置字体粗细：weight 属性

默认字重为semibold。可取值包括thin、extralight、light、normal、medium、semibold、bold、extrabold、black：

<x-filament::link weight="thin"> New user </x-filament::link> <x-filament::link weight="normal"> New user </x-filament::link> <x-filament::link weight="semibold"> New user </x-filament::link> <x-filament::link weight="black"> New user </x-filament::link>

这些取值与枚举 packages/support/src/Enums/FontWeight.php 一一对应，命中枚举时渲染为fi-font-{value}类，未命中时原样作为 class 输出。

除了内置字重，你也可以直接传入自定义 CSS 类，例如利用 Tailwind 的任意值语法覆盖字重：

<x-filament::link weight="md:font-[650]"> New user </x-filament::link>

更改链接颜色：color 属性

默认颜色为 primary（主题色）。可切换为danger、gray、info、success、warning：

<x-filament::link color="danger"> New user </x-filament::link> <x-filament::link color="gray"> New user </x-filament::link> <x-filament::link color="info"> New user </x-filament::link> <x-filament::link color="success"> New user </x-filament::link> <x-filament::link color="warning"> New user </x-filament::link>

颜色的底层渲染由 packages/support/src/View/Components/LinkComponent.php 中的getColorMap()完成：它通过ComponentColorMap::make($color)把颜色值映射为text与dark:text两套 CSS 变量（浅色模式使用gray[50]作为表面色、默认取 900 号色阶；深色模式则从最深色阶开始取gray[700]表面色、默认取 200 号色阶），最终由 link.css 中的.fi-color规则以text-(--text)/dark:text-(--dark-text)的形式生效。链接未显式着色时，内部图标默认呈现灰阶（text-gray-400 dark:text-gray-500）。

为链接添加图标：icon 与 icon-position

通过icon属性可以给链接加一个图标（图标相关用法参见 docs/08-styling/04-icons.md）：

<x-filament::link icon="heroicon-m-sparkles"> New user </x-filament::link>

默认图标显示在文字之前；使用icon-position="after"可将其移到文字之后：

<x-filament::link icon="heroicon-m-sparkles" icon-position="after" > New user </x-filament::link>

icon-position对应枚举 packages/support/src/Enums/IconPosition.php，只有before与after两个值。在 link.blade.php 中，图标通过generate_icon_html()渲染在文字前后对应位置。此外还有两个进阶属性：

• icon-alias：通过别名解析图标（配合FilamentIcon注册的别名体系使用）；
• icon-size：控制图标尺寸，当链接尺寸为xs/sm时默认使用IconSize::Small，其余尺寸下由图标默认值决定（见 link.blade.php）。

为链接添加提示：tooltip 属性

tooltip属性可以为链接添加悬浮提示：

<x-filament::link tooltip="Register a user"> New user </x-filament::link>

从 link.blade.php 可以看到，tooltip 通过 Alpine 指令x-tooltip实现，支持主题跟随（theme: $store.theme），且当tooltip是Htmlable实例时允许渲染 HTML 内容（allowHTML）。工具提示还配合了禁用的行为联动：当链接disabled且带 tooltip 时，href、x-on:、wire:click等属性会被过滤，仅保留 tooltip 展示（见 link.blade.php）。

在链接上叠加徽章：badge 插槽与 badge-color

你可以通过badge插槽在链接右上角叠加一个徽章（badge），常用于未读数量等场景：

<x-filament::link> Mark notifications as read <x-slot name="badge"> 3 </x-slot> </x-filament::link>

徽章的颜色默认也是 primary，可通过badge-color属性单独更改：

<x-filament::link badge-color="danger"> Mark notifications as read <x-slot name="badge"> 3 </x-slot> </x-filament::link>

徽章的完整样式体系参见 docs/12-components/03-badge.md（其中 更改徽章颜色 一节列出了全部可用颜色）。在实现上（link.blade.php），徽章被包裹在.fi-link-badge-ctn容器中，通过绝对定位置于链接右上角（start-full、-translate-y-3/4，RTL 下自动镜像），并复用BadgeComponent的颜色映射与fi-size-{size}尺寸类；徽章默认尺寸为xs（Size::ExtraSmall），也可以用badge-size属性覆盖。

其他进阶属性

• disabled：禁用链接，渲染aria-disabled="true"与disabled属性，样式上降为opacity-70且不可点击（带 tooltip 时保留提示，见 link.css）；
• key-bindings：为链接绑定键盘快捷键，底层通过x-mousetrap.global实现，按下快捷键即触发点击（link.blade.php）；
• label-sr-only：隐藏文字但保留给屏幕阅读器（渲染为aria-label，并对 HTML 内容做转义防注入，见 link.blade.php）；
• loading-indicator（默认开启）：当链接带wire:click/wire:target或为表单提交按钮时，自动显示加载指示器并在请求期间禁用（link.blade.php）；
• spa-mode：控制是否使用 Filament 的 SPA 软导航模式生成href。

源码中的双实现路径

从源码结构看，Link 组件的渲染逻辑存在两条等价的实现路径：

1. Blade 视图渲染：packages/support/resources/views/components/link.blade.php 是组件标签的主要入口，@props声明全部属性后逐段拼装 HTML；
2. PHP 字符串生成：support 包还提供了 trait packages/support/src/View/Concerns/CanGenerateLinkHtml.php，其中的generateLinkHtml()方法以纯 PHP 方式生成同样的标记，供非 Blade 上下文（例如需要动态生成 HTML 字符串的组件）复用，二者共享相同的属性解析、颜色映射与加载指示器逻辑。

两条路径最终都依赖LinkComponent::getColorMap()计算颜色变量、fi-link基类以及fi-size-*、fi-font-*修饰类，保证了视觉与行为的一致性。

小结

<x-filament::link>是 Filament 中"看起来像链接、用起来像按钮"的通用交互元素：tag决定底层语义标签，size/weight/color控制外观，icon/tooltip/badge增强信息表达，disabled/key-bindings/loading-indicator则覆盖了表单与键盘可达性等实战细节。无论你是要在资源页面、自定义页面还是普通 Blade 视图中放置一个可操作的文本入口，直接组合上述属性即可获得与 Filament 主题一致、并天然支持 Livewire 交互与无障碍访问的最终效果。

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