XU Table Layout Helper

[!NOTE] 中文说明 表格布局助手：Markdown 表格可视化美化插件，支持表头样式（首行 / 首列 / 颜色）与表格列宽拖拽调整，宽度自动记忆，重开文件不丢失；表格宽度默认自适应铺满页面、跟随窗口缩放。

Markdown 表格零手写 CSS：全局布局设置可视化配置、实时生效；每张表格的列宽可直接用鼠标拖动调整并自动持久化。

English description below for review purposes. / 以下为英文说明，用于过审。

Visual table styling for Markdown tables: header styles (first row / first column / color), drag-to-resize column widths with automatic per-table memory, adaptive fill that keeps tables full-width and responsive, and instant apply in both reading view and live preview — no hand-written CSS.

功能特性

• 表头样式：首行作为表头（默认开启）/ 首列作为表头，两者可同时开启；表头默认加粗，颜色可选（留空跟随主题）
• 列宽拖拽：鼠标悬停表头单元格右边缘出现拖拽手柄，按住拖动即可调整列宽——拖动边界时相邻两列互补伸缩、其余列不动，总宽守恒，1:1 跟手且不会出现单列占满全屏；拖拽时实时显示像素值；双击手柄可输入精确像素值（支持鼠标 / 触控板 / 触屏）
• 手动优先：手动拖拽或输入过的列宽拥有最高优先级，点击自动适配时这些列原样保留，只自动整理其余列；手动标记持久化保存，重启后依然有效；执行「清除本文件的表格列宽」可解除保护
• 列宽记忆：每张表格的列宽自动保存，重新打开文件、重启 Obsidian 后自动恢复；增删表格行不影响已保存的宽度；进入表格编辑、Obsidian 重建表格组件时自动补回；文件删除 / 重命名时自动清理或迁移对应记忆
• 清除列宽：命令面板一键清除当前文件所有表格的已保存列宽（含手动优先标记）
• 自动适配列宽：一键让当前文件可见表格按内容自动调整列宽，长文本单行显示；重复点击结果恒定不外扩；左侧功能区图标 / 命令面板 / 设置页按钮三种触发方式
• 滚动时自动适配（默认开启）：实时预览中视口外的表格不渲染、无法测量，开启后表格滚动进入可视区域时自动适配并记忆——长文档从头滚动到底即完成全文整理；已手动调整的列不会被覆盖
• 自适应铺开：列宽按比例换算为百分比，表格始终铺满页面并跟随窗口动态缩放，无横向滚动条（窄页面内容自动换行）；设置中可切换固定像素模式（默认自适应）
• 表格布局：fixed（固定列宽，推荐）/ auto（自动列宽），表格宽度支持 100% / 像素值
• 单元格排版：垂直对齐（上 / 中 / 下）与行高调整
• 最小列宽：拖拽时的列宽下限保护（默认 40px）
• 双机同步友好：保存前自动合并磁盘最新数据，监听外部文件变化自动重载，避免多设备同步时互相覆盖
• 实时生效：所有设置修改后立即应用，阅读视图与实时预览双视图支持

Features

• Header style: first row as header (on by default) and/or first column as header; headers are always bold, with an optional text color (empty = follow theme)
• Column width drag: hover the right edge of a header cell to grab the drag handle; dragging a boundary grows one column and shrinks its neighbour by the same delta — other columns never move, the total width stays constant, the drag is 1:1 responsive and no column can fill the screen. Live pixel tooltip while dragging; double-click the handle to type an exact value (mouse, trackpad and touch supported)
• Manual priority: columns you resize by hand (drag or exact value) win over every auto-fit: they are kept verbatim and only the other columns are fitted. The manual flag is persisted across restarts; "Clear table column widths in this file" releases the protection
• Width memory: each table's column widths are saved automatically and restored on reopen; adding or removing rows keeps saved widths intact; widths are re-applied when you enter a table and Obsidian rebuilds its widget; deleting or renaming a file cleans up or migrates its records
• Clear widths: one command clears all saved column widths in the current file (including manual-priority flags)
• Table layout: fixed (recommended) / auto, with table width (100% / pixel value)
• Cell layout: vertical alignment (top / middle / bottom) and line height
• Minimum column width: lower bound while dragging (40px by default)
• Auto-fit: one click fits every VISIBLE table in the current file to single-line content; repeated clicks are idempotent (no growth)
• Auto-fit on scroll (on by default): off-viewport tables are not rendered in Live Preview and cannot be measured; with this on, each table is fitted automatically and remembered as it scrolls into view — scrolling through a long document fits the whole file. Manually sized columns are never overwritten
• Adaptive fill: stored widths are applied as percentages so tables always fill the page and resize with the window — no horizontal scrollbar (content wraps on narrow pages); switchable to fixed pixels (adaptive by default)
• Instant apply: settings apply immediately in both reading view and live preview

安装

方式一：从 Obsidian 社区目录安装（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 点击「浏览」，搜索 "XU Table Layout Helper"
3. 点击「安装」，然后「启用」

方式二：手动安装

1. 从 最新 Release 下载 main.js、manifest.json、styles.css 三个文件
2. 在 vault 中创建目录 .obsidian/plugins/table-layout-helper/
3. 将三个文件放入该目录
4. 打开 Obsidian 设置 → 社区插件，找到 XU Table Layout Helper 并开启

Installation

From Obsidian Community Directory:

1. Open Obsidian Settings → Community Plugins
2. Click "Browse" and search for "XU Table Layout Helper"
3. Click "Install", then "Enable"

Manual Installation:

1. Download main.js, manifest.json, styles.css from the latest release
2. Put them in <vault>/.obsidian/plugins/table-layout-helper/
3. Enable in Settings → Community Plugins

使用方法

1. 将鼠标悬停到表头单元格的右边缘，出现高亮竖条后按住拖动（相邻两列互补，其余列不动）
2. 双击拖拽手柄，输入精确像素值后回车或点击「应用」
3. 松开鼠标即自动保存，手动调整的列在后续自动适配中保持不变，重新打开文件后宽度自动恢复
4. 点击左侧功能区图标（或命令面板「自动适配当前文件表格列宽」）整理当前可见表格；长文档滚动浏览时表格会自动逐个适配
5. 需要恢复某文件全部表格的默认宽度时，命令面板执行「清除本文件的表格列宽」

Usage

1. Hover the right edge of a header cell until the highlight bar appears, then drag (the two adjacent columns share the delta; other columns stay put)
2. Double-click the handle to type an exact pixel width, press Enter or click Apply
3. Widths save on release; manually adjusted columns survive later auto-fits and restore automatically on reopen
4. Click the ribbon icon (or run "Auto-fit column widths for current file") to fit visible tables; in long documents tables are fitted one by one as you scroll
5. Run "Clear table column widths in this file" from the command palette to reset the current file

设置说明

命令列表

技术说明

• 纯 JavaScript 实现（main.js），无需编译
• 运行时样式通过动态注入 <style> 应用，依靠选择器特异性覆盖主题（不使用 !important）；仅自动适配列宽的临时测量阶段通过内联样式临时压制换行（覆盖 Obsidian 内部链接的断行设置），测量结束即还原
• 列宽指纹 = 文件路径 + 列数 + 表头哈希 + 首行数据哈希（不含行号），存于插件自身 data.json，不修改笔记内容；旧版含行号的 key 首次加载时自动迁移；手动优先列以 _manual 索引集合持久化在同一记录中
• 拖拽仅在拖动期间挂载 document 级 Pointer Events 监听（rAF 节流），松手即卸载；表格重建监听按表挂载、元素销毁时自清理；滚动自动适配用 IntersectionObserver，仅观察未适配的表格，适配后立即解除观察；无轮询、无全库扫描
• 不使用 Node/Electron API，支持移动端（isDesktopOnly: false）

许可证

MIT License - Copyright (c) 2026 旭说