# HTML Table 类

Table 类提供了用于从数组或数据库结果集自动生成 HTML 表格的方法。

## 使用 Table 类

### 初始化类

Table 类不作为服务提供，应"常规"实例化，例如：

    <?php

    $table = new \CodeIgniter\View\Table();

### 示例

以下示例展示如何从多维数组创建表格。注意第一个数组索引将成为表头（也可以使用下方函数参考中介绍的 `setHeading()` 方法设置自定义标题）。

    <?php

    $table = new \CodeIgniter\View\Table();

    $data = [
        ['Name', 'Color', 'Size'],
        ['Fred', 'Blue', 'Small'],
        ['Mary', 'Red', 'Large'],
        ['John', 'Green', 'Medium'],
    ];

    echo $table->generate($data);

以下示例展示从数据库查询结果创建表格。Table 类会根据表名自动生成标题（也可以使用下方类参考中介绍的 `setHeading()` 方法设置自定义标题）。

    <?php

    $table = new \CodeIgniter\View\Table();

    $query = $db->query('SELECT * FROM my_table');

    echo $table->generate($query);

以下示例展示如何使用独立参数创建表格：

    <?php

    $table = new \CodeIgniter\View\Table();

    $table->setHeading('Name', 'Color', 'Size');

    $table->addRow('Fred', 'Blue', 'Small');
    $table->addRow('Mary', 'Red', 'Large');
    $table->addRow('John', 'Green', 'Medium');

    echo $table->generate();

以下示例与上例相同，但使用数组而非单独的参数：

    <?php

    $table = new \CodeIgniter\View\Table();

    $table->setHeading(['Name', 'Color', 'Size']);

    $table->addRow(['Fred', 'Blue', 'Small']);
    $table->addRow(['Mary', 'Red', 'Large']);
    $table->addRow(['John', 'Green', 'Medium']);

    echo $table->generate();

### 改变表格外观

Table 类允许设置表格模板来指定期望的布局设计。以下是模板原型：

    <?php

    $template = [
        'table_open' => '<table border="0" cellpadding="4" cellspacing="0">',

        'thead_open'  => '<thead>',
        'thead_close' => '</thead>',

        'heading_row_start'  => '<tr>',
        'heading_row_end'    => '</tr>',
        'heading_cell_start' => '<th>',
        'heading_cell_end'   => '</th>',

        'tfoot_open'  => '<tfoot>',
        'tfoot_close' => '</tfoot>',

        'footing_row_start'  => '<tr>',
        'footing_row_end'    => '</tr>',
        'footing_cell_start' => '<td>',
        'footing_cell_end'   => '</td>',

        'tbody_open'  => '<tbody>',
        'tbody_close' => '</tbody>',

        'row_start'  => '<tr>',
        'row_end'    => '</tr>',
        'cell_start' => '<td>',
        'cell_end'   => '</td>',

        'row_alt_start'  => '<tr>',
        'row_alt_end'    => '</tr>',
        'cell_alt_start' => '<td>',
        'cell_alt_end'   => '</td>',

        'table_close' => '</table>',
    ];

    $table->setTemplate($template);

备注

模板中提供两组 "row" 块，用于创建交替的行颜色，或使设计元素随数据行的每次迭代交替呈现。

无需提交完整模板。如果只需更改布局的某些部分，只需提交相应元素即可。以下示例仅更改表格起始标签：

    <?php

    $template = [
        'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">',
    ];

    $table->setTemplate($template);

还可以通过将模板设置数组传递给 Table 构造函数来设置默认值：

    <?php

    $customSettings = [
        'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">',
    ];

    $table = new \CodeIgniter\View\Table($customSettings);

### 将行与标题同步

Added in version 4.4.0.

如果使用关联数组作为参数，`setSyncRowsWithHeading(true)` 方法可使每个数据值放置在 `setHeading()` 所定义的对应列中。这在通过 REST API 加载数据时尤其有用——API 返回的数据顺序可能不符合需求，或者返回了过多数据。

如果数据行包含标题中不存在的键，其值会被过滤。反之，如果数据行缺少标题中列出的键，会在对应位置放置空单元格。

    <?php

    $table = new \CodeIgniter\View\Table();

    $table->setHeading(['name' => 'Name', 'color' => 'Color', 'size' => 'Size'])
        ->setSyncRowsWithHeading(true)
        ->addRow(['color' => 'Blue', 'name' => 'Fred', 'size' => 'Small'])
        ->addRow(['size' => 'Large', 'age' => '24', 'name' => 'Mary'])
        ->addRow(['color' => 'Green']);

    echo $table->generate();
    ?>

    <!-- Generates a table with this prototype: -->
    <table border="0" cellpadding="4" cellspacing="0">
        <thead>
            <tr>
                <th>Name</th>
                <th>Color</th>
                <th>Size</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Fred</td>
                <td>Blue</td>
                <td>Small</td>
            </tr>
            <tr>
                <td>Mary</td>
                <td></td>
                <td>Large</td>
            </tr>
            <tr>
                <td></td>
                <td>Green</td>
                <td></td>
            </tr>
        </tbody>
    </table>

重要

在通过 `addRow([...])` 添加任何行之前，必须先调用 `setSyncRowsWithHeading(true)` 和 `setHeading([...])`，才能进行列的重排。

使用数组作为 `generate()` 的输入会产生相同结果：

    <?php

    $data = [
        [
            'color' => 'Blue',
            'name'  => 'Fred',
            'size'  => 'Small',
        ],
        [
            'size' => 'Large',
            'age'  => '24',
            'name' => 'Mary',
        ],
        [
            'color' => 'Green',
        ],
    ];

    $table = new \CodeIgniter\View\Table();

    $table->setHeading(['name' => 'Name', 'color' => 'Color', 'size' => 'Size'])
        ->setSyncRowsWithHeading(true);

    echo $table->generate($data);

## 类参考

class CodeIgniter\View\Table
  $function = null

    用于指定一个 PHP 原生函数或有效的函数数组对象，应用于所有单元格数据。

        <?php

        $table = new \CodeIgniter\View\Table();

        $table->setHeading('Name', 'Color', 'Size');
        $table->addRow('Fred', '<strong>Blue</strong>', 'Small');

        $table->function = 'htmlspecialchars';
        echo $table->generate();

    上例中，所有单元格数据都会经过 PHP 的 `htmlspecialchars()` 函数处理，结果为:

        <td>Fred</td><td>&lt;strong&gt;Blue&lt;/strong&gt;</td><td>Small</td>

  generate([$tableData = null])
    参数:

      - $tableData (`mixed`) -- 用于填充表格行的数据

    返回:

      HTML 表格

    返回类型:

      `string`

    返回包含已生成表格的字符串。接受可选参数，可以是数组或数据库结果对象。

  setCaption($caption)
    参数:

      - $caption (`string`) -- 表格标题

    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    用于为表格添加标题。

        <?php

        $table->setCaption('Colors');

  setHeading([$args = [][, ...]])
    参数:

      - $args (`mixed`) -- 包含表格列标题的数组或多个字符串

    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    用于设置表格标题。可提交数组或独立参数：

        <?php

        $table->setHeading('Name', 'Color', 'Size'); // or

        $table->setHeading(['Name', 'Color', 'Size']);

  setFooting([$args = [][, ...]])
    参数:

      - $args (`mixed`) -- 包含表格脚注值的数组或多个字符串

    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    用于设置表格脚注。可提交数组或独立参数：

        <?php

        $table->setFooting('Subtotal', $subtotal, $notes); // or

        $table->setFooting(['Subtotal', $subtotal, $notes]);

  addRow([$args = [][, ...]])
    参数:

      - $args (`mixed`) -- 包含行值的数组或多个字符串

    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    用于为表格添加行。可提交数组或独立参数：

        <?php

        $table->addRow('Blue', 'Red', 'Green'); // or

        $table->addRow(['Blue', 'Red', 'Green']);

    如需设置单个单元格的标签属性，可为该单元格使用关联数组。 关联键 data 定义单元格的数据。任何其他 key => val 键值对会作为 key='val' 属性添加到标签上：

        <?php

        $cell = ['data' => 'Blue', 'class' => 'highlight', 'colspan' => 2];
        $table->addRow($cell, 'Red', 'Green');

        ?>

        <!-- Generates: -->
        <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td>

  makeColumns([$array = [][, $columnLimit = 0]])
    参数:

      - $array (`array`) -- 包含多行数据的数组

      - $columnLimit (`int`) -- 表格的列数

    返回:

      HTML 表格列数组

    返回类型:

      `array`

    此方法接受一维数组作为输入，并创建一个深度等于所需列数的多维数组。 这样就能将包含多个元素的单维数组以固定列数的表格显示。参考以下示例：

        <?php

        $list = ['one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'];

        $newList = $table->makeColumns($list, 3);

        $table->generate($newList);

        ?>

        <!-- Generates a table with this prototype: -->
        <table border="0" cellpadding="4" cellspacing="0">
            <tr>
                <td>one</td>
                <td>two</td>
                <td>three</td>
            </tr>
            <tr>
                <td>four</td>
                <td>five</td>
                <td>six</td>
            </tr>
            <tr>
                <td>seven</td>
                <td>eight</td>
                <td>nine</td>
            </tr>
            <tr>
                <td>ten</td>
                <td>eleven</td>
                <td>twelve</td>
            </tr>
        </table>

  setTemplate($template)
    参数:

      - $template (`array`) -- 包含模板值的关联数组

    返回:

      成功返回 true，失败返回 false

    返回类型:

      `bool`

    用于设置模板。可提交完整或部分模板。

        <?php

        $template = [
            'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">',
        ];

        $table->setTemplate($template);

  setEmpty($value)
    参数:

      - $value (`mixed`) -- 放入空单元格的值

    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    用于为所有空单元格设置默认值。例如，可将其设置为不换行空格：

        <?php

        $table->setEmpty('&nbsp;');

  clear()
    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    清除表格标题、行数据和标题。如果需要用不同数据展示多个表格， 应在每个表格生成后调用此方法，清除上一个表格的信息。

    示例

        <?php

        $table = new \CodeIgniter\View\Table();

        $table->setCaption('Preferences')
            ->setHeading('Name', 'Color', 'Size')
            ->addRow('Fred', 'Blue', 'Small')
            ->addRow('Mary', 'Red', 'Large')
            ->addRow('John', 'Green', 'Medium');

        echo $table->generate();

        $table->clear();

        $table->setCaption('Shipping')
            ->setHeading('Name', 'Day', 'Delivery')
            ->addRow('Fred', 'Wednesday', 'Express')
            ->addRow('Mary', 'Monday', 'Air')
            ->addRow('John', 'Saturday', 'Overnight');

        echo $table->generate();

  setSyncRowsWithHeading(bool $orderByKey)
    返回:

      Table 实例（方法链式调用）

    返回类型:

      `Table`

    使每行数据的键按标题键的顺序排列。由此可更好地控制数据放在正确的列中。 确保在首次调用 `addRow()` 方法之前设置此值。