Filament 中文文档

主题

全部文档

图片条目 ​

简介 ​

Infolist 可根据条目状态中的路径渲染图片：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('header_image')

此时，header_image 状态可能包含 posts/header-images/4281246003439.jpg，该路径相对于存储磁盘的根目录。存储磁盘在 配置文件 中定义，默认为 local。也可设置 FILESYSTEM_DISK 环境变量来更改。

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

图片条目图片条目

设置替代文本 ​

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

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('header_image')
    ->alt('Article header image')

TIP

除了接受静态值外，alt() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数，包括当前图片的 $state，这在条目渲染多张图片时很有用。

若未设置任何替代文本，图片会以空的 alt 属性渲染，对辅助技术而言会标记为装饰性图片。

WARNING

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

管理图片磁盘 ​

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

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

公开图片 ​

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

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

自定义大小 ​

可通过传入 imageWidth() 与 imageHeight()，或使用 imageSize() 同时设置两者来自定义图片大小：

php
use Filament\Infolists\Components\ImageEntry;

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

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

ImageEntry::make('author.avatar')
    ->imageSize(40)

TIP

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

自定义大小的图片条目自定义大小的图片条目

方形图片 ​

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

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('author.avatar')
    ->imageHeight(40)
    ->square()
方形图片条目方形图片条目

也可传入布尔值，以控制图片是否方形：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('author.avatar')
    ->imageHeight(40)
    ->square(FeatureFlag::active())

TIP

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

圆形图片 ​

可将图片设为完全圆角，适合渲染头像：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('author.avatar')
    ->imageHeight(40)
    ->circular()
圆形图片条目圆形图片条目

也可传入布尔值，以控制图片是否圆形：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('author.avatar')
    ->imageHeight(40)
    ->circular(FeatureFlag::active())

TIP

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

添加默认图片 URL ​

若尚无图片，可通过向 defaultImageUrl() 方法传入 URL 来显示占位图：

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

堆叠图片 ​

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

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
堆叠图片条目堆叠图片条目

也可传入布尔值，以控制图片是否堆叠：

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

自定义堆叠环宽度 ​

默认环宽度为 3，可自定义为 0 到 8：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->ring(5)
自定义堆叠环宽度的图片条目自定义堆叠环宽度的图片条目

TIP

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

自定义堆叠重叠 ​

默认重叠为 4，可自定义为 0 到 8：

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->overlap(2)
自定义堆叠重叠的图片条目自定义堆叠重叠的图片条目

TIP

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

设置数量限制 ​

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

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

限制数量的图片条目限制数量的图片条目

显示剩余图片数量 ​

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

php
use Filament\Infolists\Components\ImageEntry;

ImageEntry::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText()
带剩余数量文本的限制图片条目带剩余数量文本的限制图片条目

也可传入布尔值，以控制是否显示剩余数量文本：

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

自定义剩余数量文本大小 ​

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

php
use Filament\Infolists\Components\ImageEntry;
use Filament\Support\Enums\TextSize;

ImageEntry::make('colleagues.avatar')
    ->imageHeight(40)
    ->circular()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText(size: TextSize::Large)

TIP

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

阻止文件存在性检查 ​

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

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

为图片添加额外 HTML 属性 ​

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

php
use Filament\Infolists\Components\ImageEntry;

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

TIP

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

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