跳到主要内容

版本：5.x

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。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 作为参数注入到该函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
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 <a href="https://laravel.com/docs/blade#the-loop-variable" target="_blank">row loop</a> 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 给该方法。

简介
设置 alt 文本
管理图片存储磁盘
公共图片
自定义大小
方形图片
圆形图片
添加默认图片 URL
堆叠图片
- 自定义堆叠环的宽度
- 自定义堆叠数
设置限制
- 显示剩余图片数
禁用文件存在性检查
图像换行
添加额外的 HTML 属性到图片中