Markdown-it Sticky Table Plugin

一个 markdown-it 插件，用于实现表格的固定头部、固定列和横向滚动功能。

功能特性

1. 固定表格头部: 滚动时表头始终保持可见
2. 固定前N行: 支持固定前N行数据（不仅限于表头）
3. 固定前N列: 支持固定前N列数据，水平滚动时保持可见
4. 交叉固定: 同时支持固定行和列的交叉区域显示
5. 横向滚动: 当表格内容超出屏幕宽度时，可以左右滑动浏览
6. 美观样式: 包含hover效果和自定义滚动条样式
7. 性能优化: CSS样式缓存机制，提升渲染性能
8. 错误处理: 完善的参数验证和错误提示
9. 可配置选项: 支持自定义最大高度、样式类名、固定行数和列数等

构建和测试

构建项目

# 构建生产版本（生成 CommonJS 和 ES Module 两种格式）
npm run build

# 开发模式（监听文件变化）
npm run dev

运行测试

# 测试 CommonJS/UMD 版本
npm test

# 测试 ES Module 版本
npm run test:esm

# 运行所有测试
npm run test:all

生成测试html

node test/test-sticky-rows.js

使用方法

CommonJS/Node.js

const MarkdownIt = require('markdown-it');
const stickyTablePlugin = require('markdown-it-sticky-table');

const md = new MarkdownIt();
md.use(stickyTablePlugin);

ES Module/Modern JavaScript

import MarkdownIt from 'markdown-it';
import stickyTablePlugin from 'markdown-it-sticky-table';

const md = new MarkdownIt();
md.use(stickyTablePlugin);

浏览器 (UMD)

<script src="https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js"></script>
<script src="path/to/markdown-it-sticky-table.js"></script>

<script>
const md = window.markdownit();
md.use(window.markdownItStickyTable);
</script>

基本用法

const MarkdownIt = require('markdown-it');
const stickyTablePlugin = require('./src/index');

const md = new MarkdownIt();
md.use(stickyTablePlugin);

const markdown = `
| 姓名 | 年龄 | 城市 |
|------|------|------|
| 张三 | 25   | 北京 |
| 李四 | 30   | 上海 |
`;

const html = md.render(markdown);

配置选项

md.use(stickyTablePlugin, {
  className: 'custom-table-container',  // 容器CSS类名
  stickyHeader: true,                   // 是否启用固定头部（向后兼容）
  stickyRows: 3,                       // 固定前N行
  stickyColumns: 2,                    // 固定前N列（新功能）
  horizontalScroll: true,               // 是否启用横向滚动
  maxHeight: '400px'                    // 表格最大高度
});

固定前N行示例

// 只固定表头（默认行为）
md.use(stickyTablePlugin, {
  stickyRows: 1
});

// 固定前3行（表头+前2行数据）
md.use(stickyTablePlugin, {
  stickyRows: 3,
  maxHeight: '300px'
});

// 不固定任何行
md.use(stickyTablePlugin, {
  stickyRows: 0
});

固定前N列示例

// 固定前1列（适用于有ID列的表格）
md.use(stickyTablePlugin, {
  stickyColumns: 1
});

// 固定前2列（适用于有多个标识列的表格）
md.use(stickyTablePlugin, {
  stickyColumns: 2,
  maxHeight: '400px'
});

// 同时固定前2行和前2列
md.use(stickyTablePlugin, {
  stickyRows: 2,
  stickyColumns: 2,
  maxHeight: '400px'
});

// 不固定任何列
md.use(stickyTablePlugin, {
  stickyColumns: 0
});

选项说明

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | className | String | 'sticky-table-container' | 表格容器的CSS类名 | | stickyHeader | Boolean | true | 是否启用固定表头功能（向后兼容） | | stickyRows | Number | 1 | 固定前N行数据，0表示不固定任何行 | | stickyColumns | Number | 0 | 固定前N列数据，0表示不固定任何列 | | horizontalScroll | Boolean | true | 是否启用横向滚动 | | maxHeight | String | '400px' | 表格的最大高度，可设为null禁用 |

参数详细说明

• stickyRows:

  • 设置为 1 时，只固定表头
  • 设置为 3 时，固定表头和前2行数据
  • 设置为 0 时，不固定任何行
  • 每个固定行都有独特的z-index和背景色

• stickyColumns:

  • 设置为 1 时，只固定第一列
  • 设置为 2 时，固定前两列
  • 设置为 0 时，不固定任何列
  • 每个固定列默认宽度为150px，有独特的z-index和背景色
  • 固定列与固定行的交叉区域会自动处理层级和样式

• 交叉固定效果:

  • 同时启用固定行和列时，交叉区域会自动处理
  • 交叉区域的z-index高于单独的行或列
  • 保证固定行在垂直滚动时正常工作，固定列在水平滚动时正常工作

• 向后兼容性:

  • 当 stickyHeader: false 且未设置 stickyRows 时，自动设为 stickyRows: 0
  • 新增的 stickyColumns 参数默认为 0，不影响现有功能
  • 保持与旧版本的完全兼容

测试

运行测试脚本：

npm test

这将生成一个HTML文件 test/output.html，在浏览器中打开可以测试插件功能。

构建

开发模式（监听文件变化）：

npm run dev

生产构建：

npm run build

生成的HTML结构

插件会将原始的markdown表格转换为以下HTML结构：

<div class="sticky-table-container" style="max-height: 400px; overflow-y: auto; overflow-x: auto; position: relative;">
  <table class="sticky-table">
    <thead class="sticky-header">
      <tr class="sticky-row sticky-row-0">
        <th>列1</th>
        <th>列2</th>
      </tr>
    </thead>
    <tbody>
      <tr class="sticky-row sticky-row-1">
        <td>第1行数据</td>
        <td>第1行数据</td>
      </tr>
      <tr class="sticky-row sticky-row-2">
        <td>第2行数据</td>
        <td>第2行数据</td>
      </tr>
      <tr>
        <td>普通行</td>
        <td>普通行</td>
      </tr>
    </tbody>
  </table>
</div>
<style>
  /* CSS样式会自动插入，包含固定行的样式 */
</style>

CSS类说明

• sticky-table-container: 表格容器
• sticky-table: 表格本体
• sticky-header: 表头固定样式
• sticky-row: 固定行通用样式
• sticky-row-0, sticky-row-1, etc.: 每个固定行的特定样式
• sticky-column: 固定列通用样式
• sticky-column-0, sticky-column-1, etc.: 每个固定列的特定样式

CSS样式特性

• 固定表头: 使用 position: sticky 实现
• 固定多行: 支持固定前N行，每行有不同的top值和z-index
• 固定多列: 支持固定前N列，每列有不同的left值和z-index
• 交叉固定: 固定行和列的交叉区域自动处理层级和样式
• 横向滚动: 容器设置 overflow-x: auto
• 美观滚动条: 自定义webkit和Firefox滚动条样式
• 悬停效果: 表格行和固定列的hover效果，交叉区域有特殊的hover样式
• 层级管理: 自动管理固定行、列和交叉区域的z-index，确保正确的显示层级
• 性能优化: CSS样式缓存机制，避免重复生成
• 响应式设计: 适配不同屏幕尺寸

浏览器兼容性

• Chrome/Safari: 完全支持
• Firefox: 完全支持
• Edge: 完全支持
• IE11: 部分支持（sticky定位可能不工作）

许可证

MIT License