# Vtable

**Repository Path**: vmsimab/vtable

## Basic Information

- **Project Name**: Vtable
- **Description**: Vtable —— 在 Obsidian 中创建富文本增强表格。每一个单元格都能独立支持较为完整的渲染，且支持单元格合并。底层基于标准 JSON 格式，简洁透明、易于读写
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vtable — Obsidian 增强表格插件

> **告别原生表格的三大痛点：无法格内换行、无法合并单元格、无法公式计算**

在 Obsidian 中创建**可视化、可编辑的表格**，支持富文本格式化、公式计算、图表导出等高级功能。

---

## 为什么需要 vtable？

Obsidian 原生 Markdown 表格存在明显局限：

| 痛点           | 原生表格                       | vtable                         |
| -------------- | ------------------------------ | ------------------------------ |
| **格内换行**   | ❌ 回车跳出单元格，无法多行输入 | ✅ 单元格内自由回车，内容不丢失 |
| **合并单元格** | ❌ 完全不支持                   | ✅ 任意行列合并，一键操作       |
| **公式计算**   | ❌ 手动计算，易出错             | ✅ Excel 风格公式，自动求值     |
| **数据可视化** | ❌ 需借助其他工具               | ✅ 一键生成柱状图/饼图/折线图   |

---

## 快速开始

### 创建表格

1. 打开命令面板（`Ctrl/Cmd + P`）
2. 选择 **"创建 vtable"**
3. 在笔记中即出现可编辑表格，直接输入内容

### 转换已有表格

选中 Markdown 表格或 HTML 表格 → 执行 **"转换为 vtable"** → 一键转为可编辑表格

---

## 核心优势

### 1. 格内回车换行 — 终于可以在单元格里自由换行了

原生表格按下回车就会跳出单元格，vtable 让你在单元格内自由编辑多行内容，表格结构始终完整。

### 2. 合并单元格 — 像 Excel 一样灵活

通过浮动工具栏或右键菜单，轻松实现**向下合并**、**向右合并**、**拆分还原**，制作复杂表头不再是噩梦。

### 3. 公式计算 — 内置 Excel 风格函数

![](https://gitee.com/vmsimab/obsidian_images/raw/master/imgs/数据函数.gif)

以 `=` 开头即可启用公式，支持 5 种常用聚合函数：

| 函数      | 说明     | 示例              |
| --------- | -------- | ----------------- |
| `SUM`     | 求和     | `=SUM(A1:C3)`     |
| `AVERAGE` | 求平均值 | `=AVERAGE(A1:A5)` |
| `COUNT`   | 计数     | `=COUNT(B2:B10)`  |
| `MIN`     | 求最小值 | `=MIN(C1:C8)`     |
| `MAX`     | 求最大值 | `=MAX(D5:D15)`    |

> 即使单元格包含 HTML 格式（如 `<b>123</b>`），公式也能正确提取数值。

### 4. 一键图表 — 数据秒变可视化

选中表格执行命令，即可生成**柱状图、饼图、折线图**，图表自动适配深色/浅色主题。

### 5. 自动模板生成 — 图表制作零门槛

不知道图表数据怎么填？**插件启用后自动帮你搞定**：

- 插件会自动检测你的模板文件夹（优先读取 Obsidian 官方 Templates 核心插件的设置路径，若未启用则使用根目录下的 `TEMPLATE` 文件夹）
- 自动创建三个现成模板：`柱状图模板.md`、`饼图模板.md`、`折线图模板.md`
- **无需任何操作**，打开模板文件夹即可看到，直接使用或插入到笔记中

**柱状图模板**（8 行标准结构）：
```
| vbarchart | |
| 标题 | 图表标题 |
| v% | 是 |
| x范围 | |
| x | X轴标签 |
| y范围 | 0-100 |
| y | Y轴标签 |
| 数据项 | 数值 |
```

**饼图模板**（Mermaid 兼容格式）：
```
| vpie | |
| 标题 | 饼图标题 |
| 类别A | 30 |
| 类别B | 70 |
```

**折线图模板**（7 行标准结构）：

```
| vline | |
| 标题 | 图表标题 |
| x范围 | |
| x | X轴标签 |
| y范围 | 0-100 |
| y | Y轴标签 |
| 数据点 | 数值 |
```

> 替换示例数据后执行对应图表命令，即可生成图表 SVG —— **从模板到图表，一步到位**。

---

## 功能详解

### 富文本与 Markdown 渲染

单元格内输入以下语法，失焦后自动渲染：

| 语法                 | 效果              |
| -------------------- | ----------------- |
| `**粗体**`           | **粗体**          |
| `*斜体*`             | *斜体*            |
| `==高亮==`           | 高亮标记          |
| `~~删除~~`           | ~~删除线~~        |
| `` `代码` ``         | 行内代码          |
| `[链接](url)`        | 可点击链接        |
| `![[图片.png]]`      | Obsidian 图片嵌入 |
| `$E=mc^2$`           | LaTeX 行内公式    |
| `$$\sum_{i=1}^n$$`   | LaTeX 块公式      |
| `<span style="...">` | HTML 标签直接渲染 |

### 浮动工具栏

聚焦单元格时自动弹出，包含两行快捷按钮：

**第一行 — 格式与合并：**
`B` 加粗 · `I` 斜体 · `A−/A+` 调整字号 · `拆/合/合→` 单元格合并拆分

**第二行 — 行列与导出：**
`+行/+列` 插入 · `−行/−列` 删除 · `MD` 转 Markdown · `H5` 转 HTML

> 可在设置中分别控制桌面端/移动端是否显示工具栏

### 右键菜单

在单元格上右键 → 快速访问：插入行列、删除行列、合并/拆分单元格

### 格式互转

| 命令                 | 功能                        |
| -------------------- | --------------------------- |
| 转换为 vtable        | Markdown/HTML 表格 → vtable |
| 转换为 Markdown 表格 | vtable → 标准 Markdown 表格 |
| 转换为 HTML 表格     | vtable → HTML `<table>`     |

---

## 全部命令

| 命令                 | 快捷 ID           | 功能                             |
| -------------------- | ----------------- | -------------------------------- |
| 创建 vtable          | `vt-create`       | 插入空白可编辑表格               |
| 转换为 vtable        | `vt-convert`      | 将 Markdown/HTML 表格转为 vtable |
| 转换为 Markdown 表格 | `vt-to-markdown`  | 导出为 Markdown 格式             |
| 转换为 HTML 表格     | `vt-to-html`      | 导出为 HTML 格式                 |
| 转换为柱状图         | `vt-to-barchart`  | 生成柱状图 SVG                   |
| 转换为饼状图         | `vt-to-piechart`  | 生成 Mermaid 饼图                |
| 转换为折线图         | `vt-to-linechart` | 生成折线图 SVG                   |

> 所有命令可在 Obsidian 设置 → 快捷键中绑定自定义热键

---

## 设置项

| 选项             | 说明                          |
| ---------------- | ----------------------------- |
| 电脑端浮窗工具栏 | 桌面端编辑时显示浮动工具栏    |
| 移动端浮窗工具栏 | 手机/平板编辑时显示浮动工具栏 |

路径：Obsidian 设置 → 第三方插件 → vtable

---

## 安装

### 手动安装（推荐）

页面已提供可直接使用的 `main.js`、`styles.css` 和 `manifest.json` 文件，**无需自行构建**：

1. 从 Releases 下载上述三个文件
2. 在 Obsidian 库的 `.obsidian/plugins/` 目录下创建 `vtable` 文件夹
3. 将三个文件放入该文件夹
4. 重启 Obsidian，在设置 → 第三方插件中启用

### 从源码构建

如需自行构建，可参考以下步骤：

```bash
git clone <仓库地址>
cd vtable
npm install
npm run build
```

将生成的 `main.js`、`styles.css` 和 `manifest.json` 复制到 `.obsidian/plugins/vtable/` 即可。

---

## 技术架构

```
vtable/
├── src/                        # 源代码目录
│   ├── main.ts                 # 插件入口、命令注册、设置面板
│   ├── builder.ts              # 数据模型、序列化、行列操作
│   ├── render.ts               # 表格渲染、工具栏、公式/图片渲染
│   ├── bar.ts                  # 浮动工具栏 UI
│   ├── formula.ts              # 公式引擎
│   ├── vbarchart.ts            # 柱状图生成
│   ├── vpiechart.ts            # 饼图生成
│   └── vlinechart.ts           # 折线图生成
├── main.js                     # 编译后的插件主文件
├── styles.css                  # 插件样式
├── manifest.json               # 插件清单
├── package.json                # 项目依赖
├── esbuild.config.mjs          # 构建配置
├── tsconfig.json               # TypeScript 配置
└── LICENSE                     # MIT 许可证
```

---

## 数据存储格式

vtable 使用 JSON 存储表格数据（通常无需手动编辑）：

```json
{"rows":[
  [{"t":"内容","rs":1,"cs":1}, {"t":"","rs":1,"cs":1}],
  [{"t":"","rs":1,"cs":1}, {"t":"","rs":1,"cs":1}]
]}
```

- `t` — 单元格文本（支持 HTML）
- `rs/cs` — 行/列合并数（默认 1，被合并单元格为 0）

---

**让 Obsidian 表格不再是短板。**