README

表格服务提供了一种轻松构建表格的方法。

目录

• 入门
  • 要求
  • 亮点
  • 屏幕截图
  • 简单示例
• 文档
  • 创建表格
  • 创建行
  • 创建行
  • 行方法
  • 自定义行
  • 表格属性
  • 渲染表格
    • 默认渲染器
    • 表格渲染器
    • 自定义渲染器
• 致谢

入门

使用以下命令添加运行此项目的表格服务项目的最新版本。

composer require tobento/service-table

要求

• PHP 8.0 或更高版本

亮点

• 框架无关，适用于任何项目
• 解耦设计
• 自定义渲染

屏幕截图

简单示例

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'sku' => 'Sku',
    'title' => 'Title',
    'description' => 'Description',
    'price' => 'Price',
])->heading();

$table->row([
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => 'A nice shirt in blue color.',
    'price' => 19.99,
]);

渲染表格

<?= $table->render() ?>

// or just
<?= $table ?>

上面的两个表格都将生成以下输出

<div class="table">
    <div class="table-row th">
        <div class="table-col grow-1">Sku</div>
        <div class="table-col grow-1">Title</div>
        <div class="table-col grow-2">Description</div>
        <div class="table-col grow-1">Price</div>
    </div>
    <div class="table-row">
        <div class="table-col grow-1">shirt</div>
        <div class="table-col grow-1">Shirt</div>
        <div class="table-col grow-2">A nice shirt in blue color.</div>
        <div class="table-col grow-1">19.99</div>
    </div>
</div>

文档

创建表格

use Tobento\Service\Table\Table;
use Tobento\Service\Table\TableInterface;
use Tobento\Service\Table\Renderer;

$table = new Table(
    name: 'products',
    columns: ['title', 'description'], // The columns to render only.
    renderer: new Renderer(),
);

var_dump($table instanceof TableInterface);
// bool(true)

// Get the name of the table:
var_dump($table->name());
// string(8) "products"

带有方法

您可以通过以下“方法”更改一些数据或实现，它将返回一个新的实例。

withColumns

use Tobento\Service\Table\Table;

$table = new Table('products');

$newTable = $table->withColumns(['sku', 'title']);

var_dump($table === $newTable);
// bool(false)

withRenderer

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Renderer;

$table = new Table('products');

$newTable = $table->withRenderer(new Renderer());

var_dump($table === $newTable);
// bool(false)

创建行

从数组项创建行

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->rows([
    [
        'sku' => 'shirt',
        'title' => 'Shirt',
        'description' => 'A nice shirt in blue color.',
        'price' => 19.99,
    ],
    [
        'sku' => 'cap',
        'title' => 'Cap',
        'description' => 'A nice cap.',
        'price' => 11.99,
    ],    
]);

使用回调创建行

如果您提供了一个对象数组或只想创建特定的行列，则可以使用回调创建行。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Row;

class Product
{
    public function __construct(
        protected string $title,
        protected float $price,
    ) {}

    public function title(): string
    {
        return $this->title;
    }
    
    public function price(): float
    {
        return $this->price;
    }         
}

$table = new Table('products');

$table->rows([
    new Product('Shirt', 19.99),
    new Product('Cap', 11.99),  
], function(Row $row, Product $product): void {
    $row->column(key: 'title', text: $product->title());
    $row->column(key: 'price', text: $product->price(), attributes: ['data-foo' => 'value']);
});

仅从数组项创建特定的行列

$table = new Table('products');

$table->rows([
    [
        'sku' => 'shirt',
        'title' => 'Shirt',
        'description' => 'A nice shirt in blue color.',
        'price' => 19.99,
    ],
    [
        'sku' => 'cap',
        'title' => 'Cap',
        'description' => 'A nice cap.',
        'price' => 11.99,
    ],
], function(Row $row, array $item): void {
    $row->column(key: 'title', text: $item['title']);
    $row->column(key: 'price', text: $item['price'], attributes: ['data-foo' => 'value']);
});

创建行

从数组创建行

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => 'A nice shirt in blue color.',
    'price' => 19.99,
]);

使用回调创建行列

如果您提供了一个对象，则可以使用回调创建行列。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Row;

class Product
{
    public function __construct(
        protected string $title,
        protected float $price,
    ) {}

    public function title(): string
    {
        return $this->title;
    }
    
    public function price(): float
    {
        return $this->price;
    }         
}

$table = new Table('products');

$table->row(
    new Product('Shirt', 19.99),
    function(Row $row, Product $product): void {
        $row->column(key: 'title', text: $product->title())
            ->column(key: 'price', text: $product->price(), attributes: ['data-foo' => 'value']);
    }
);

行方法

标题

您可以标记行作为标题。

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'title' => 'Title',
    'description' => 'Description',
])->heading();

Id

您可以给行一个 id 以便稍后获取它。

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'title' => 'Title',
    'description' => 'Description',
])->id('header');

$headerRow = $table->getRow('header');

每个

您可以使用 each 方法创建行列。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Row;

$item = [
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => 'A nice shirt in blue color.',
    'price' => 19.99,
];

$table = new Table('products');

$table->row()
      ->each($item, function(Row $row, $value, $key): void {
            $row->column(key: $key, value: $value);
      });

当

当方法将在第一个参数评估为 true 时执行给定的回调。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Row;

$table = new Table('products');

$table->row()
      ->when(true, function(Row $row): void {
          $row->column('actions', 'Actions');
      });

Html

您可以将列标记为 Html，表示不进行转义。

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => '<p>A nice shirt in blue color.</p>',
    'price' => 19.99,
])->html('description');

PrependHtml / AppendHtml

您可以在行之前和之后添加 Html。

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row([
    'sku' => '<input type="text" id="sku" name="sku">',
    'title' => '<input type="text" id="title" name="title">',
])->html('sku')
  ->html('title')
  ->prependHtml('<form>')
  ->appendHtml('</form>');

列

您可以使用列方法添加列。

use Tobento\Service\Table\Table;

$table = new Table('products');

$table->row()
      ->column(key: 'sku', text: 'Sku')
      ->column(key: 'title', text: 'Title', attributes: ['data-foo' => 'Foo']);

自定义行

您可以使用 addRow 方法传递自定义行。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\RowInterface;

$table = new Table('products');

// must implement RowInterface
$customRow = new CustomRow();

$table->addRow($customRow);

表格属性

您可以为表格设置属性，这些属性将根据渲染器进行渲染。

use Tobento\Service\Table\Table;

$table = new Table('products');
$table->attributes(['data-foo' => 'value']);

$attributes = $table->getAttributes();
// ['data-foo' => 'value']

渲染表格

根据您的需求，有不同的渲染表格的方式。

默认渲染器

默认渲染器使用 <div> 元素生成表格并自动计算列大小。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\Renderer;

$table = new Table(
    name: 'products',
    renderer: new Renderer(),
);

$table->attributes(['data-id' => 'value']);

$table->row([
    'sku' => 'Sku',
    'title' => 'Title',
    'description' => 'Description',
    'price' => 'Price',
])->heading();

$table->row([
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => 'A nice shirt in blue color.',
    'price' => 19.99,
])->attributes(['data-row' => 'name']);

echo $table;

输出

<div class="table" data-id="value">
    <div class="table-row th">
        <div class="table-col grow-1">Sku</div>
        <div class="table-col grow-1">Title</div>
        <div class="table-col grow-2">Description</div>
        <div class="table-col grow-1">Price</div>
    </div>
    <div class="table-row" data-row="name">
        <div class="table-col grow-1">shirt</div>
        <div class="table-col grow-1">Shirt</div>
        <div class="table-col grow-2">A nice shirt in blue color.</div>
        <div class="table-col grow-1">19.99</div>
    </div>
</div>

表格渲染器

表格渲染器使用 <table> HTML 元素生成表格。

use Tobento\Service\Table\Table;
use Tobento\Service\Table\TableRenderer;

$table = new Table(
    name: 'products',
    renderer: new TableRenderer(),
);

$table->attributes(['data-id' => 'value']);

$table->row([
    'sku' => 'Sku',
    'title' => 'Title',
    'description' => 'Description',
    'price' => 'Price',
])->heading();

$table->row([
    'sku' => 'shirt',
    'title' => 'Shirt',
    'description' => 'A nice shirt in blue color.',
    'price' => 19.99,
])->attributes(['data-row' => 'name']);

echo $table;

输出

<table data-id="value">
    <tr>
        <th>Sku</th>
        <th>Title</th>
        <th>Description</th>
        <th>Price</th>
    </tr>
    <tr data-row="name">
        <td>shirt</td>
        <td>Shirt</td>
        <td>A nice shirt in blue color.</td>
        <td>19.99</td>
    </tr>
</table>

$table->row()->prependHtml() 和 $table->row()->appendHtml 方法将被忽略，因为它会产生无效的 HTML！

自定义渲染器

您可能需要编写自己的适合应用程序的渲染器。

use Tobento\Service\Table\RendererInterface;
use Tobento\Service\Table\TableInterface;

class CustomRenderer implements RendererInterface
{
    /**
     * Render the table.
     *
     * @param TableInterface $table
     * @return string
     */
    public function render(TableInterface $table): string
    {
        // create the your custom table ...
        
        return 'table';
    }
}

致谢

• Tobias Strub
• 所有贡献者