提示框

简介

提示框（Callouts）用于突出重要信息或消息，常用于警告、通知或提示。可使用 Callout 组件创建提示框：

use Filament\Schemas\Components\Callout;

Callout::make('New version available')
    ->description('Filament v4 has been released with exciting new features and improvements.')
    ->info()

TIP

除了接受静态值外，make() 与 description() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

使用状态变体

提示框内置状态变体，会自动设置合适的图标、图标颜色与背景色。可使用 danger()、info()、success() 或 warning() 方法：

use Filament\Schemas\Components\Callout;

Callout::make('Payment successful')
    ->description('Your order has been confirmed and is being processed.')
    ->success()

Callout::make('Session expiring soon')
    ->description('Your session will expire in 5 minutes. Save your work to avoid losing changes.')
    ->warning()

Callout::make('Connection failed')
    ->description('Unable to connect to the server. Please check your internet connection.')
    ->danger()

状态变体的无访问性

由于提示框的状态通过图标与背景色在视觉上传达，Filament 也会向屏幕阅读器播报。使用状态变体时，会在提示框标题内渲染视觉上隐藏的严重程度前缀（Error:、Note:、Success: 或 Warning:），以便辅助技术用户先听到严重程度再听到消息。前置图标标记为装饰性（aria-hidden），不会单独播报。

提示框渲染为普通的 <div>，这对页面加载时即存在的内容是合适的。若动态显示提示框（例如操作完成后）并希望屏幕阅读器播报，可使用 extraAttributes() 启用 live region：

use Filament\Schemas\Components\Callout;

Callout::make('Changes saved')
    ->success()
    ->extraAttributes(['role' => 'status']) // Use `alert` instead of `status` for urgent messages

移除背景色

默认情况下，状态提示框带有彩色背景。可使用 color(null) 移除背景色，同时保留状态图标与图标颜色：

use Filament\Schemas\Components\Callout;

Callout::make('Scheduled maintenance')
    ->description('The system will be unavailable on Sunday from 2:00 AM to 4:00 AM.')
    ->warning()
    ->color(null)

TIP

除了接受静态值外，color() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

添加自定义图标

可使用 icon() 方法为提示框添加自定义 图标：

use Filament\Schemas\Components\Callout;
use Filament\Support\Icons\Heroicon;

Callout::make('Pro tip')
    ->description('You can use keyboard shortcuts to navigate faster. Press ? to see all available shortcuts.')
    ->icon(Heroicon::OutlinedLightBulb)

TIP

除了接受静态值外，icon() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

更改图标颜色

可使用 iconColor() 方法更改图标颜色：

use Filament\Schemas\Components\Callout;
use Filament\Support\Icons\Heroicon;

Callout::make('Pro tip')
    ->description('You can use keyboard shortcuts to navigate faster. Press ? to see all available shortcuts.')
    ->icon(Heroicon::OutlinedLightBulb)
    ->iconColor('primary')

TIP

除了接受静态值外，iconColor() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

更改图标大小

默认图标大小为「large」。可使用 iconSize() 方法改为「small」或「medium」：

use Filament\Schemas\Components\Callout;
use Filament\Support\Enums\IconSize;

Callout::make('Quick note')
    ->description('This callout has a smaller icon.')
    ->info()
    ->iconSize(IconSize::Small)

TIP

除了接受静态值外，iconSize() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

使用自定义背景色

可使用 color() 方法设置自定义背景色：

use Filament\Schemas\Components\Callout;
use Filament\Support\Icons\Heroicon;

Callout::make('Pro tip')
    ->description('You can use keyboard shortcuts to navigate faster. Press ? to see all available shortcuts.')
    ->color('primary')
    ->icon(Heroicon::OutlinedLightBulb)
    ->iconColor('primary')

在提示框页脚添加操作

可使用 actions() 方法在提示框页脚添加 操作：

use Filament\Actions\Action;
use Filament\Schemas\Components\Callout;

Callout::make('Your trial ends in 3 days')
    ->description('Upgrade now to keep access to all premium features.')
    ->warning()
    ->actions([
        Action::make('upgrade')
            ->label('Upgrade to Pro')
            ->button(),
        Action::make('compare')
            ->label('Compare plans'),
    ])

TIP

除了接受静态值外，actions() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

更改页脚操作对齐方式

默认情况下，操作对齐到起始端。可使用 footerActionsAlignment() 方法更改对齐方式：

use Filament\Actions\Action;
use Filament\Schemas\Components\Callout;
use Filament\Support\Enums\Alignment;

Callout::make('Updates available')
    ->description('New features and improvements are ready to install.')
    ->info()
    ->actions([
        Action::make('install')->label('Install Now'),
        Action::make('later')->label('Remind Me Later'),
    ])
    ->footerActionsAlignment(Alignment::End)

可用的对齐选项为 Alignment::Start、Alignment::Center、Alignment::End 与 Alignment::Between。

TIP

除了接受静态值外，footerActionsAlignment() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

添加自定义页脚内容

可使用 footer() 方法向页脚添加自定义内容。该方法接受 schema 组件数组：

use Filament\Actions\Action;
use Filament\Schemas\Components\Callout;
use Filament\Schemas\Components\Text;

Callout::make('Backup complete')
    ->description('Your data has been successfully backed up to the cloud.')
    ->success()
    ->footer([
        Text::make('Last backup: 5 minutes ago')
            ->color('gray'),
        Action::make('viewBackups')
            ->label('View All Backups')
            ->button(),
    ])

TIP

除了接受静态值外，footer() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

添加自定义控件内容

可使用 controls() 方法向控件区域（右上角）添加自定义内容。该方法接受 schema 组件数组：

use Filament\Actions\Action;
use Filament\Schemas\Components\Callout;

Callout::make('Backup complete')
    ->description('Your data has been successfully backed up to the cloud.')
    ->success()
    ->controls([
        Action::make('dismiss')
            ->icon('heroicon-m-x-mark')
            ->iconButton()
            ->color('gray'),
    ])

TIP

除了接受静态值外，controls() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

向提示框添加控件操作

可使用 controlActions() 方法在提示框右上角添加控件 操作。例如，可添加一个在用户会话期间隐藏提示框的关闭按钮：

use Filament\Actions\Action;
use Filament\Schemas\Components\Callout;
use Filament\Support\Icons\Heroicon;

Callout::make('New version available')
    ->description('Filament v4 has been released with exciting new features and improvements.')
    ->info()
    ->controlActions([
        Action::make('dismiss')
            ->icon(Heroicon::XMark)
            ->iconButton()
            ->color('gray')
            ->action(fn () => session()->put('new-version-callout-dismissed', true)),
    ])
    ->visible(fn (): bool => ! session()->get('new-version-callout-dismissed'))