README

Cellbrush表格生成器

使用PHP生成HTML表格的库。

表格结构

• 命名行和列，以便可以使用字符串键进行定位。
• 使用列组和行组实现colspan和rowspan。
• 自动填充空单元格，以保持结构的完整性。
• 自动警告单元格冲突。

标签属性

• 轻松添加行类。
• 轻松添加行条纹类（奇数/偶数斑马条纹等）。
• 轻松添加应用于列中所有单元格的列类。
• (更多计划中)

API设计

• 使用方法链而非庞大的数组。
• 为常用功能提供快捷符号。
• 返回值和参数类型有良好的文档记录，以便您的IDE可以告知您可能的操作。
• 抛出异常以违反完整性。
• Composer和PSR-4。

基本用法

一个简单的3x3表格，对角线单元格已填充。

$table = \Donquixote\Cellbrush\Table\Table::create()
  ->addRowNames(['row0', 'row1', 'row2'])
  ->addColNames(['col0', 'col1', 'col2'])
  ->td('row0', 'col0', 'Diag 0')
  ->td('row1', 'col1', 'Diag 1')
  ->td('row2', 'col2', 'Diag 2')
;
$html = $table->render();

太啰嗦了吗？请看下面的“快捷语法”。

thead和tfoot中的单元格

如上所示的表格，但添加了thead部分。

列名在表格部分之间共享，但每个部分需要定义新的行。

$table = ...
$table->thead()
  ->addRowName('head row')
  ->th('head row', 'col0', 'H0')
  ->th('head row', 'col1', 'H1')
  ->th('head row', 'col2', 'H2')
;
$html = $table->render();

额外的tbody部分

默认情况下，每个addRowName()和td()或th()都会进入主tbody部分。

所以，以下两个是等效的

$table->td('row0', 'col0', 'Cell contents');
$table->tbody()->td('row0', 'col0', 'Cell contents');

可以通过这种方式添加更多命名的tbody部分

$table->tbody('tb1')
  ->addRowName(..)
  ->td(..)

再次强调，列定义在表格部分之间共享，但需要单独添加行定义。

完整的rowspan和colspan

要使单元格跨越整个表格宽度，只需将列名设置为''。同样，将行名设置为''以跨越表格部分的整个高度。

$table->thead()
  ->addRowName('head row')
  ->td('head row', '', 'Horizontal cell in thead.')
;
$table
  ->...
  ->td('', 'col1', 'Vertical cell')
;

列组

命名列组允许具有colspan的单元格。在下面的示例中，列名"products"指定了一个跨越所有3个products.*单元格的colspan单元格，而"products.a"、"products.b"和"products.c"指定了不带colspan的特定单元格。

$table->addColNames(['legend', 'products.a', 'products.b', 'products.c']);
$table->thead()
  ->addRowName('head')
  ->th('head', 'legend', 'Legend')
  // The "Products" label will span 3 columns: products.a, products.b, products.c
  ->th('head', 'products', 'Products')
  ->addRowName('name')
  ->th('name', 'legend', 'Product name')
  ->th('name', 'products.a', 'Product A')
  ->th('name', 'products.b', 'Product B')
  ->th('name', 'products.c', 'Product C')
;
$table
  ->addRowName('width')
  ->th('width', 'legend', 'Width')
  ->td('width', 'products.a', '55 cm')
  ->td('width', 'products.b', '102 cm')
  ..
  ->addRowName('height')
  ..
  ->addRowName('price')
  ->td('price', 'products.a', '7.66 EUR')

行组

类似于列组。

$table = Table::create()
  ->addColNames(['legend', 'sublegend', 0, 1])
  ->addRowNames(['dimensions.width', 'dimensions.height', 'price'])
  ->th('dimensions', 'legend', 'Dimensions')
  ->th('dimensions.width', 'sublegend', 'Width')
  ->th('dimensions.height', 'sublegend', 'Height')
  ->th('price', 'legend', 'Price')
;
$table->headRow()->thMultiple(['Product 0', 'Product 1']);
$table->rowHandle('dimensions.width')->tdMultiple(['2cm', '5cm']);
$table->rowHandle('dimensions.height')->tdMultiple(['14g', '22g']);
$table->rowHandle('price')->tdMultiple(['7,- EUR', '5,22 EUR']);

行组和列组的组合

$table = (new Table())
  // Add columns.
  ->addColName('name')
  ->addColNames(['info.color', 'info.price'])
  // Add banana row group.
  ->addRowNames(['banana.description', 'banana.info'])
  ->th('banana', 'name', 'Banana')
  ->td('banana.description', 'info', 'A yellow fruit.')
  ->td('banana.info', 'info.color', 'yellow')
  ->td('banana.info', 'info.price', '60 cent')
;
// Alternative syntax with handles, see "Shortcut syntax" below.
$table->addRow('coconut')->th('name', 'Coconut');
$table->addRow('coconut.description')->td('info', 'Has liquid inside.');
$table->addRow('coconut.info')
  ->td('info.color', 'brown')
  ->td('info.price', '3 dollar')
;
$table->headRow()
  ->th('name', 'Name')
  ->th('info.color', 'Color')
  ->th('info.price', 'Price')
;

嵌套组

组可以有无限深度。

$table = Table::create()
  ->addRowNames(['T', 'B.T', 'B.B.T', 'B.B.B'])
  ->addColNames(['L', 'R.L', 'R.R.L', 'R.R.R'])
  ->td('T', '', 'top')
  ->td('B', 'L', 'bottom left')
  ->td('B.T', 'R', 'B.T / R')
  ->td('B.B', 'R.L', 'B.B / R.L')
  ->td('B.B.T', 'R.R', 'B.B.T / R.R')
  ->td('B.B.B', 'R.R.L', 'B.B.B / R.R.L')
  ->td('B.B.B', 'R.R.R', 'B.B.B / R.R.R')
;

开放单元格

开放端单元格允许重叠的colspan单元格，就像墙上的砖块。

$table = (new Table())->addColNames([0, 1, 2, 3, 4, 5, 6, 7]);
$table->addRow(0)->tdMultiple([0, 1, 2, 3, 4, 5, 6, 7]);
$table->addRow(1)
  ->tdOpenEnd(0, '0..2')
  ->tdOpenEnd(3, '3..4')
  ->tdOpenEnd(5, '5')
  ->tdOpenEnd(6, '6..7')
;
$table->addRow(2)
  ->tdOpenEnd(0, '0..1')
  ->tdOpenEnd(2, '2..3')
  ->tdOpenEnd(4, '4..6')
  ->tdOpenEnd(7, '7')
;

使用行句柄和列句柄的快捷语法

RowHandle和*ColHandle允许您省略$rowName和$colName中的一个来定位表格单元格。

$table = (new Table())
  ->addRowNames(['row0', 'row1', 'row2'])
  ->addColNames(['legend', 'col0', 'col1', 'col2'])
  ...
;
// Add cells in a "head0" row in the thead section.
$table->headRow()
  ->th('col0', 'Column 0')
  ->th('col1', 'Column 1')
  ->th('col2', 'Column 2')
;
// Add cells in a "legend" column.
$table->colHandle('legend')
  ->th('row0', 'Row 0')
  ->th('row1', 'Row 1')
  ->th('row2', 'Row 2')
;

行类

可以使用addRowClass()轻松添加行类。

$table->addRowClass('row0', 'rowClass0');

行条纹

可以使用addRowStriping()将行条纹类添加到表格部分。

默认条纹是['odd', 'even']，但可以使用三个或更多条纹添加不同的模式。

// Odd/even zebra striping.
$table->addRowStriping();
// 3-way striping.
$table->addRowStriping(['1of3', '2of3', '3of3']);

条纹始终应用于表格部分。默认情况下，这将是最主要的tbody部分。

列类

您可以使用addColClass()将类添加到列中的所有单元格。这可以一次对所有表格部分执行，也可以对特定的表格部分执行。

$table->addColClass('col0', 'allSectionsColumn0');
$table->tbody()->addColClass('col0', 'tbodyColumn0');

单元格类

使用addCellClass()将类添加到单个单元格。

$table->addCellClass('row0', 'col0', 'my_class');

列排序

即使在添加了单元格之后，也可以对列进行排序。

// Create a table, and render it.
$table = Table::create()
  ->addRowNames(['row0', 'row1', 'row2'])
  ->addColNames(['col0', 'col1', 'col2'])
  ->td('row0', 'col0', 'Diag 0')
  ->td('row1', 'col1', 'Diag 1')
  ->td('row2', 'col2', 'Diag 2')
;
print $table->render();

// Reorder the columns, and render again.
$table->setColOrder(['col1', 'col2', 'col0']);
print $table->render();

还需要更多示例吗？

您可以在单元测试中看到更多示例。

计划中的功能

下一步

• 碰撞检测。
• 专用异常类。