@evansun/excel-designer

@evansun/excel-designer

基于 Canvas + Vue 3 的在线 Excel 表格组件库。支持单元格合并、行高列宽拖拽、公式引擎、撤销重做、序列化等完整功能。

特性

• 纯 Canvas 渲染 — 不依赖 DOM 表格，性能稳定，支持大数据量
• 单元格合并 — 合并/取消合并（Ctrl+M），支持跨行跨列合并
• 行高列宽调整 — 表头边线拖拽、双击自适应、右键数值精确设置
• 空白区可用 — 数据区外的空白网格可直接点击选中、合并、输入文字，按需自动扩展行列
• 公式引擎 — 内置公式解析器，支持 SUM、AVERAGE 等常用函数与单元格引用
• 撤销/重做 — 完整的历史栈，所有编辑操作可撤销
• 序列化 — exportJSON / loadJSON 完整往返，支持合并、尺寸、样式持久化
• Vue 3 组件 — 提供 SpreadsheetCanvas 和 Toolbar 开箱即用组件

安装

npm install @evansun/excel-designer
# 或
pnpm add @evansun/excel-designer

Peer Dependencies

{ "vue": "^3.3.0" }

快速开始

Vue 3 项目中使用

<template>
  <div class="app">
    <Toolbar
      :cell-style="activeStyle"
      :can-undo="canUndo"
      :can-redo="canRedo"
      :merged="isMerged"
      @undo="handleUndo"
      @redo="handleRedo"
      @apply-style="handleApplyStyle"
      @toggle-merge="handleToggleMerge"
      @insert-row="handleInsertRow"
      @delete-row="handleDeleteRow"
      @insert-col="handleInsertCol"
      @delete-col="handleDeleteCol"
    />
    <SpreadsheetCanvas
      ref="canvasRef"
      :sheet-data="initialData"
      :show-toolbar="true"
      :show-save="true"
      :extra-data="{ zones: zoneConfig }"
      @ready="onReady"
      @selection-changed="onSelectionChanged"
      @cell-change="onCellChange"
      @history-change="onHistoryChange"
      @save="handleSave"
      @export="handleExport"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { SpreadsheetCanvas, Toolbar } from '@evansun/excel-designer'
import '@evansun/excel-designer/style.css'

const canvasRef = ref()
const initialData = ref(null) // 从后端加载的表格数据
const zoneConfig = ref({})    // 额外配置（带区等）
let engine = null

function onReady(api) {
  engine = api
}

function handleSave(payload) {
  // payload = { version, savedAt, workbook, ...extraData }
  console.log('保存数据', payload)
  // 发送到后端
}

function handleExport(data) {
  console.log('导出 JSON', data)
}
</script>

仅使用核心引擎（不依赖 Vue）

import { Spreadsheet } from '@evansun/excel-designer'

const canvas = document.getElementById('my-canvas')
// 可传入外部数据，不传则使用默认示例数据
const engine = new Spreadsheet(canvas, {
  sheetData: serverData  // 可选，传入则作为初始数据加载
})

engine.on('ready', () => {
  console.log('表格就绪')
})

engine.on('selection-changed', (data) => {
  console.log('选区变化', data)
})

engine.mount()

// 导出数据
const json = engine.exportJSON()

// 加载数据
engine.loadJSON(newData)

核心模型导出

除组件外，库还导出以下核心类和工具函数，可用于二次开发：

import {
  Sheet, Row, Cell,        // 数据模型
  DEFAULT_STYLE,            // 默认样式常量
  MIN_ROW_HEIGHT,           // 最小行高（18）
  MIN_COL_WIDTH,            // 最小列宽（36）
  colIndexToLetter,         // 列索引→字母（0→A, 26→AA）
  colLetterToIndex,         // 列字母→索引（A→0）
  LayoutCache,              // 布局缓存（prefixSum 前缀和）
  History,                  // 撤销/重做历史栈
  Selection,                // 选区管理
  Editor,                   // 内联编辑器
  FormulaEngine,            // 公式引擎
  Parser, parseFormula, tokenize,  // 公式解析
  DependencyGraph,          // 公式依赖图
  builtinFunctions,         // 内置函数（SUM/AVERAGE 等）
  FormulaError              // 公式错误类型
} from '@evansun/excel-designer'

API 文档

SpreadsheetCanvas 组件

Props

Emits

暴露方法（defineExpose）

Toolbar 组件

Props

cellStyle 默认值：

{
  fontFamily: 'Arial',
  fontSize: 11,
  bold: false,
  italic: false,
  underline: false,
  strikethrough: false,
  align: 'left',       // 'left' | 'center' | 'right'
  valign: 'middle',    // 'top' | 'middle' | 'bottom'
  fg: '#333333',
  bg: '#ffffff'
}

Emits

Spreadsheet 引擎 API

序列化数据格式

exportJSON() 返回 / loadJSON(json) 接收的完整数据结构：

{
  "name": "Sheet1",
  "rowOrder": ["r1", "r2", "r3"],
  "colOrder": ["c1", "c2", "c3"],
  "rows": [
    {
      "id": "r1",
      "parentId": null,
      "height": 24,
      "collapsed": false,
      "zoneId": null,
      "cells": [
        {
          "colId": "c1",
          "value": "单项工程费汇总表",
          "rawInput": "单项工程费汇总表",
          "formula": null,
          "style": {
            "fontFamily": "Arial",
            "fontSize": 14,
            "bold": true,
            "italic": false,
            "underline": false,
            "strikethrough": false,
            "align": "center",
            "valign": "middle",
            "fg": "#333333",
            "bg": "#ffffff"
          }
        }
      ]
    },
    {
      "id": "r2",
      "parentId": "r1",
      "height": 24,
      "collapsed": false,
      "zoneId": null,
      "cells": []
    }
  ],
  "cols": [
    { "id": "c1", "width": 100 },
    { "id": "c2", "width": 100 },
    { "id": "c3", "width": 100 }
  ],
  "merges": [
    { "startRowId": "r1", "startColId": "c1", "endRowId": "r1", "endColId": "c3" }
  ]
}

字段说明：

样式字段：

键盘快捷键

鼠标交互

开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建应用（演示页）
npm run build

# 构建库产物（发布用）
npm run build:lib

构建产物

dist/
  excel-designer.es.js   # ES Module
  excel-designer.umd.js   # UMD
  style.css               # 组件样式

发布

# 1. 确保已构建
npm run build:lib

# 2. 登录 npm
npm login

# 3. 发布（scoped 包需指定公开访问）
npm publish --access public

常见问题

如何从后端加载数据？

// 1. 从后端获取数据
const res = await fetch('/api/sheet/123')
const sheetData = await res.json()

// 2. 传入组件
// 方式一：通过 prop
<SpreadsheetCanvas :sheet-data="sheetData" />

// 方式二：通过引擎实例
const engine = canvasRef.value.getInstance()
engine.loadJSON(sheetData)

如何保存到后端？

<SpreadsheetCanvas
  :show-save="true"
  :extra-data="{ projectId: 'p001', sheetId: 's001' }"
  @save="handleSave"
/>

async function handleSave(payload) {
  // payload = { version, savedAt, workbook, projectId, sheetId }
  await fetch('/api/sheet/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  })
}

如何自定义工具栏？

不使用内置 Toolbar，自行构建：

<template>
  <div>
    <!-- 你的自定义工具栏 -->
    <MyToolbar @bold="onBold" @merge="onMerge" />
    <!-- 只保留画布，不显示内置操作栏 -->
    <SpreadsheetCanvas ref="canvasRef" :show-toolbar="false" @ready="onReady" />
  </div>
</template>

<script setup>
const canvasRef = ref()
let engine = null

function onReady(api) { engine = api }
function onBold() {
  engine.applyStyle({ bold: !engine.getActiveStyle().bold })
}
function onMerge() {
  engine.toggleMerge()
}
</script>

如何动态修改单元格？

const engine = canvasRef.value.getInstance()

// 设置值
engine.setCell('r1', 'c1', 'Hello World')

// 设置公式
engine.insertFormulaAt('r7', 'c3', '=SUM(C4:C6)')

// 设置样式
engine.applyStyle({ bold: true, align: 'center', fg: '#ff0000' })

// 设置行高/列宽
engine.setRowHeight('r1', 40)
engine.setColWidth('c1', 150)

// 插入行/列
engine.insertRow(null, 'r1', 24)      // 在 r1 后插入行
engine.insertCol('c1', 'after', 100)  // 在 c1 右侧插入列

如何监听单元格变化？

engine.on('cell-change', (data) => {
  // data = { rowId, colId, value, oldValue }
  console.log(`单元格 ${data.rowId}|${data.colId} 改为 ${data.value}`)
})

License

MIT