README

Filament Toolbox 是 Filament 生态系统组件的集合。

安装

您可以通过 composer 安装此包

composer require unexpectedjourney/filament-toolbox

组件

• 表格列
  • 标题和详情列
  • 标志列

标题和详情列

标题和详情列是一种在同一列中显示两个单独值的方式。这可以通过 Filament 的 TextColumn 和 description() 原生实现，但它缺少一些功能，例如内置的详情限制和标题或详情被限制时的自动工具提示。

使用方法

创建一个 HeadingDetailColumn，就像创建一个 TextColumn 一样，然后链式调用 detail() 提供详情内容。

use UnexpectedJourney\FilamentToolbox\Tables\Columns\HeadingDetailColumn;

HeadingDetailColumn::make('sku')
    ->detail(fn(Product $record): string => $record->name)

要精确控制标题中显示的内容，可以使用 heading() 方法。

use UnexpectedJourney\FilamentToolbox\Tables\Columns\HeadingDetailColumn;

HeadingDetailColumn::make('sku')
    ->heading(fn(Product $record): string => str($record->sku)->upper())
    ->detail(fn(Product $record): string => $record->name)

使用 limit() 或 words() 方法对标题和详情中显示的字符数或单词数进行限制。当标题或详情被限制时，列会检测并添加必要的工具提示以显示完整内容。

HeadingDetailColumn::make('sku')
    ->detail(fn(Product $record): string => $record->name)
    ->limit(30)

使用 limitHeading()、wordsHeading()、limitDetail() 和 wordsDetail() 方法分别限制标题或详情中显示的字符数或单词数。将根据需要智能地添加工具提示。

HeadingDetailColumn::make('sku')
    ->detail(fn(Product $record): string => $record->name)
    ->limitHeading(100)
    ->limitDetail(30)

如果您不想显示工具提示，可以使用 showTooltipsWhenLimited() 禁用工具提示来处理标题和详情的工具提示显示，或者使用 showHeadingTooltipWhenLimited() 和 showDetailTooltipWhenLimited() 方法分别管理标题和详情的工具提示。

HeadingDetailColumn::make('sku')
    ->detail(fn(Product $record): string => $record->name)
    ->showTooltipsWhenLimited(false)
    ->limitDetail(30)

标志列

标志列用于显示模型上多个真/假值上的布尔图标。可以使用 Filament 内置的 IconColumn 获得类似的结果，但标志列有一些额外功能，如每个图标的工具提示或 URL，以及以网格显示图标。

使用方法

准备您的模型

您的模型需要一个返回数组的属性，其中键是标志的名称，值是激活状态。这可以是一个 JSON 列或自定义属性获取器。

添加列

将 FlagColumn 添加到您的列数组中，并调用 flags() 将一个 Flag 数组传递给它。每个 Flag 必须有一个名称，该名称与列状态中的标志名称相对应，以及一个可选的显示图标名称。

use UnexpectedJourney\FilamentToolbox\Tables\Columns\FlagColumn;
use UnexpectedJourney\FilamentToolbox\Tables\Columns\FlagColumn\Flag;

FLagColumn::make('flags')
    ->flags([
        Flag::make('trashed', 'heroicon-o-trash'),
        Flag::make('on_sale', 'heroicon-o-tag'),
        Flag::make('bundle', 'heroicon-o-archive-box')
    ])

注意：如果制作标志时使用的名称不是列状态中的键，则它将被视为不活跃。

如果您更喜欢使用专门的 icon() 方法指定图标，可以在指定图标的地方传递一个闭包而不是一个字符串。使用 Filament 的魔法闭包，添加 $active 作为其中一个参数以获取标志的激活状态。

FLagColumn::make('flags')
    ->flags([
        Flag::make('trashed', 'heroicon-o-trash'),
        Flag::make('on_sale', 'heroicon-o-tag'),
        Flag::make('bundle', 'heroicon-o-archive-box'),
        Flag::make('visible')
            ->icon(fn(bool $active): string => $active
                ? 'heroicon-o-eye'
                : 'heroicon-o-eye-slash')
        
    ])

自定义显示顺序

标志按照在 flags() 方法中出现的顺序显示，并且默认情况下不活跃的标志被隐藏。

显示不活跃的标志

要显示所有标志（包括不活跃的），请使用 FlagColumn 上的 showInactive() 方法。

FLagColumn::make('flags')
    ->showInactive()
    ->flags([
        Flag::make('trashed', 'heroicon-o-trash'),
        Flag::make('on_sale', 'heroicon-o-tag'),
        Flag::make('bundle', 'heroicon-o-archive-box')
    ])

显示或隐藏不活跃的标志也可以通过调用 showWhenInactive() 在每个标志的基础上进行。您可以为不活跃的图标传递一个闭包以条件性地显示图标。

FLagColumn::make('flags')
    ->flags([
        Flag::make('trashed', 'heroicon-o-trash')
            ->showWhenInactive(),
        Flag::make('on_sale', 'heroicon-o-tag'),
        Flag::make('bundle', 'heroicon-o-archive-box')
    ])

注意：在标志上使用 showWhenInactive() 将会覆盖在 FlagColumn 上调用的 showInactive()。

更改颜色

默认情况下，活动标志将使用 Filament 主题的主色，非活动标志将使用灰色。您可以通过调用 activeColor() 和 inactiveColor() 方法来为整个 FlagColumn 或每个特定的标志更改这些颜色。

注意：标志上定义的颜色将覆盖 FlagColumn 上定义的颜色。

use Filament\Support\Colors\Color;

FLagColumn::make('flags')
    ->activeColor('success')
    ->inactiveColor(Color::Stone)
    ->flags([
        Flag::make('trashed', 'heroicon-o-trash')
            ->activeColor('danger'),
        Flag::make('on_sale', 'heroicon-o-tag'),
        Flag::make('bundle', 'heroicon-o-archive-box')
    ])

默认图标

如果标志没有指定图标，将使用默认图标。默认活动图标是 'heroicon-o-check-circle'，默认非活动图标是 'heroicon-o-x-circle'。在 FlagColumn 上调用 'activeIcon()' 和 'inactiveIcon()' 方法来设置相应的图标。

FLagColumn::make('flags')
    ->activeIcon('heroicon-o-check')
    ->inactiveIcon('heroicon-o-x-mark')
    ->flags([...])

自定义网格

默认情况下，FlagColumn 以 3 个图标的网格显示标志。这与 Filament 布局组件如 Filament\Tables\Columns\Layout\Grid 控制网格的方式类似。调用 columns()。有关更多信息，请参阅 Filament 的文档：https://filamentphp.com/docs/3.x/tables/layout#controlling-column-width-using-a-grid

##### Tooltips
Tooltips are hidden by default but can be shown for all flags calling the `showTooltips()` method on the `FlagColumn`. 

```PHP
FLagColumn::make('flags')
    ->showTooltips()
    ->flags([...])

工具提示是自动从标志名称生成的标题化字符串。您可以通过在单个标志上调用 tooltip() 方法来指定自己的工具提示。您可以将闭包传递给此方法，并通过添加 $active 参数来访问标志的活动状态。

FLagColumn::make('flags')
    ->showTooltips()
    ->flags([
        Flag::make('published', 'heroicon-o-calendar')
            ->tootip(fn(bool $active, Model $record): string => $active 
                ? 'Published on '.$record->published_at
                : 'Not published')
    ])

注意：即使 FlagColumn 没有配置为显示工具提示，当工具提示显式设置时，标志总会显示工具提示。

网址

每个标志都可以可选地成为一个链接。通过在标志上调用 url() 方法将其转换为链接。此方法接受一个字符串或一个闭包。您可以通过向您的闭包添加 $active 参数来访问标志的活动状态。

FLagColumn::make('flags')
    ->showTooltips()
    ->flags([
        Flag::make('published', 'heroicon-o-calendar')
            ->url(fn(bool $active, Model $record): ?string => $active 
                ? $record->getUrl()
                : null)
    ])

您可以通过设置 url() 方法的 openInNewTab 参数或通过在标志上调用专门的 openUrlInNewTab() 方法来在新标签页中打开网址。

FLagColumn::make('flags')
    ->showTooltips()
    ->flags([
        Flag::make('published', 'heroicon-o-calendar')
            ->url(...)
            ->openUrlInNewTab()
    ])

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全漏洞

请查看我们关于如何报告安全漏洞的 安全策略。

鸣谢

• Rhiannon Journey
• 所有贡献者

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件。