Filament 中文文档

主题

全部文档

Enum 技巧 ​

简介 ​

Enums 是表示一组固定常量的特殊 PHP 类。适合建模可选值有限的概念，例如一周中的日子、一年中的月份，或扑克牌花色。

由于 enum「cases」是 enum 类的实例，为 enums 添加接口非常有用。Filament 提供一组可加到 enums 上的接口，以提升使用体验。

WARNING

在 Eloquent 模型属性上使用 enum 时，请确保正确进行 cast。

Enum 标签 ​

HasLabel 接口将 enum 实例转换为文本标签，便于在 UI 中显示可读的 enum 值。

php
use Filament\Support\Contracts\HasLabel;
use Illuminate\Contracts\Support\Htmlable;

enum Status: string implements HasLabel
{
    case Draft = 'draft';
    case Reviewing = 'reviewing';
    case Published = 'published';
    case Rejected = 'rejected';
    
    public function getLabel(): string | Htmlable | null
    {
        return $this->name;
        
        // or
    
        return match ($this) {
            self::Draft => 'Draft',
            self::Reviewing => 'Reviewing',
            self::Published => 'Published',
            self::Rejected => 'Rejected',
        };
    }
}

在表单字段选项中使用 enum 标签 ​

HasLabel 接口可用于从 enum 生成选项数组：以 enum 的值为键、标签为值。适用于 Select、CheckboxList 等表单字段，以及 Table Builder 的 SelectColumn 与 SelectFilter：

php
use Filament\Forms\Components\CheckboxList;
use Filament\Forms\Components\Radio;
use Filament\Forms\Components\Select;
use Filament\Tables\Columns\SelectColumn;
use Filament\Tables\Filters\SelectFilter;

Select::make('status')
    ->options(Status::class)

CheckboxList::make('status')
    ->options(Status::class)

Radio::make('status')
    ->options(Status::class)

SelectColumn::make('status')
    ->options(Status::class)

SelectFilter::make('status')
    ->options(Status::class)

这些示例中，Status::class 是实现了 HasLabel 的 enum 类，选项由此生成：

php
[
    'draft' => 'Draft',
    'reviewing' => 'Reviewing',
    'published' => 'Published',
    'rejected' => 'Rejected',
]

在表格文本列中使用 enum 标签 ​

若在 Table Builder 中使用 TextColumn，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasLabel 接口显示 enum 标签，而非原始值。

将 enum 标签用作表格分组标题 ​

若在 Table Builder 中使用分组，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasLabel 接口显示 enum 标签，而非原始值。标签会显示为每个分组的标题。

在 infolist 文本条目中使用 enum 标签 ​

若在 infolist 中使用 TextEntry，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasLabel 接口显示 enum 标签，而非原始值。

Enum 颜色 ​

HasColor 接口将 enum 实例转换为颜色，便于在 UI 中以色块/色标显示 enum 值。

php
use Filament\Support\Contracts\HasColor;

enum Status: string implements HasColor
{
    case Draft = 'draft';
    case Reviewing = 'reviewing';
    case Published = 'published';
    case Rejected = 'rejected';
    
    public function getColor(): string | array | null
    {
        return match ($this) {
            self::Draft => 'gray',
            self::Reviewing => 'warning',
            self::Published => 'success',
            self::Rejected => 'danger',
        };
    }
}

在表格文本列中使用 enum 颜色 ​

若在 Table Builder 中使用 TextColumn，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasColor 接口按对应颜色显示 enum 标签。在列上使用 badge() 时效果最佳。

在 infolist 文本条目中使用 enum 颜色 ​

若在 infolist 中使用 TextEntry，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasColor 接口按对应颜色显示 enum 标签。在条目上使用 badge() 时效果最佳。

在表单 toggle buttons 字段中使用 enum 颜色 ​

若使用 ToggleButtons 表单字段，并将其选项设为 enum，Filament 会自动用 HasColor 接口按对应颜色显示 enum 标签。

Enum 图标 ​

HasIcon 接口将 enum 实例转换为图标，便于在 UI 中与 enum 值一并显示图标。

php
use BackedEnum;
use Filament\Support\Contracts\HasIcon;
use Filament\Support\Icons\Heroicon;
use Illuminate\Contracts\Support\Htmlable;

enum Status: string implements HasIcon
{
    case Draft = 'draft';
    case Reviewing = 'reviewing';
    case Published = 'published';
    case Rejected = 'rejected';

    public function getIcon(): string | BackedEnum | Htmlable | null
    {
        return match ($this) {
            self::Draft => Heroicon::Pencil,
            self::Reviewing => Heroicon::Eye,
            self::Published => Heroicon::Check,
            self::Rejected => Heroicon::XMark,
        };
    }
}

在表格文本列中使用 enum 图标 ​

若在 Table Builder 中使用 TextColumn，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasIcon 接口在标签旁显示 enum 图标。在列上使用 badge() 时效果最佳。

在 infolist 文本条目中使用 enum 图标 ​

若在 infolist 中使用 TextEntry，且 Eloquent 模型中已将该属性 cast 为 enum，Filament 会自动用 HasIcon 接口在标签旁显示 enum 图标。在条目上使用 badge() 时效果最佳。

在表单 toggle buttons 字段中使用 enum 图标 ​

若使用 ToggleButtons 表单字段，并将其选项设为 enum，Filament 会自动用 HasIcon 接口在标签旁显示 enum 图标。

Enum 描述 ​

HasDescription 接口将 enum 实例转换为文本描述，通常显示在其标签下方，便于在 UI 中展示易读说明。

php
use Filament\Support\Contracts\HasDescription;
use Filament\Support\Contracts\HasLabel;
use Illuminate\Contracts\Support\Htmlable;

enum Status: string implements HasLabel, HasDescription
{
    case Draft = 'draft';
    case Reviewing = 'reviewing';
    case Published = 'published';
    case Rejected = 'rejected';
    
    public function getLabel(): string | Htmlable | null
    {
        return $this->name;
    }
    
    public function getDescription(): string | Htmlable | null
    {
        return match ($this) {
            self::Draft => 'This has not finished being written yet.',
            self::Reviewing => 'This is ready for a staff member to read.',
            self::Published => 'This has been approved by a staff member and is public on the website.',
            self::Rejected => 'A staff member has decided this is not appropriate for the website.',
        };
    }
}

在表单字段描述中使用 enum 描述 ​

HasDescription 接口可用于从 enum 生成描述数组：以 enum 的值为键、描述为值。适用于 Radio 与 CheckboxList 等表单字段：

php
use Filament\Forms\Components\CheckboxList;
use Filament\Forms\Components\Radio;

Radio::make('status')
    ->options(Status::class)

CheckboxList::make('status')
    ->options(Status::class)