← 全部文档

布局表格

把表格标记为布局表格,即只用于定位内容的表格(例如电子邮件简报和签名中的表格),而不是带有行和列标题的数据表格。布局表格会获得 role="presentation",因此屏幕阅读器会把它的单元格当作普通文本朗读,而不是读出一个网格。

编辑器中的一个两行两列表格,内容为 Acme Weekly、Issue 42, November 2026、一行头条新闻和 Upcoming events,以细虚线轮廓绘制
用插件插入的布局表格。虚线轮廓只在编辑时显示,让作者能看清单元格。

启用

该功能由 layouttable.js 插件提供(也包含在 plugins/all_plugins.js 中)。它不在任何内置工具栏中。它的命令有:

  • insertlayouttable:在光标处插入一个 2 × 2 的布局表格。
  • toggletablelayout:在布局表格和数据表格之间切换光标所在的表格。
  • tablelayoutmode 和 tabledatamode:把光标所在的表格设为布局表格或数据表格。

这些命令没有自己的图标或标签。要把它们放到工具栏上,请通过 svgCode_<command> 和 text_<command> 为它们提供图标和标签:

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css" />
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/layouttable.js"></script>

<div id="div_editor1"><p>Newsletter header:</p><p><br></p></div>
<script>
var editor1 = new RichTextEditor("#div_editor1", {
  toolbar: "custom",
  toolbar_custom: "{bold,italic,underline}|{inserttable,insertlayouttable,toggletablelayout}|{undo,redo}",
  text_insertlayouttable: "Insert layout table",
  text_toggletablelayout: "Layout / data table",
  svgCode_insertlayouttable: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-dasharray="3 2"><rect x="3" y="4" width="18" height="16" rx="1"/><path d="M12 4v16"/></svg>'
});
</script>

没有 svgCode_toggletablelayout 时,该按钮会显示编辑器的通用占位图标。加载了斜杠菜单插件时,同样的操作无需工具栏:/layout 提供 "Layout table" 和 "Mark table as layout",/data 提供 "Mark table as data"。

输入 /layout 之后的斜杠菜单:Blocks 下的 Columns、Insert 下的 Layout table,以及 Tools 下的 Mark table as layout
加载了斜杠命令插件(此处来自 all_plugins.js)时,输入 /layout 后的斜杠菜单。

选项

选项默认值作用
layoutTableOutlinetrue编辑时在布局表格及其单元格周围绘制虚线轮廓。轮廓只是编辑器内部的样式;永远不会被保存。

切换时会发生什么

切换为布局表格(tablelayoutmode,或在数据表格上切换):

  • 为表格添加 role="presentation" 并删除 summary;
  • 把每个 <th> 变成 <td>,并从单元格中删除 scope、headers 和 abbr;
  • 把 <caption> 的文字移到表格上方的一个段落中,使文字得以保留;
  • 把 <thead> 中的行移到表体中。

只有表格本身会改变;嵌套在其某个单元格中的数据表格会保留其表头。

切换为数据表格(tabledatamode,或在布局表格上切换)会删除该角色。在同一编辑会话中,它还会把原来是表头的单元格恢复为 <th>。这种记忆不会被保存:重新加载内容之后,不会恢复任何东西。此时 API 的 promoteFirstRow 选项会把第一行设为带有 scope="col" 的表头;斜杠菜单的 "Mark table as data" 就使用了它。

一个带有标题和表头行的数据表格,切换为布局表格、重新加载、再切换回数据表格,经历了以下步骤:

<!-- to layout -->
<p>Prices</p>
<table role="presentation"><tbody><tr><td>Plan</td><td>Price</td></tr><tr><td>Basic</td><td>$10</td></tr></tbody></table>
<!-- reloaded, then setTableLayoutMode("data", null, { promoteFirstRow: true }) -->
<table><tbody><tr><th scope="col">Plan</th><th scope="col">Price</th></tr><tr><td>Basic</td><td>$10</td></tr></tbody></table>

如果中间没有重新加载,切换回来后会再次得到 <th> 单元格,但没有它们的 scope,而且标题仍然是一个段落。

API

  • editor1.insertLayoutTable(rows, cols, { width }):插入一个布局表格(默认为 2 × 2 且 width: 100%)并返回它。
  • editor1.setTableLayoutMode("layout" | "data", table, { promoteFirstRow }):table 默认为光标所在的表格。
  • editor1.getTableLayoutMode(table) 返回 "layout"、"data" 或 null(没有表格);editor1.isLayoutTable(table) 返回一个布尔值。role="presentation" 和 role="none" 都算作布局表格。
  • editor1.toggleTableLayoutMode()、editor1.listLayoutTables()(文档中的所有布局表格)、editor1.showLayoutTableOutlines(false)(隐藏虚线轮廓;true 显示轮廓)。

注意事项

  • 插入的布局表格保存为:
    <table role="presentation" cellpadding="0" cellspacing="0" style="width: 100%; border-collapse: collapse"><tbody><tr><td style="vertical-align: top">Acme Weekly</td><td style="vertical-align: top">Issue 42, November 2026</td></tr>…</tbody></table>
    不会添加任何类;role="presentation" 就是全部的标记。cellpadding、cellspacing 和 border-collapse 是为电子邮件客户端准备的。
  • 无障碍检查器不会要求布局表格提供表头单元格,而是会报告仍带有数据表格标记的布局表格。
  • 净化程序必须保留 table 上的 role 属性。

相关内容:文字处理工具演示、表格支持演示、邮件营销演示。