介绍

在进行项目开发时，您经常需要展示各种数据类型，如货币、数字或日期。Orchid 提供的内置组件可以简化这一任务，类似于 Microsoft Excel 或 Apple Numbers 等流行的电子表格软件。

Orchid 的组件帮助您避免代码重复，并能轻松格式化和显示数据。这些组件可以用于 表格单元格（使用 TD 类）和 图例（使用 Sight 类）。在本篇文档中，我们将主要介绍 TD 组件的使用。

DateTimeSplit

DateTimeSplit 组件专为以两行格式显示日期而设计。上行显示格式化的日期，下行提供附加信息，如星期几和时间。

要使用 DateTimeSplit 组件，您可以指定包含日期信息的属性，并将其包含在表格单元格定义中：

TD::make('created_at')
    ->usingComponent(DateTimeSplit::class),

默认情况下，Orchid 为单元格的上部和下部提供合理的格式选项。不过，您也可以自定义这些选项以满足特定需求。例如，您可以更改日期格式或调整时区：

use Orchid\Screen\Components\Cells\DateTimeSplit;

TD::make('created_at')
    ->usingComponent(DateTimeSplit::class, upperFormat: 'Y-m-d', lowerFormat: 'H:i:s.uP', timeZone: 'Europe/Madrid'),

在上面的例子中，我们将 upperFormat 选项设置为 'Y-m-d'，以 'YYYY-MM-DD’ 格式显示日期。lowerFormat 选项设置为 'H:i:s.uP'，以 'HH:MM:SS.microseconds+timezone’ 格式显示时间。请随意调整这些格式和 timeZone 选项以适应您的项目需求。

注意： 本文档假设您熟悉 PHP 的 命名参数 功能。

Number

Number 组件简化了数字数据的格式化和显示。它允许您以所需格式展示数字，例如通过千位分隔符提高可读性。

要使用 Number 组件，请在表格单元格定义中指定包含数值的属性：

use Orchid\Screen\Components\Cells\Number;

TD::make('value')
    ->usingComponent(Number::class),

当组件遇到大数字时，会自动添加千位分隔符以增强可读性。例如，值 100400500.75 将被渲染为 100 400 500,8。

除了默认行为，您还可以通过指定选项来自定义 Number 组件，如小数位数、十进制分隔符和千位分隔符：

TD::make('value')
    ->usingComponent(Number::class, decimals: 1, decimal_separator: ',', thousands_separator: ' '),

Boolean

Boolean 组件旨在以简洁且视觉清晰的方式表示布尔值。它允许您使用适当的标签显示布尔数据。

以下是使用 Boolean 组件的示例：

use Orchid\Screen\Components\Cells\Boolean;

TD::make('value')
    ->usingComponent(Boolean::class),

默认情况下，Boolean 组件将布尔值显示为 “true” 或 “false”。不过，您可以轻松自定义标签以匹配数据的语义：

TD::make('value')
    ->usingComponent(Boolean::class, true: '启用', false: '禁用'),

Percentage

Percentage 组件简化了以百分比形式展示值的过程。它自动格式化值并添加百分号以提供清晰的视觉表示。

要使用 Percentage 组件，请在表格单元格定义中指定包含数值的属性：

use Orchid\Screen\Components\Cells\Percentage;

TD::make('value')
    ->usingComponent(Percentage::class),

Percentage 组件提供了数值作为百分比的清晰简洁表示。您还可以通过指定要显示的小数位数来自定义组件：

TD::make('value')
    ->usingComponent(Percentage::class, decimals: 2),

Currency

Currency 组件简化了货币值的格式化和显示。它确保格式一致并提供自定义选项。

要使用 Currency 组件，请指定字段并使用 usingComponent 方法：

use Orchid\Screen\Components\Cells\Currency;

TD::make('value')
    ->usingComponent(Currency::class),

Currency 组件自动使用适当的货币符号和小数分隔符格式化货币值。不过，您也可以通过指定附加选项自定义格式。例如：

TD::make('value')
    ->usingComponent(Currency::class, decimals: 1, decimal_separator: ',', thousands_separator: ' '),

如果需要使用自定义货币符号，可以使用 before 和 after 选项指定。例如：

TD::make('value')
    ->usingComponent(Currency::class, before: '$', after: '₽'),

在这种情况下，货币值将以美元符号显示在值之前，并在值之后显示卢布符号。调整这些选项以匹配项目中使用的货币符号。