文本条目

简介

文本条目显示简单文本：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('title')

自定义颜色

可为文本设置颜色：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('status')
    ->color('primary')

TIP

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

添加图标

文本条目也可有图标：

php

use Filament\Infolists\Components\TextEntry;
use Filament\Support\Icons\Heroicon;

TextEntry::make('email')
    ->icon(Heroicon::Envelope)

TIP

icon() 方法也接受函数以动态计算图标。你可以将各种工具作为参数注入该函数。

可使用 iconPosition() 设置图标位置：

php

use Filament\Infolists\Components\TextEntry;
use Filament\Support\Enums\IconPosition;
use Filament\Support\Icons\Heroicon;

TextEntry::make('email')
    ->icon(Heroicon::Envelope)
    ->iconPosition(IconPosition::After) // `IconPosition::Before` or `IconPosition::After`

TIP

iconPosition() 方法也接受函数以动态计算图标位置。你可以将各种工具作为参数注入该函数。

图标颜色默认为文本颜色，但可使用 iconColor() 单独自定义图标颜色：

php

use Filament\Infolists\Components\TextEntry;
use Filament\Support\Icons\Heroicon;

TextEntry::make('email')
    ->icon(Heroicon::Envelope)
    ->iconColor('primary')

TIP

iconColor() 方法也接受函数以动态计算图标颜色。你可以将各种工具作为参数注入该函数。

显示为「徽章」

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

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('status')
    ->badge()
    ->color(fn (string $state): string => match ($state) {
        'draft' => 'gray',
        'reviewing' => 'warning',
        'published' => 'success',
        'rejected' => 'danger',
    })

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

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

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('status')
    ->badge(FeatureFlag::active())

TIP

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

格式化

使用文本条目时，你可能希望 UI 中实际输出的文本与条目的原始状态不同，后者通常自动从 Eloquent 模型检索。格式化状态可在保留原始数据完整性的同时，以更友好的方式呈现。

要在不更改状态本身的情况下格式化文本条目的状态，可使用 formatStateUsing() 方法。该方法接受以状态为参数并返回格式化状态的函数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('status')
    ->formatStateUsing(fn (string $state): string => __("statuses.{$state}"))

此时，数据库中的 status 列可能包含 draft、reviewing、published 或 rejected 等值，但格式化后的状态会是这些值的翻译版本。

TIP

传给 formatStateUsing() 的函数可将各种工具作为参数注入。

日期格式化

除了向 formatStateUsing() 传入函数外，还可使用 date()、dateTime() 与 time() 方法，用 PHP 日期格式化令牌格式化条目状态：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->date()

TextEntry::make('created_at')
    ->dateTime()

TextEntry::make('created_at')
    ->time()

可通过向 date()、dateTime() 或 time() 方法传入自定义格式字符串来自定义日期格式。可使用任意 PHP 日期格式化令牌：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->date('M j, Y')
    
TextEntry::make('created_at')
    ->dateTime('M j, Y H:i:s')
    
TextEntry::make('created_at')
    ->time('H:i:s')

TIP

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

使用 Carbon 宏格式进行日期格式化

也可使用 isoDate()、isoDateTime() 与 isoTime() 方法，用 Carbon 的宏格式格式化条目状态：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->isoDate()

TextEntry::make('created_at')
    ->isoDateTime()

TextEntry::make('created_at')
    ->isoTime()

可通过向 isoDate()、isoDateTime() 或 isoTime() 方法传入自定义宏格式字符串来自定义日期格式。可使用任意 Carbon 宏格式：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->isoDate('L')

TextEntry::make('created_at')
    ->isoDateTime('LLL')

TextEntry::make('created_at')
    ->isoTime('LT')

TIP

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

相对日期格式化

可使用 since() 方法，用 Carbon 的 diffForHumans() 格式化条目状态：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->since()

此外，可使用 dateTooltip()、dateTimeTooltip()、timeTooltip()、isoDateTooltip()、isoDateTimeTooltip()、isoTime()、isoTimeTooltip() 或 sinceTooltip() 方法，在工具提示中显示格式化日期，通常用于提供额外信息：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->since()
    ->dateTooltip() // Accepts a custom PHP date formatting string

TextEntry::make('created_at')
    ->since()
    ->dateTimeTooltip() // Accepts a custom PHP date formatting string

TextEntry::make('created_at')
    ->since()
    ->timeTooltip() // Accepts a custom PHP date formatting string

TextEntry::make('created_at')
    ->since()
    ->isoDateTooltip() // Accepts a custom Carbon macro format string

TextEntry::make('created_at')
    ->since()
    ->isoDateTimeTooltip() // Accepts a custom Carbon macro format string

TextEntry::make('created_at')
    ->since()
    ->isoTimeTooltip() // Accepts a custom Carbon macro format string

TextEntry::make('created_at')
    ->dateTime()
    ->sinceTooltip()

设置日期格式化的时区

上面列出的每个日期格式化方法也接受 timezone 参数，可将状态中的时间转换到不同时区：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->dateTime(timezone: 'America/New_York')

也可向条目的 timezone() 方法传入时区，以便一次性应用到所有日期时间格式化方法：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('created_at')
    ->timezone('America/New_York')
    ->dateTime()

TIP

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

若未向条目传入 timezone()，将使用 Filament 的默认时区。可在 AppServiceProvider 等服务提供者的 boot() 方法中使用 FilamentTimezone::set() 设置 Filament 的默认时区：

php

use Filament\Support\Facades\FilamentTimezone;

public function boot(): void
{
    FilamentTimezone::set('America/New_York');
}

若要为应用中所有文本条目设置默认时区，这会很有用。Filament 中其他使用时区的地方也会用到它。

WARNING

Filament 的默认时区仅在条目存储时间时应用。若条目仅存储日期（使用 date() 而非 dateTime()），则不会应用时区。这是为了防止在存储无时间的日期时发生时区偏移。

数字格式化

除了向 formatStateUsing() 传入函数外，还可使用 numeric() 方法将条目格式化为数字：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('stock')
    ->numeric()

若要自定义格式化数字时使用的小数位数，可使用 decimalPlaces 参数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('stock')
    ->numeric(decimalPlaces: 0)

TIP

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

默认会使用应用的 locale 适当地格式化数字。若要自定义所用 locale，可将其传给 locale 参数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('stock')
    ->numeric(locale: 'nl')

TIP

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

货币格式化

除了向 formatStateUsing() 传入函数外，还可使用 money() 方法轻松以任意货币格式化金额：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('price')
    ->money('EUR')

TIP

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

money() 还有一个 divideBy 参数，可在格式化前将原始值除以某个数。例如，若数据库以分为单位存储价格，这会很有用：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('price')
    ->money('EUR', divideBy: 100)

TIP

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

默认会使用应用的 locale 适当地格式化货币。若要自定义所用 locale，可将其传给 locale 参数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('price')
    ->money('EUR', locale: 'nl')

TIP

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

若要自定义格式化数字时使用的小数位数，可使用 decimalPlaces 参数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('price')
    ->money('EUR', decimalPlaces: 3)

TIP

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

渲染 Markdown

若条目值是 Markdown，可使用 markdown() 渲染：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->markdown()

也可传入布尔值，以控制文本是否渲染为 Markdown：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->markdown(FeatureFlag::active())

TIP

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

渲染 HTML

若条目值是 HTML，可使用 html() 渲染：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->html()

也可传入布尔值，以控制文本是否渲染为 HTML：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->html(FeatureFlag::active())

TIP

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

DANGER

Filament 内置的 HTML 消毒器允许内联 style 属性，以支持字体颜色、文本高亮与图片尺寸等富文本格式功能。这意味着 background: url(...) 或 position: fixed 等 CSS 属性不会从已消毒 HTML 中剥离。若内容来自不受信任的用户，应考虑限制默认配置。如何自定义消毒器详见安全文档。

渲染未经消毒的原始 HTML

若使用此方法，HTML 会在渲染前消毒以移除任何潜在不安全内容。若希望退出此行为，可通过格式化将 HTML 包装在 HtmlString 对象中：

php

use Filament\Infolists\Components\TextEntry;
use Illuminate\Support\HtmlString;

TextEntry::make('description')
    ->formatStateUsing(fn (string $state): HtmlString => new HtmlString($state))

DANGER

渲染原始 HTML 时请谨慎，因其可能包含恶意内容，从而导致应用出现跨站脚本（XSS）等安全漏洞。使用此方法前务必确保要渲染的 HTML 是安全的。

或者，也可从 formatStateUsing() 方法返回 view() 对象，同样不会被消毒：

php

use Filament\Infolists\Components\TextEntry;
use Illuminate\Contracts\View\View;

TextEntry::make('description')
    ->formatStateUsing(fn (string $state): View => view(
        'filament.infolists.components.description-entry-content',
        ['state' => $state],
    ))

列出多个值

若文本条目的状态是数组，则可渲染多个值。这可能出现在 Eloquent 属性使用 array 转换、关联有多条结果，或向 state() 方法传入数组时。若文本条目内有多个值，它们会以逗号分隔。可使用 listWithLineBreaks() 方法改为换行显示：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->listWithLineBreaks()

也可传入布尔值，以控制各项之间是否换行：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->listWithLineBreaks(FeatureFlag::active())

TIP

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

为列表添加项目符号

可使用 bulleted() 方法为每个列表项添加项目符号：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->bulleted()

也可传入布尔值，以控制文本是否带项目符号：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->bulleted(FeatureFlag::active())

TIP

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

限制列表中的值数量

可使用 limitList() 方法限制列表中的值数量：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->listWithLineBreaks()
    ->limitList(3)

TIP

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

展开受限列表

可使用 expandableLimitedList() 方法允许受限项展开与折叠：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->listWithLineBreaks()
    ->limitList(3)
    ->expandableLimitedList()

INFO

此功能仅适用于 listWithLineBreaks() 或 bulleted()，即每项独占一行的情况。

也可传入布尔值，以控制文本是否可展开：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('authors.name')
    ->listWithLineBreaks()
    ->limitList(3)
    ->expandableLimitedList(FeatureFlag::active())

TIP

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

将单个值拆分为多个列表项

若希望将模型中的文本字符串「拆分」为多个列表项，可使用 separator() 方法。例如，这对将逗号分隔的标签显示为徽章很有用：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('tags')
    ->badge()
    ->separator(',')

TIP

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

聚合关联

Filament 提供若干用于聚合关联字段的方法，包括 avg()、max()、min() 与 sum()。例如，若要显示所有关联记录某字段的平均值，可使用 avg() 方法：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('users_avg_age')->avg('users', 'age')

本例中，users 是关联名，age 是被求平均的字段。条目名必须是 users_avg_age，因为这是 Laravel 用于存储结果的约定。

若希望在聚合前限定关联范围，可向方法传入数组，键为关联名，值为用于限定 Eloquent 查询的函数：

php

use Filament\Infolists\Components\TextEntry;
use Illuminate\Database\Eloquent\Builder;

TextEntry::make('users_avg_age')->avg([
    'users' => fn (Builder $query) => $query->where('is_active', true),
], 'age')

自定义文本大小

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

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

php

use Filament\Infolists\Components\TextEntry;
use Filament\Support\Enums\TextSize;

TextEntry::make('title')
    ->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\Infolists\Components\TextEntry;
use Filament\Support\Enums\FontWeight;

TextEntry::make('title')
    ->weight(FontWeight::Bold)

TIP

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

自定义字体系列

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

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

php

use Filament\Support\Enums\FontFamily;
use Filament\Infolists\Components\TextEntry;

TextEntry::make('apiKey')
    ->label('API key')
    ->fontFamily(FontFamily::Mono)

TIP

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

处理长文本

限制文本长度

可使用 limit() 限制条目值的长度：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->limit(50)

TIP

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

默认情况下，文本被截断时会在末尾追加省略号（...）。可通过向 end 参数传入自定义字符串来自定义：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->limit(50, end: ' (more)')

TIP

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

也可在函数中通过 getCharacterLimit() 方法获取传给 limit() 的值并复用：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->limit(50)
    ->tooltip(function (TextEntry $component): ?string {
        $state = $component->getState();

        if (strlen($state) <= $component->getCharacterLimit()) {
            return null;
        }

        // Only render the tooltip if the entry contents exceeds the length limit.
        return $state;
    })

限制词数

可使用 words() 限制条目中显示的词数：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->words(10)

TIP

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

默认情况下，文本被截断时会在末尾追加省略号（...）。可通过向 end 参数传入自定义字符串来自定义：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->words(10, end: ' (more)')

TIP

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

将文本限制为特定行数

你可能希望将文本限制为特定行数，而非固定长度。将文本限制为若干行在响应式界面中很有用，可确保各屏幕尺寸体验一致。可使用 lineClamp() 方法实现：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->lineClamp(2)

TIP

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

阻止文本换行

默认情况下，文本超出容器宽度时会换到下一行。可使用 wrap(false) 方法阻止此行为：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('description')
    ->wrap(false)

TIP

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

允许将文本复制到剪贴板

你可使文本可复制：点击条目会将文本复制到剪贴板，并可选择自定义确认消息及持续时间（毫秒）：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('apiKey')
    ->label('API key')
    ->copyable()
    ->copyMessage('Copied!')
    ->copyMessageDuration(1500)

也可传入布尔值，以控制文本是否可复制：

php

use Filament\Infolists\Components\TextEntry;

TextEntry::make('apiKey')
    ->label('API key')
    ->copyable(FeatureFlag::active())

TIP

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

WARNING

此功能仅在应用启用 SSL 时可用。

添加后缀与前缀操作

可使用 prefixAction() 与 suffixAction() 方法在条目前后放置操作：

php

use Filament\Actions\Action;
use Filament\Infolists\Components\TextEntry;
use Filament\Support\Icons\Heroicon;

TextEntry::make('cost')
    ->prefix('€')
    ->suffixAction(
        Action::make('copyCostToPrice')
            ->icon(Heroicon::Clipboard),
    )

文本条目 ​

简介 ​

自定义颜色 ​

添加图标 ​

显示为「徽章」 ​

格式化 ​

日期格式化 ​

使用 Carbon 宏格式进行日期格式化 ​

相对日期格式化 ​

在工具提示中显示格式化日期 ​

设置日期格式化的时区 ​

数字格式化 ​

货币格式化 ​

渲染 Markdown ​

渲染 HTML ​

渲染未经消毒的原始 HTML ​

列出多个值 ​

为列表添加项目符号 ​

限制列表中的值数量 ​

展开受限列表 ​

将单个值拆分为多个列表项 ​

聚合关联 ​

自定义文本大小 ​

自定义字重 ​

自定义字体系列 ​

处理长文本 ​

限制文本长度 ​

限制词数 ​

将文本限制为特定行数 ​

阻止文本换行 ​

允许将文本复制到剪贴板 ​

添加后缀与前缀操作 ​