文本列

简介

文本列显示简单文本：

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')

自定义颜色

你可以为文本设置颜色：

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

添加图标

文本列也可以有图标：

php

use Filament\Tables\Columns\TextColumn;
use Filament\Support\Icons\Heroicon;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;
use Filament\Support\Enums\IconPosition;
use Filament\Support\Icons\Heroicon;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;
use Filament\Support\Icons\Heroicon;

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

TIP

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

显示为「徽章」

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

格式化

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

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

php

use Filament\Tables\Columns\TextColumn;

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

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

TIP

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

日期格式化

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

TIP

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

相对日期格式化

你可以使用 since() 方法，用 Carbon 的 diffForHumans() 格式化列的状态：

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

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

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

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

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

设置日期格式化的时区

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

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::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\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

货币格式化

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

渲染 Markdown

若列的值是 Markdown，你可以使用 markdown() 渲染：

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

渲染 HTML

若列的值是 HTML，你可以使用 html() 渲染：

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

DANGER

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

渲染未经消毒的原始 HTML

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

php

use Filament\Tables\Columns\TextColumn;
use Illuminate\Support\HtmlString;

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

DANGER

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

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

php

use Filament\Tables\Columns\TextColumn;
use Illuminate\Contracts\View\View;

TextColumn::make('description')
    ->formatStateUsing(fn (string $state): View => view(
        'filament.tables.columns.description-column-content',
        ['state' => $state],
    ))

显示描述

描述可用于在列内容上方或下方轻松渲染额外文本。

你可以使用 description() 方法在文本列内容下方显示描述：

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->description(fn (Post $record): string => $record->description)

TIP

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

默认情况下，描述显示在主文本下方，但你可以使用 'above' 作为第二个参数将其移到上方：

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('title')
    ->description(fn (Post $record): string => $record->description, position: 'above')

列出多个值

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

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

为列表添加项目符号

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

php

use Filament\Tables\Columns\TextColumn;

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

限制列表中的值数量

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

展开受限列表

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

php

use Filament\Tables\Columns\TextColumn;

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

INFO

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

自定义文本大小

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

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

php

use Filament\Tables\Columns\TextColumn;
use Filament\Support\Enums\TextSize;

TextColumn::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\Tables\Columns\TextColumn;
use Filament\Support\Enums\FontWeight;

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

TIP

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

自定义字体系列

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

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

php

use Filament\Support\Enums\FontFamily;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->fontFamily(FontFamily::Mono)

TIP

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

处理长文本

限制文本长度

你可以使用 limit() 限制列值的长度：

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

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

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

限制词数

你可以使用 words() 限制列中显示的词数：

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

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

php

use Filament\Tables\Columns\TextColumn;

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

TIP

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

允许文本换行

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('description')
    ->wrap()

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('description')
    ->wrap(FeatureFlag::active())

TIP

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

将文本限制为特定行数

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('description')
    ->wrap()
    ->lineClamp(2)

TIP

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

允许将文本复制到剪贴板

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->copyable()
    ->copyMessage('Email address copied')
    ->copyMessageDuration(1500)

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

php

use Filament\Tables\Columns\TextColumn;

TextColumn::make('email')
    ->copyable(FeatureFlag::active())

TIP

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

WARNING

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

文本列 ​

简介 ​

自定义颜色 ​

添加图标 ​

显示为「徽章」 ​

格式化 ​

日期格式化 ​

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

相对日期格式化 ​

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

设置日期格式化的时区 ​

数字格式化 ​

货币格式化 ​

渲染 Markdown ​

渲染 HTML ​

渲染未经消毒的原始 HTML ​

显示描述 ​

列出多个值 ​

为列表添加项目符号 ​

限制列表中的值数量 ​

展开受限列表 ​

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

自定义文本大小 ​

自定义字重 ​

自定义字体系列 ​

处理长文本 ​

限制文本长度 ​

限制词数 ​

允许文本换行 ​

将文本限制为特定行数 ​

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

文本列

简介