标注框

#简介

标注框（Callout）用于高亮显示重要信息或提示。它们常用于警示、通知或提示信息。你可以使用 Callout 组件来创建标注：

use Filament\Schemas\Components\Callout;

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

As well as allowing static values, the make() and description() methods also accept functions to dynamically calculate them. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#使用状态变体

标注框（Callout）内置了状态变体，可自动设置相应的图标、图标颜色及背景颜色。你可以使用 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()

#Accessibility of status variants

Since a callout’s status is conveyed visually through its icon and background color, Filament also announces it to screen readers. When you use a status variant, a visually-hidden severity prefix (Error:, Note:, Success:, or Warning:) is rendered inside the callout’s heading, so assistive technology users hear the severity before the message. The leading icon is marked as decorative (aria-hidden) so it is not announced separately.

Callouts render as a plain <div>, which is correct for content that is present when the page loads. If you reveal a callout dynamically (for example, after an action completes) and want screen readers to announce it, opt into a live region using extraAttributes():

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)

As well as allowing a static value, the color() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#添加自定义图标

你可以使用 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)

As well as allowing a static value, the icon() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#更改图标颜色

你可以使用 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')

As well as allowing a static value, the iconColor() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#更改图标大小

默认情况下，图标大小为“大”（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)

As well as allowing a static value, the iconSize() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#使用自定义背景颜色

你可以使用 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')

#向标注框页脚添加 Action

你可以使用 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'),
    ])

As well as allowing a static value, the actions() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#更改页脚操作的对齐方式

默认情况下，Action 对齐到起始位置。你可以使用 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。

As well as allowing a static value, the footerActionsAlignment() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#添加自定义页脚内容

你可以使用 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(),
    ])

As well as allowing a static value, the footer() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#添加自定义控件内容

你可以使用 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'),
    ])

As well as allowing a static value, the controls() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#为标注框添加控制操作

你可以使用 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'))

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion