CKEditor 5 中的表格（概述）

表格功能为您提供了创建和编辑表格的工具。表格非常适合以清晰、直观的方式组织数据。

# 演示

使用插入表格按钮 将新表格插入内容中。单击表格内部以打开上下文工具栏。该工具栏允许您添加或删除列 和行 。您还可以合并或拆分单元格 。

尝试切换标题的显示和隐藏 。您还可以更改整个表格 或单个单元格 的属性。要控制列的宽度，请单击并拖动其边缘。

阅读完本指南后，您可以在 CKEditor 5 中的表格 博客文章中寻找更多有趣的细节。

# 基本表格功能

基本表格功能允许用户将表格插入内容中，添加或删除列和行，以及合并或拆分单元格。

@ckeditor/ckeditor5-table 包含多个插件，实现了各种与表格相关的功能。Table 插件是生态系统的核心，它提供了表格功能。还有许多其他功能扩展了编辑器的功能

# 表格选择

TableSelection 插件引入了对表格的自定义选择系统的支持，该系统允许您

• 选择任意矩形表格片段 - 来自不同行的几个单元格、一列（或几列）或一行（或多行）。
• 一次性将格式或链接应用于所有选定的单元格。

表格选择插件由 Table 插件自动加载，可以在 上面的演示中 测试。

# 在表格周围键入

要轻松地在表格之前或之后键入，请选择表格，然后根据您要添加内容的位置（之前或之后）按一次箭头键 (← 或 →)。表格将不再处于选中状态，您键入的任何文本都将出现在所需位置。

# 嵌套表格

CKEditor 5 允许在其他表格的单元格内嵌套表格。这可用于创建基于表格的高级图表或布局。嵌套表格可以像常规表格一样进行格式化。

# 演示

您可以在下面的演示中测试此功能，方法是在现有表格底部空白的“已放弃”部分中添加一个新表格。单击单元格内部，然后使用插入表格按钮 。嵌套表格将出现在单元格内。

# 已知问题

虽然嵌套表格功能齐全，但使用 Markdown 输出 功能生成的 Markdown 代码将无法正确呈现嵌套表格 (#9475)。如果您认为此问题很重要，请随时在 GitHub 上点赞 👍 此问题。

# 表格上下文工具栏

The TableToolbar plugin introduces a contextual toolbar for table. The toolbar appears when a table or a cell is selected and contains various table-related buttons. These would typically include add or remove columns and rows and merge or split cells . If these features are configured, the toolbar will also contain buttons for captions and table and cell properties.

The table selection plugin is loaded automatically by the Table plugin and can be tested in the demo above. Learn more about configuring a contextual toolbar in the Common API section below.

# 表格单元格中的块级内容与内联内容

表格功能允许在表格单元格内创建块级内容（例如段落、列表、标题等）。但是，如果表格单元格只包含一个段落，并且该段落没有特殊属性（例如文本对齐），则单元格内容被视为“内联”，并且段落不会被渲染。

这意味着表格单元格可以有两种状态：内联内容或块级内容。造成这种区别的原因是，大多数表格只包含内联内容（例如上面的演示），而“数据表格”通常不包含任何块级内容。在这种情况下，打印出<p>元素在语义上是错误的，也是不必要的。但是，在某些情况下，用户希望在表格单元格内创建一个列表，例如，此时需要支持块级内容。

# 内联内容

以下是仅包含内联内容的表格单元格的模型表示（一个<paragraph>在里面）

<table>
    <tableRow>
        <tableCell>
            <paragraph>Foo</paragraph>
        </tableCell>
        <tableCell>
            <paragraph>Bar</paragraph>
        </tableCell>
    </tableRow>
</table>

上面的模型结构将被渲染到数据中，如下所示

<figure class="table">
    <table>
        <tbody>
            <tr>
                <td>Foo</td>
                <td>Bar</td>
            </tr>
        </tbody>
    </table>
</figure>

在编辑视图（用户编辑内容的可编辑容器）中，将创建额外的<span>元素以补偿隐藏的<paragraph>元素

<figure class="table">
    <table>
        <tbody>
            <tr>
                <td><span>Foo</span></td>
                <td><span>Bar</span></td>
            </tr>
        </tbody>
    </table>
</figure>

# 块级内容

如果表格单元格包含除没有属性的单个<paragraph>之外的任何其他块级内容，这些块级元素将被渲染。

以下是一个包含一些块级内容的示例表格（模型表示）

<table>
    <tableRow>
        <tableCell>
            <paragraph>Foo</paragraph>
            <paragraph>Bar</paragraph>
        </tableCell>
        <tableCell>
            <heading1>Some title</heading1>
        </tableCell>
        <tableCell>
            <paragraph textAlign="right">Baz</paragraph>
        </tableCell>
    </tableRow>
</table>

上面的模型结构将被渲染到数据和编辑视图中，如下所示

<figure class="table">
    <table>
        <tbody>
            <tr>
                <td>
                    <p>Foo</p>
                    <p>Bar</p>
                </td>
                <td>
                    <h2>Some title</h2>
                </td>
                <td>
                    <p style="text-align: right;">Baz</p>
                </td>
            </tr>
        </tbody>
    </table>
</figure>

# 安装

在安装编辑器后，将功能添加到插件列表和工具栏配置中

import { ClassicEditor, Table, TableToolbar } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Table, TableToolbar, Bold, /* ... */ ],
        toolbar: [ 'insertTable', /* ... */ ],
        table: {
            contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 默认表格标题

为了使每个插入的表格默认具有n行和列作为表格标题，请设置一个可选的表格配置属性defaultHeadings，如下所示

import { ClassicEditor, Table, TableToolbar } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Table, TableToolbar, Bold, /* ... */ ],
        toolbar: [ 'insertTable', /* ... */ ],
        table: {
            defaultHeadings: { rows: 1, columns: 1 }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

查看应用于第一行和第一列的默认标题的表格，在下面的演示中。点击表格，使用列属性 或行属性 UI 按钮来切换相应的标题。

# 禁止嵌套表格

默认情况下，编辑器允许在另一个表格的单元格内嵌套表格。

要禁止嵌套表格，您需要注册一个额外的模式规则。它需要在数据加载到编辑器之前添加。因此，最好将其作为插件实现

function DisallowNestingTables( editor ) {
    editor.model.schema.addChildCheck( ( context, childDefinition ) => {
        if ( childDefinition.name == 'table' && Array.from( context.getNames() ).includes( 'table' ) ) {
            return false;
        }
    } );
}

// Pass it via config.extraPlugins or config.plugins:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        extraPlugins: [ DisallowNestingTables ],

        // The rest of the configuration.
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 通用 API

# UI 组件

The Table plugins register the following UI components

组件 名称	注册者
'insertTable' 下拉菜单	表格
'tableColumn' 下拉菜单
'tableRow' 下拉菜单
'mergeTableCells' 分割按钮

# 工具栏

The TableToolbar plugin introduces two balloon toolbars for tables.

• The content toolbar shows up when a table cell is selected and it is anchored to the table. It is possible to configure its content. Normally, the toolbar contains the table-related tools such as 'tableColumn' and 'tableRow' dropdowns and 'mergeTableCells' split button.
• The table toolbar shows up when the whole table is selected, for instance using the widget handler. It is possible to configure its content.

# 编辑器命令

命令 名称	命令类	属于（顶级插件）
'insertTable'	InsertTableCommand	表格
'insertTableColumnLeft'	InsertColumnCommand
'insertTableColumnRight'	InsertColumnCommand
'insertTableRowAbove'	InsertRowCommand
'insertTableRowBelow'	InsertRowCommand
'removeTableColumn'	RemoveColumnCommand
'removeTableRow'	RemoveRowCommand
'selectTableColumn'	SelectColumnCommand
'selectTableRow'	SelectRowCommand
'setTableColumnHeader'	SetHeaderColumnCommand
'setTableRowHeader'	SetHeaderRowCommand
'mergeTableCellRight'	MergeCellCommand
'mergeTableCellLeft'	MergeCellCommand
'mergeTableCellUp'	MergeCellCommand
'mergeTableCellDown'	MergeCellCommand
'splitTableCellVertically'	SplitCellCommand
'splitTableCellHorizontally'	SplitCellCommand

# 贡献

该功能的源代码可在 GitHub 上获取，地址为 https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table。