eznio/tabler

CLI ASCII 表格绘制器

维护者

详细信息

github.com/eznio/tabler

主页

源代码

问题

安装: 283

依赖项: 2

建议者: 0

安全: 0

星星: 0

关注者: 2

分支: 1

公开问题: 0

1.0.3 2017-06-07 04:02 UTC

Requires

Requires (Dev)

MIT e38930667ee0769e0c15b5781ad53d37d9d55639

cliconsoleasciitable

This package is not auto-updated.

Last update: 2024-09-14 19:36:48 UTC

README

概述

简单的（最初）辅助工具，可格式化和渲染 CLI 工具的 ASCII 表格。

基本用法

$tabler = (new \eznio\tabler\Tabler())
    ->setHeaders(['a' => 'Column A', 'b' => 'Column B', 'c' => 'Column C'])
    ->setData([
        ['a' => '123', 'b' => '456', 'c' => '7'],
        ['a' => '123', 'b' => '456', 'c' => '7'],
        ['a' => '123', 'b' => '456', 'c' => '7']
    ])
    ->setRenderer(new \eznio\tabler\renderers\MysqlStyleRenderer());

它会产生

+----------+----------+----------+
| Column A | Column B | Column C |
+----------+----------+----------+
| 123      | 456      | 7        |
| 123      | 456      | 7        |
| 123      | 456      | 7        |
+----------+----------+----------+

基本类和接口

类

  • Tabler - 整个包的门面类。包含设置表格数据、生成、样式化和渲染的快捷调用
  • Composer - 扫描标题和数据数组，收集最大长度，组合列结构并尝试获取缺失的列名
  • LayoutBuilder - 获取已解析的表格数据的 Composer 并生成 TableLayout 结构（-s）（见下文）
  • Styler - 设置文本行样式（背景颜色、前景颜色、一些文本样式）的辅助工具
  • Element - TableLayout 结构的基本类

接口

  • Renderer - 实现渲染类的接口

表格元素

什么是以及为什么

TableLayout 是一个元结构，代表整个表格及其元素 - 行和单元格。

主要用于样式化。例如，如果我们想以红色显示第 2 列

$layout = $tabler->getTableLayout();
$layout->getHeaderLine()->getHeaderCell('column2')
    ->setForegroundColor(\eznio\tabler\references\ForegroundColors::RED);

模式

整体元素布局和嵌套

+-----------------------------------------+
| TableLayout                             |
|                                         |
| +-------------------------------------+ |
| | HeaderLine                          | |
| |                                     | |
| | +------------+ +------------+       | |
| | | HeaderCell | | HeaderCell | . . . | |
| | +------------+ +------------+       | |
| +-------------------------------------+ |
|                                         |
| +-------------------------------------+ |
| | DataGrid                            | |
| |                                     | |
| | +---------------------------------+ | |
| | | DataRow                         | | |
| | |                                 | | |
| | | +----------+ +----------+       | | |
| | | | DataCell | | DataCell | . . . | | |
| | | +----------+ +----------+       | | |
| | +---------------------------------+ | |
| |                                     | |    
| | +---------------------------------+ | |
| | | DataRow                         | | |
| | |                                 | | |
| | | +----------+ +----------+       | | |
| | | | DataCell | | DataCell | . . . | | |
| | | +----------+ +----------+       | | |
| | +---------------------------------+ | |
| |                                     | |
| |  . . .                              | |
| +-------------------------------------+ |
+-----------------------------------------+

简短元素参考

  • TableLayout - 整个表格。边框颜色在这里设置
  • HeaderLine - 包含列标题的第一行
  • HeaderCell - 单个标题行的单元格。
  • DataGrid - 整个数据部分
  • DataRow - 单个数据行
  • DataCell - 单个数据单元格

获取/设置子元素

  1. 获取 TableLayout
/** @var Tabler $tabler */
$tableLayout = $tabler->getTableLayout();
  1. 获取顶部元素
/** @var HeaderLine $headerLine */
$headerLine = $tableLayout->getheaderLine();

/** @var DataGrid $dataGrid */
$dataGrid = $tableLayout->getDataGrid();
  1. 获取标题行单元格
/** @var HeaderCell $headerCellA */
$headerCellA = $headerLine->getHeaderCell('a');
  1. 获取数据行和单元格
/** @var DataRow $firstDataRow */
$firstDataRow = $dataGrid->getRow(0);

/** @var DataCell $dataCellA */
$dataCellA = $firstDataRow->getCell('a');

门面公共 API 参考

$tabler = new \eznio\tabler\Tabler();

主要部分

  • setData(array $data)

    设置表格数据 2 级嵌套数组

    • 顶层数组元素被视为行，也应该是数组
    • 行元素被视为单元格。它们的数组键是列 ID

  • setHeaders(array $headers)

    设置表格标题数组。其元素被视为列标题，其数组键是列 ID。

  • getTableLayout()

    返回 TableLayout 结构。如果没有构建，则在返回之前构建。

  • setRenderer(Renderer $renderer)

    设置渲染类以渲染表格

  • setGuessHeaderNames(bool $guessHeaderNames)

    将 $guessHeaderNames 设置为 true 表示如果未提供标题，则使用列 ID 作为标题标题

    如果 $guessHeaderNames 设置为 false，则没有提供标题的列名将渲染为空字符串

  • render(TableLayout $tableLayout = null)

    渲染当前（如果没有传递 TableLayout），或给定 TableLayout 组件为表格字符串表示形式并返回它

样式快捷方式

如果需要，描述在源代码中可用

  • setBorderBackgroundColor($color)
  • getBorderBackgroundColor()
  • setBorderForegroundColor($color)
  • getBorderForegroundColor()
  • setHeadingLineStyles(array $styles)
  • getHeadingLineStyles()
  • setHeadingCellStyles($columnId, array $styles)
  • getHeadingCellStyles($columnId)
  • setColumnStyles($columnId, array $styles)
  • setColumnTextAlignment($columnId, $alignment)
  • setColumnMinLength($columnId, $minLength)
  • setColumnLeftPadding($columnId, $leftPadding)
  • getColumnLeftPadding($columnId)
  • setColumnRightPadding($columnId, $rightPadding)
  • getColumnRightPadding($columnId)
  • setColumnPadding($columnId, $padding)
  • setRowStyles($rowId, array $styles)
  • setOddRowsStyles(array $styles)
  • setEvenRowsStyles(array $styles)
  • getRowStyles($rowId)
  • setCellStyles($columnId, $rowId, array $styles)
  • getCellStyles($columnId, $rowId)
  • setCellTextAlignment($columnId, $rowId, $alignment)
  • getCellTextAlignment($columnId, $rowId)

样式化

样式数组

样式可以设置为一个值

$cell->setStyle(ForegroundColors::RED);

或数组

$cell->setStyle([
    ForegroundColors::RED,
    BacgroundColors::WHITE,
    TextStyles::BOLD
]);

如果从背景或前景颜色设置了多个数组元素，则使用最后一个。文本样式可以自由组合使用。

样式引用类

  • references\ForegroundColors
  • references\BackgroundColors
  • references\TextStyles

样式元素

  • TableLayout - 设置边框背景和前景颜色
  • HeaderLine - 设置整个表头的背景/前景/文本样式，可以在 HeaderCell 级别进行覆盖
  • HeaderCell - 设置单个表头单元格的背景/前景/文本样式、最小长度、文本对齐和内边距，覆盖 HeaderLine 级别的设置
  • DataRow - 设置单个数据行的背景/前景/文本样式和文本对齐，可以在 DataCell 中进行覆盖
  • DataCell - 设置单个数据单元格的背景/前景/文本样式、最小长度、文本对齐和内边距，覆盖 DataRow 级别的设置

渲染器

表格数据

本部分示例中将使用以下表格设置

$tabler = (new \eznio\tabler\Tabler())
    ->setHeaders(['a' => 'Column A', 'b' => 'Column B', 'c' => 'Column C'])
    ->setData([
        ['a' => '123', 'b' => '456', 'c' => '7'],
        ['a' => '234', 'b' => '567', 'c' => '8'],
        ['a' => '345', 'b' => '6789', 'c' => '']
    ]);

MySQL风格渲染器

$tabler->setRenderer(new MysqlStyleRenderer());
+----------+----------+----------+
| Column A | Column B | Column C |
+----------+----------+----------+
| 123      | 456      | 7        |
| 234      | 567      | 8        |
| 345      | 6789     |          |
+----------+----------+----------+

MC风格渲染器

$tabler->setRenderer(new McStyleRenderer());
╔══════════╦══════════╦══════════╗
║ Column A ║ Column B ║ Column C ║
╠══════════╬══════════╬══════════╣
║ 123      ║ 456      ║ 7        ║
║ 234      ║ 567      ║ 8        ║
║ 345      ║ 6789     ║          ║
╚══════════╩══════════╩══════════╝

"清除"样式渲染器

$tabler->setRenderer(new ClearStyleRenderer());
 Column A  Column B  Column C 
    
 123       456       7        
 234       567       8        
 345       6789

"单行"样式渲染器

$tabler->setRenderer(new SingleLineRenderer());
┌──────────┬──────────┬──────────┐
│ Column A │ Column B │ Column C │
├──────────┼──────────┼──────────┤
│ 123      │ 456      │ 7        │
│ 234      │ 567      │ 8        │
│ 345      │ 6789     │          │
└──────────┴──────────┴──────────┘

更激进的示例

$tabler = (new \eznio\tabler\Tabler())
    ->setHeaders(['a' => 'Column A', 'b' => 'Column B', 'c' => 'Column C'])
    ->setData([
        ['a' => '123', 'b' => '456', 'c' => '7'],
        ['a' => '234', 'b' => '567', 'c' => '8'],
        ['a' => '345', 'b' => '6789', 'c' => '']
    ])
    ->setRenderer(new \eznio\tabler\renderers\SingleLineRenderer())
    ->setGuessHeaderNames(false);

$layout = $tabler->getTableLayout();

$layout->getHeaderLine()->getHeaderCell('a')
    ->setTextAlignment(\eznio\tabler\references\TextAlignments::TEXT_ALIGN_LEFT)
    ->setForegroundColor(\eznio\styler\references\ForegroundColors::RED);

$layout->getHeaderLine()->getHeaderCell('b')
    ->setTextAlignment(\eznio\tabler\references\TextAlignments::TEXT_ALIGN_CENTER)
    ->setForegroundColor(\eznio\styler\references\ForegroundColors::YELLOW);

$layout->getHeaderLine()->getHeaderCell('c')
    ->setTextAlignment(\eznio\tabler\references\TextAlignments::TEXT_ALIGN_RIGHT)
    ->setForegroundColor(\eznio\styler\references\ForegroundColors::GREEN);

$layout->getDataGrid()->getRow(1)->getCell('c')
    ->setTextAlignment(\eznio\tabler\references\TextAlignments::TEXT_ALIGN_CENTER);

echo $tabler->render($layout);