Prime 组件

简介

在 Filament schema 中，prime 组件是最基础的构建块，可用于向 schema 插入任意内容，例如文本和图片。顾名思义，prime 组件不可再分、无法再简化。Filament 提供一组内置 prime 组件：

Text
Icon
Image
Unordered list

你也可以创建自己的自定义组件，向 schema 添加任意内容。

本例中，prime 组件用于向用户显示说明、可扫描的 QR 码，以及用户可保存的恢复码列表：

php

use Filament\Actions\Action;
use Filament\Schemas\Components\Image;
use Filament\Schemas\Components\Section;
use Filament\Schemas\Components\Text;
use Filament\Schemas\Components\UnorderedList;
use Filament\Support\Enums\FontWeight;
use Filament\Support\Enums\TextSize;

$schema
    ->components([
        Text::make('Scan this QR code with your authenticator app:')
            ->color('neutral'),
        Image::make(
            url: asset('images/qr.jpg'),
            alt: 'QR code to scan with an authenticator app',
        )
            ->imageHeight('12rem')
            ->alignCenter(),
        Section::make()
            ->schema([
                Text::make('Please save the following recovery codes in a safe place. They will only be shown once, but you\'ll need them if you lose access to your authenticator app:')
                    ->weight(FontWeight::Bold)
                    ->color('neutral'),
                UnorderedList::make(fn (): array => array_map(
                    fn (string $recoveryCode): Text => Text::make($recoveryCode)
                        ->copyable()
                        ->fontFamily(FontFamily::Mono)
                        ->size(TextSize::ExtraSmall)
                        ->color('neutral'),
                    ['tYRnCqNLUx-3QOLNKyDiV', 'cKok2eImKc-oWHHH4VhNe', 'C0ZstEcSSB-nrbyk2pv8z', '49EXLRQ8MI-FpWywpSDHE', 'TXjHnvkUrr-KuiVJENPmJ', 'BB574ookll-uI20yxP6oa', 'BbgScF2egu-VOfHrMtsCl', 'cO0dJYqmee-S9ubJHpRFR'],
                ))
                    ->size(TextSize::ExtraSmall),
            ])
            ->compact()
            ->secondary(),
    ])

虽然可用 infolist 文本条目在 schema 中渲染文本，但条目旨在渲染关于实体（如 Eloquent 模型）的标签-值详情，而非任意文本。Prime 组件更适合此用途。Infolist 可视为更接近 HTML 中的描述列表。

Prime 组件类位于 Filament\Schemas\Components 命名空间，置于 schema 的组件数组中。

Text 组件

可使用 Text 组件向 schema 插入文本。文本内容传给 make() 方法：

php

use Filament\Schemas\Components\Text;

Text::make('Modifying these permissions may give users access to sensitive information.')

要渲染原始 HTML 内容，可向 make() 方法传入 HtmlString 对象：

php

use Filament\Schemas\Components\Text;
use Illuminate\Support\HtmlString;

Text::make(new HtmlString('<strong>Warning:</strong> Modifying these permissions may give users access to sensitive information.'))

DANGER

请注意，你需要确保 HTML 可安全渲染，否则应用将面临 XSS 攻击风险。

要渲染 Markdown，可使用 Laravel 的 str() 辅助函数将 Markdown 转为 HTML，再转换为 HtmlString 对象：

php

use Filament\Schemas\Components\Text;

Text::make(
    str('**Warning:** Modifying these permissions may give users access to sensitive information.')
        ->inlineMarkdown()
        ->toHtmlString(),
)

TIP

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

自定义文本颜色

可为文本设置颜色：

php

use Filament\Schemas\Components\Text;

Text::make('Information')
    ->color('info')

TIP

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

使用中性色

默认情况下，文本颜色为 gray，相对背景通常较暗淡。可使用 color('neutral') 方法使其更深：

php

use Filament\Schemas\Components\Text;

Text::make('Modifying these permissions may give users access to sensitive information.')

Text::make('Modifying these permissions may give users access to sensitive information.')
    ->color('neutral')

显示为「徽章」

默认情况下，文本较朴素且无背景色。可使用 badge() 方法使其显示为「徽章」。很好的用例是状态：你可能希望显示与状态匹配颜色的徽章：

php

use Filament\Schemas\Components\Text;

Text::make('Warning')
    ->color('warning')
    ->badge()

也可传入布尔值，以控制文本是否显示为徽章：

php

use Filament\Schemas\Components\Text;

Text::make('Warning')
    ->color('warning')
    ->badge(FeatureFlag::active())

TIP

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

为徽章添加图标

可为徽章添加其他内容，例如图标：

php

use Filament\Schemas\Components\Text;
use Filament\Support\Icons\Heroicon;

Text::make('Warning')
    ->color('warning')
    ->badge()
    ->icon(Heroicon::ExclamationTriangle)

自定义文本大小

文本默认使用较小字号，可改为 TextSize::ExtraSmall、TextSize::Medium 或 TextSize::Large。

例如，可使用 size(TextSize::Large) 放大文本：

php

use Filament\Schemas\Components\Text;
use Filament\Support\Enums\TextSize;

Text::make('Modifying these permissions may give users access to sensitive information.')
    ->size(TextSize::Large)

自定义字重

文本条目默认使用常规字重，可改为以下任一选项：FontWeight::Thin、FontWeight::ExtraLight、FontWeight::Light、FontWeight::Medium、FontWeight::SemiBold、FontWeight::Bold、FontWeight::ExtraBold 或 FontWeight::Black。

例如，可使用 weight(FontWeight::Bold) 加粗字体：

php

use Filament\Schemas\Components\Text;
use Filament\Support\Enums\FontWeight;

Text::make('Modifying these permissions may give users access to sensitive information.')
    ->weight(FontWeight::Bold)

TIP

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

自定义字体系列

可将文本字体系列改为以下任一选项：FontFamily::Sans、FontFamily::Serif 或 FontFamily::Mono。

例如，可使用 fontFamily(FontFamily::Mono) 使用等宽字体：

php

use Filament\Support\Enums\FontFamily;
use Filament\Schemas\Components\Text;

Text::make('28o.-AK%D~xh*.:[4"3)zPiC')
    ->fontFamily(FontFamily::Mono)

TIP

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

可使用 tooltip() 方法为文本添加工具提示：

php

use Filament\Schemas\Components\Text;

Text::make('28o.-AK%D~xh*.:[4"3)zPiC')
    ->tooltip('Your secret recovery code')

TIP

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

使用 JavaScript 确定文本内容

可使用 JavaScript 确定文本内容。若要根据表单字段的状态显示不同消息，且无需向服务器请求重新渲染 schema，这会很有用。为此可使用 js() 方法：

php

use Filament\Schemas\Components\Text;

Text::make(<<<'JS'
    $get('name') ? `Hello, ${$get('name')}` : 'Please enter your name.'
    JS)
    ->js()

$state 与 $get() 工具在 JavaScript 上下文中可用，因此可用它们获取 schema 中字段的状态。

Icon 组件

可使用 Icon 组件向 schema 插入图标。图标传给 make() 方法：

php

use Filament\Schemas\Components\Icon;
use Filament\Support\Icons\Heroicon;

Icon::make(Heroicon::Star)

TIP

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

自定义图标颜色

可为图标设置颜色：

php

use Filament\Schemas\Components\Icon;
use Filament\Support\Icons\Heroicon;

Icon::make(Heroicon::ExclamationCircle)
    ->color('danger')

TIP

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

自定义图标大小

默认图标大小为 IconSize::Medium，也可自定义为 IconSize::ExtraSmall、IconSize::Small、IconSize::Large、IconSize::ExtraLarge 或 IconSize::TwoExtraLarge：

php

use Filament\Schemas\Components\Icon;
use Filament\Support\Enums\IconSize;
use Filament\Support\Icons\Heroicon;

Icon::make(Heroicon::Star)
    ->size(IconSize::Large)

TIP

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

可使用 tooltip() 方法为图标添加工具提示：

php

use Filament\Schemas\Components\Icon;
use Filament\Support\Icons\Heroicon;

Icon::make(Heroicon::ExclamationTriangle)
    ->tooltip('Warning')

TIP

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

Image 组件

可使用 Image 组件向 schema 插入图片。图片 URL 与替代文本传给 make() 方法：

php

use Filament\Schemas\Components\Image;

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)

TIP

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

自定义图片大小

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

php

use Filament\Schemas\Components\Image;

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->imageWidth('12rem')

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->imageHeight('12rem')

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->imageSize('12rem')

TIP

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

对齐图片

可使用 alignStart()、alignCenter() 或 alignEnd() 方法将图片对齐到起始端（从左到右界面为左，从右到左界面为右）、居中或末端（从左到右界面为右，从右到左界面为左）：

php

use Filament\Schemas\Components\Image;

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->alignStart() // This is the default alignment.

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->alignCenter()

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->alignEnd()

或者，也可向 alignment() 方法传入 Alignment 枚举：

php

use Filament\Schemas\Components\Image;
use Filament\Support\Enums\Alignment;

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->alignment(Alignment::Center)

TIP

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

可使用 tooltip() 方法为图片添加工具提示：

php

use Filament\Schemas\Components\Image;

Image::make(
    url: asset('images/qr.jpg'),
    alt: 'QR code to scan with an authenticator app',
)
    ->tooltip('Scan this QR code with your authenticator app')
    ->alignCenter()

TIP

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

无序列表组件

可使用 UnorderedList 组件向 schema 插入无序列表。列表项由纯文本或文本组件组成，传给 make() 方法：

php

use Filament\Schemas\Components\UnorderedList;

UnorderedList::make([
    'Tables',
    'Schemas',
    'Actions',
    'Notifications',
])

TIP

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

可将文本组件用作列表项，从而自定义每一项的格式：

php

use Filament\Schemas\Components\Text;
use Filament\Schemas\Components\UnorderedList;
use Filament\Support\Enums\FontFamily;

UnorderedList::make([
    Text::make('Tables')->fontFamily(FontFamily::Mono),
    Text::make('Schemas')->fontFamily(FontFamily::Mono),
    Text::make('Actions')->fontFamily(FontFamily::Mono),
    Text::make('Notifications')->fontFamily(FontFamily::Mono),
])

自定义项目符号大小

若正在修改列表内容的文本大小，可能也希望调整项目符号大小以匹配。为此可使用 size() 方法。项目符号默认使用较小字号，可改为 TextSize::ExtraSmall、TextSize::Medium 或 TextSize::Large。

例如，可使用 size(TextSize::Large) 放大项目符号：

php

use Filament\Schemas\Components\Text;
use Filament\Schemas\Components\UnorderedList;

UnorderedList::make([
    Text::make('Tables')->size(TextSize::Large),
    Text::make('Schemas')->size(TextSize::Large),
    Text::make('Actions')->size(TextSize::Large),
    Text::make('Notifications')->size(TextSize::Large),
])
    ->size(TextSize::Large)

TIP

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

为 prime 组件添加额外 HTML 属性

可通过 extraAttributes() 方法向组件传入额外 HTML 属性，它们会合并到其外层 HTML 元素上。属性应以数组表示，键为属性名，值为属性值：

php

use Filament\Schemas\Components\Text;

Text::make('Modifying these permissions may give users access to sensitive information.')
    ->extraAttributes(['class' => 'custom-text-style'])

TIP

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

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

Prime 组件 ​

简介 ​

Text 组件 ​

自定义文本颜色 ​

使用中性色 ​

显示为「徽章」 ​

为徽章添加图标 ​

自定义文本大小 ​

自定义字重 ​

自定义字体系列 ​

为文本添加工具提示 ​

使用 JavaScript 确定文本内容 ​

Icon 组件 ​

自定义图标颜色 ​

自定义图标大小 ​

为图标添加工具提示 ​

Image 组件 ​

自定义图片大小 ​

对齐图片 ​

为图片添加工具提示 ​

无序列表组件 ​

自定义项目符号大小 ​

为 prime 组件添加额外 HTML 属性 ​

Prime 组件

简介

Text 组件

自定义文本颜色

使用中性色

显示为「徽章」

为徽章添加图标

自定义文本大小

自定义字重

自定义字体系列

为文本添加工具提示

使用 JavaScript 确定文本内容

Icon 组件

自定义图标颜色

自定义图标大小

为图标添加工具提示

Image 组件

自定义图片大小

对齐图片

为图片添加工具提示

无序列表组件

自定义项目符号大小

为 prime 组件添加额外 HTML 属性