DOCS
DOCS

Languages

Version

Theme

表格 - Column

Image column

简介

表格中也可以基于列状态中的路径渲染图片：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')

此例中，avatar 状态值为 users/avatars/4281246003439.jpg，这是相对于存储磁盘根目录的路径。存储磁盘在配置文件中定义，默认为 local。你可以设置 FILESYSTEM_DISK 环境变量来修改它。

此外，该状态值也可以是图片的绝对 URL 路径，如 https://example.com/images/avatar.jpg。

Image column

设置 alt 文本

你应该为图片设置描述性的 alt 文本，以便屏幕阅读器用户能够理解每张图片展示的内容。请使用 alt() 方法：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->alt('User avatar')
除了允许静态值之外，alt() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中，包括当前图片的状态 $state。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

如果你未设置任何 alt 文本，该图像将以空的 alt 属性进行渲染，这向辅助阅读表明该图像属于装饰性内容。

NOTE

当图像链接到某个 URL 时，其 alt 文本将成为该链接的可访问名称。请务必为链接图像设置具有实际意义的 alt 文本，否则使用屏幕阅读器的用户将遇到一个没有名称的链接。

管理图片存储磁盘

默认存储磁盘在配置文件中定义，默认为 local。你也可以通过设置 FILESYSTEM_DISK 环境变量来更改此设置。如果你希望使用非默认磁盘，可以向 disk() 方法传入自定义的磁盘名称：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->disk('s3')
除了允许静态值之外，disk() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

公共图片

默认情况下，Filament 会为文件系统中的图片生成临时 URL，除非存储磁盘被设置为 public。如果图片存储在公共磁盘中，你可以将 visibility() 设置为 public：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->visibility('public')
除了允许静态值之外，visibility() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

自定义大小

你可以将图片宽高传入 imageWidth() 和 imageHeight() 中，或者将二者同时传入给 imageSize()，来自定义图片大小：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->imageWidth(200)

ImageColumn::make('header_image')
    ->imageHeight(50)

ImageColumn::make('avatar')
    ->imageSize(40)
Image column with custom size
除了允许静态值之外，imageWidth()、imageHeight() 和 imageSize() 方法也可以接受函数来动态计算它们的值。你可以将多个 utility 作为参数注入到函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

方形图片

你可以使用 1:1 比例尺展示图片：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->square()
Square image column

此外，你也可以传入一个布尔值，控制图片是否为方形：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->square(FeatureFlag::active())
除了允许静态值之外，square() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

圆形图片

你可以将图片设为圆形，这对渲染头像相当有用：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->circular()
Circular image column

此外，你也可以传入一个布尔值，控制图片是否为圆形：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->circular(FeatureFlag::active())
除了允许静态值之外，circular() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

添加默认图片 URL

将一个 URL 传入到 defaultImageUrl() 方法中，你可以在图片还不存在时，展示占位符图片：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->defaultImageUrl(url('storage/posts/header-images/default.jpg'))
除了允许静态值之外，defaultImageUrl() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

堆叠图片

使用 stacked()，你可以将多张图像以相互重叠的堆叠形式显示：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
Stacked image column

此外，你也可以传入一个布尔值，控制图片是否堆叠展示：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked(FeatureFlag::active())
除了允许静态值之外，stacked() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

自定义堆叠环的宽度

默认环宽为 3，但你可以将其自定义为 0 到 8 之间的值：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->ring(5)
Image column with stacked ring width
除了允许静态值之外，ring() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

自定义堆叠数

默认的堆叠数为 4，不过你可以使用 0 到 8 之间的数对其进行自定义：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->overlap(2)
Image column with stacked overlap
除了允许静态值之外，overlap() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

设置限制

使用 limit()，你可以限制要显示的图片数量最大值：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
除了允许静态值之外，limit() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.
Limited image column

显示剩余图片数

当设置限制时，你也可以传递 limitedRemainingText() 显示剩余的图片数量：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText()
Limited image column with remaining text

此外，你也可以传入一个布尔值，控制是否显示剩余数：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText(FeatureFlag::active())
除了允许静态值之外，limitedRemainingText() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

自定义剩余文本大小

默认情况下，剩余文本的大小是 TextSize::Small。你可以使用 size 参数将其自定义为 TextSize::ExtraSmall、TextSize::Medium 或 TextSize::Large：

use Filament\Tables\Columns\ImageColumn;
use Filament\Support\Enums\TextSize;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText(size: TextSize::Large)
除了允许静态值之外，limitedRemainingText() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

禁用文件存在性检查

加载 Schema 时，系统会自动检测图像是否存在，以避免因文件缺失而引发错误。此过程完全在后端执行。当使用包含大量图像的远程存储时，该过程可能会耗时较长。你可以使用 checkFileExistence(false) 方法来禁用此功能：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('attachment')
    ->checkFileExistence(false)
除了允许静态值之外，checkFileExistence() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

图像换行

如果图像无法在同一行内排列，可以通过设置 wrap() 让它们换行：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->circular()
    ->stacked()
    ->wrap()

TIP

换行时的“宽度”会受到列标签的影响，因此你可能需要使用较短或隐藏的标签，以实现更紧凑的换行效果。

添加额外的 HTML 属性到图片中

通过 extraImgAttributes() 方法，你可以传递额外的 HTML 属性给 <img> 元素。这些属性以数组的形式表示，数组的键为属性名，数组值是属性值：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('logo')
    ->extraImgAttributes([
        'alt' => 'Logo',
        'loading' => 'lazy',
    ])
除了允许静态值之外，extraImgAttributes() 方法也可以接受函数来动态计算其值。你可以将多个 utility 作为参数注入到该函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Column Filament\Tables\Columns\Column $column The current column instance.
Livewire Livewire\Component $livewire The Livewire component instance.
Eloquent record ?Illuminate\Database\Eloquent\Model $record The Eloquent record for the current table row.
Row loop stdClass $rowLoop The row loop object for the current table row.
State mixed $state The current value of the column, based on the current table row.
Table Filament\Tables\Table $table The current table instance.

默认情况下，多次调用 extraImgAttributes() 将会覆盖之前的属性设置。如果你想要合并属性，可以传入 merge:true 给该方法。

Edit on GitHub

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

Previous
Icon column
Next
Color column
Your logo here? 💖