README file from
GithubMerged Table · 表格合并
一个 Obsidian 插件:在 Markdown 笔记中创建、编辑带合并单元格的表格,并支持把已经存在的普通 Markdown 表格转换为可合并表格。

功能
- 真正的合并单元格:支持横向、纵向以及 2×2 以上的矩形合并,阅读视图和实时预览都能正确显示。
- 可视化表格编辑器:拖动选择区域,点击“合并”;支持拆分、插入/删除行列、左/中/右对齐、撤销。
- 右键菜单:选中单元格后右键,可直接“合并选中单元格”“与右侧单元格合并”“与下方单元格合并”“拆分单元格”,也可以打开编辑器。
- 兼容旧表格:对安装插件之前创建的普通 Markdown 表格,在阅读视图或编辑器中右键即可转换并合并,不会要求重新录入。
- 单元格内容保留:合并时保留区域内所有非空内容(用空格连接),不会静默丢弃。
- Markdown 单元格内容:单元格内可继续使用粗体、链接、行内代码等 Markdown 语法。
- 纯本地:不联网、不上传笔记。

安装
GitHub 发布页:https://github.com/Frecely/obsidian-merged-table/releases
手动安装
-
下载
merged-table-1.0.2.zip(或直接使用本项目的dist/merged-table文件夹),解压后得到merged-table文件夹。 -
把整个
merged-table文件夹放到你的仓库目录:<你的仓库>/.obsidian/plugins/merged-table/文件夹内应包含:
main.js manifest.json styles.css -
打开 Obsidian → 设置 → 第三方插件 → 关闭“安全模式” → 重新加载已安装插件。
-
在“已安装插件”中启用 Merged Table。
要求 Obsidian 1.4.0 或更高版本。
从源码构建
node tools/build.mjs
node --test tests/model.test.js
构建结果会写入项目根目录的 main.js 和 dist/merged-table/。
使用
新建合并表格
- 点击左侧功能区的表格图标,或
- 打开命令面板,执行 “插入可合并表格”。
在阅读视图中执行插入时,插件会把表格追加到笔记末尾;如果需要插入到光标位置,请切换到实时预览/编辑模式。阅读视图中的右键菜单不受影响。
在弹出的编辑器中:
- 默认是 3×3 空表,可以直接输入内容;
- 用鼠标拖动选择多个单元格,或按住
Shift单击扩展选择; - 点击 合并;
- 点击 保存,表格会以
merged-table代码块的形式插入到光标位置。
合并已有的 Markdown 表格
这是为了兼容安装插件之前创建的表格:
- 在阅读视图中右键表格,或在实时预览/源码模式中右键表格单元格;
- 选择 “合并单元格…(转换为增强表格)”;
- 在弹出的编辑器里选择区域并合并;
- 保存后会转换为
merged-table代码块,原表格中的文字、链接等内容会保留。
也可以在命令面板执行 “编辑光标处的表格 / 合并单元格”。
普通 Markdown 表格本身不支持
colspan/rowspan,因此第一次合并时需要转换格式。转换是保存时发生的;取消不会修改笔记。
在渲染后的表格上直接操作
对于已经转换过的表格:
- 拖动选择单元格;
Shift+ 单击扩展选择; - 右键选中的区域:
- 合并选中单元格
- 与右侧单元格合并
- 与下方单元格合并
- 拆分单元格
- 编辑表格…
- 双击单元格打开可视化编辑器;
- 鼠标悬停时右上角会出现铅笔按钮,也可以打开编辑器。
快捷键/命令
| 命令 | 说明 |
|---|---|
| 插入可合并表格 | 打开编辑器并插入新表(阅读视图会追加到末尾) |
| 编辑光标处的表格 / 合并单元格 | 编辑光标所在的增强表格或普通表格(编辑模式) |
| 将 Markdown 表格转换为可合并表格 | 仅转换光标所在的普通表格(编辑模式) |
表格语法
增强表格使用 merged-table 代码块,内容仍然是 Markdown 表格,只是用两个标记表示被覆盖的单元格:
<:该单元格与左侧单元格合并;^:该单元格与上方单元格合并。
例如:
```merged-table
| 区域 | 上半年 | < | 下半年 | < | 全年 |
| --- | --- | --- | --- | --- | --- |
| 华东 | 128 | 156 | 142 | 168 | 594 |
| 西北 | 50 | 62 | 58 | 70 | 240 |
| ^ | 22 | 28 | 30 | 34 | 114 |
```
渲染后:
- “上半年”横跨两列;
- “下半年”横跨两列;
- “西北”纵跨两行。
规则:
- 一个合并区域必须是完整矩形;
- 带内容的单元格必须位于合并区域的左上角;
- 合并区域不能跨越表头与表体(HTML 表格限制);
- 如果单元格内容本身就是
<或^,请写成\<或\^; - 单元格内的
|需要转义为\|;单元格内换行会保存为<br>。
设计说明
Obsidian 的原生 Markdown 表格无法表达 colspan / rowspan,而实时预览中的原生表格是 Obsidian 自己维护的可编辑组件,直接修改它的 DOM 会破坏光标、Tab 导航和源码映射。因此本插件采用:
merged-table代码块作为增强表格的存储格式;- 插件自己的渲染器把它渲染成带
rowspan/colspan的 HTML 表格; - 可视化编辑器负责安全地修改行列结构和合并关系;
- 对原生 Markdown 表格提供右键转换入口。
这样阅读视图和实时预览的行为一致,也不会和 Obsidian 的原生表格编辑器互相干扰。
限制
- 合并后的表格以代码块存储,源码模式下会看到
merged-table围栏和</^标记。 - 从普通 Markdown 表格转换是单向的;转换后可以用编辑器的“拆分”逐个还原单元格,但不会自动还原成普通 Markdown 表格。转换会改写原表格,建议先备份笔记或确认仓库已有版本历史。
- 在阅读视图中右键合并会直接写入文件;如需撤销,请使用 Obsidian 的文件恢复/版本历史。实时预览/编辑模式下可以使用编辑器撤销。
- 合并多个非空单元格时,内容用空格连接保留;不会自动排版成多行。保存前可以在“单元格内容”框中调整。
- 表头与表体之间不能合并(这是 HTML 表格的限制,不是插件限制)。
- 仅支持矩形合并;不支持斜线表头、嵌套表格等。
开发
src/
model.js 纯数据模型:合并、拆分、行列增删、对齐
parser.js Markdown 表格解析、< / ^ 标记解析、序列化
locate.js 在编辑器中定位增强表格和原生表格
editor.js 可视化编辑器 Modal
main.js Obsidian 插件入口、渲染、右键菜单、命令
tests/
model.test.js
tools/
build.mjs 零依赖打包脚本
cdp.mjs 开发时用于连接 Obsidian 调试端口的脚本
测试:
node --test tests/model.test.js
License
MIT