图片列

简介

表格可以根据列状态中的路径渲染图片：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')

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

或者，状态也可以包含图片的绝对 URL，例如 https://example.com/images/avatar.jpg。

设置 alt 文本

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

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->alt('User avatar')

TIP

除静态值外，alt() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中，包括当前图片的 $state。

若未设置任何 alt 文本，图片会以空的 alt 属性渲染，辅助技术会将其视为装饰性图片。

WARNING

当图片链接到 URL 时，其 alt 文本会成为该链接的可访问名称。务必为带链接的图片设置有意义的 alt() 文本，否则屏幕阅读器用户会遇到没有名称的链接。

管理图片磁盘

默认存储磁盘在配置文件中定义，默认为 local。你也可以设置 FILESYSTEM_DISK 环境变量来更改它。若要偏离默认磁盘，可以将自定义磁盘名传给 disk() 方法：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->disk('s3')

TIP

除静态值外，disk() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

公开图片

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

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->visibility('public')

TIP

除静态值外，visibility() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

自定义尺寸

你可以通过传入 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)

TIP

除静态值外，imageWidth()、imageHeight() 和 imageSize() 方法也接受函数以动态计算这些值。你可以将各种工具作为参数注入到函数中。

方形图片

你可以使用 1:1 宽高比显示图片：

use Filament\Tables\Columns\ImageColumn;

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

可选地，你可以传入布尔值来控制图片是否应为方形：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->square(FeatureFlag::active())

TIP

除静态值外，square() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

圆形图片

你可以将图片设为完全圆形，这在渲染头像时很有用：

use Filament\Tables\Columns\ImageColumn;

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

可选地，你可以传入布尔值来控制图片是否应为圆形：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('avatar')
    ->imageHeight(40)
    ->circular(FeatureFlag::active())

TIP

除静态值外，circular() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

添加默认图片 URL

若图片尚不存在，你可以通过向 defaultImageUrl() 方法传入 URL 来显示占位图片：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('header_image')
    ->defaultImageUrl(url('storage/posts/header-images/default.jpg'))

TIP

除静态值外，defaultImageUrl() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

堆叠图片

你可以使用 stacked() 将多张图片显示为重叠堆叠：

use Filament\Tables\Columns\ImageColumn;

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

可选地，你可以传入布尔值来控制图片是否应堆叠：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked(FeatureFlag::active())

TIP

除静态值外，stacked() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

自定义堆叠环宽度

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

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->ring(5)

TIP

除静态值外，ring() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

自定义堆叠重叠

默认重叠为 4，但你可以将其自定义为 0 到 8：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->overlap(2)

TIP

除静态值外，overlap() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

设置限制

你可以通过传入 limit() 限制要显示的最大图片数量：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)

TIP

除静态值外，limit() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

显示剩余图片数量

设置限制后，你还可以通过传入 limitedRemainingText() 显示剩余图片数量。

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText()

可选地，你可以传入布尔值来控制是否显示剩余文本：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText(FeatureFlag::active())

TIP

除静态值外，limitedRemainingText() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

自定义剩余文本尺寸

默认情况下，剩余文本的尺寸为 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)

TIP

除静态值外，limitedRemainingText() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

阻止文件存在性检查

加载 schema 时，系统会自动检测图片是否存在，以避免缺失文件导致错误。这一切都在后端完成。使用远程存储且图片较多时，这可能很耗时。你可以使用 checkFileExistence(false) 方法禁用此功能：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('attachment')
    ->checkFileExistence(false)

TIP

除静态值外，checkFileExistence() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

换行显示多张图片

若图片无法在一行内放下，可通过设置 wrap() 使其换行：

use Filament\Tables\Columns\ImageColumn;

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

TIP

换行所用的「宽度」会受列标签影响，因此你可能需要使用更短或隐藏的标签，以实现更紧凑的换行。

为图片添加额外 HTML 属性

你可以通过 extraImgAttributes() 方法向 <img> 元素传入额外 HTML 属性。属性应以数组表示，键为属性名，值为属性值：

use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('logo')
    ->extraImgAttributes([
        'alt' => 'Logo',
        'loading' => 'lazy',
    ])

TIP

除静态值外，extraImgAttributes() 方法也接受函数以动态计算该值。你可以将各种工具作为参数注入到函数中。

默认情况下，多次调用 extraImgAttributes() 会覆盖先前的属性。若希望合并属性，可以向该方法传入 merge: true。