开源表格 LuckySheet 使用指引针对开源的、基于客户端渲染的在线表格-Luckysheet，基于Vue项目，进

下述内容基于 Vue2 展开，请注意

LuckySheet 是一个基于前端渲染的 Excel编辑器，完全开源，无需付费

其仅支持 xlsx 格式，且已不再维护，因而在使用时需注意防坑🕳

附录：

基础配置及使用

资源引入

无法通过 node_modules 依赖形式引入

GitHub中查询到的 luckysheet-vue，是其针对 Vue-2 的测试项目

使用CDN

于 public/index.html 文件中，引入下述资源

<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/plugins/css/pluginsCss.css' />
<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/plugins/plugins.css' />
<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/css/luckysheet.css' />
<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/assets/iconfont/iconfont.css' />
<script src="https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/plugins/js/plugin.js"></script>
<script src="https://cdn.jsdelivr.net/npm/luckysheet@latest/dist/luckysheet.umd.js"></script>

若需引入指定版本资源，可将上述 @lastest 调整为对应版本号（例如 @2.13.1，历史版本可查询 npm-luckysheet）

借用外部CDN，存在 资源失效 风险，需注意。可将相关资源下载，由内部服务器做托管操作

本地引入

获取

借助 NPM

下载打包内容，其下 dist 文件夹即为所需内容

⭐ 在下步“引入”完成后，记得卸载该打包内容
借助 GitHub

下载源码，先后运行 npm i、npm run build；项目下 dist 文件夹即为所需内容

引入

将上述获取的资源，放置到项目 public/luckysheet 目录下（其中 index.html 为多余文件）

于 public/index.html 文件中，引入下述资源

<link rel="stylesheet" href="/luckysheet/plugins/css/pluginsCss.css" />
<link rel="stylesheet" href="/luckysheet/plugins/plugins.css" />
<link rel="stylesheet" href="/luckysheet/css/luckysheet.css" />
<link rel="stylesheet" href="/luckysheet/assets/iconfont/iconfont.css" />
<script src="/luckysheet/plugins/js/plugin.js"></script>
<script src="/luckysheet/luckysheet.umd.js"></script>

简单使用

设置容器

<div id="luckysheet" style="width: 100vh; height: 100vw;" />

创建表格

window.luckysheet.create({
  container: 'luckysheet'
})

效果如下：

整体配置

基础配置项

详见整体配置-配置项

container: 'luckysheet', // 容器ID
title: 'LuckySheet 标题', // 标题内容
lang: 'zh', // 强制设置为中文
allowEdit: this.editable, // 支持编辑
showinfobar: false, // 显示顶部信息（含 luckysheet图标、文件标题 等）
/* 工具栏配置 */
showtoolbar: false, // 显示工具栏
  showtoolbarConfig: {
  postil: false, // 支持批注
  mergeCell: false, // 支持合并单元格（luckysheet无法监听合并操作）
},
// sheet 页
showsheetbar: false, // 显示sheet页
showsheetbarConfig: {
  menu: false, // sheet 管理菜单
  add: false, // sheet 新增
},
sheetRightClickConfig: { // 工作表鼠标右击选项
  delete: false,
  copy: false,
  hide: false,
  move: false,
},
enableAddBackTop: true, // 支持回到顶部（操作按钮位于底部）

监听函数

下方仅展示常用hook，详见整体配置-钩子函数、GitHub示例

hook: {
  cellMousedown: (cell, position, sheet, ctx) => {
    /*
     * 参数信息备注
     * - cell.v 原始值 cell.m 显示值 cell.ct.s 备份值
     * - position.c 列索引 position.r 行索引
     * - cell.mc.cs 跨列数 cell.mc.rs 跨行数
     */
    this.$emit('cellMousedown', cell, position, sheet, ctx)
  },
  rangeSelect: (sheet, range) => {
    this.$emit('rangeSelect', sheet, range)
  },
  cellUpdated: (r, c, oldVal, newVal, isRefresh) => {
    /*
     * 参数信息备注
     * - r 行索引 c 列索引
     */
    this.$emit('cellUpdated', r, c, oldVal, newVal, isRefresh)
  },
  sheetActivate: (index, isPivotInitial, isNewSheet) => {
    /*
     * 参数信息备注
     * - index sheet索引 isPivotInitial 是否是透视表 isNewSheet 是否是新建sheet
     *
     * 可通过 luckysheet.getSheet 方法获取当前sheet信息
     * - index、order区别：https://dream-num.github.io/LuckysheetDocs/zh/guide/FAQ.html#%E6%AF%8F%E4%B8%AAsheet%E9%A1%B5%E7%9A%84index%E5%92%8Corder%E6%9C%89%E4%BB%80%E4%B9%88%E5%8C%BA%E5%88%AB
     */
    this.$emit('sheetActivate', index, isPivotInitial, isNewSheet)
  },
  cellAllRenderBefore: (data, sheet, ctx) => {
    // 重置渲染次数
    this.cellRenderedTimes = 0
     /*
      渲染失败的情况下，cellAllRenderBefore 仍触发，而 cellRenderAfter 不触发
      正常渲染情况下，cellAllRenderBefore 与 首次cellRenderAfter 触发事件间隔在 几毫秒
     */
    setTimeout(() => {
      if (this.cellRenderedTimes === 0) {
        console.error('渲染失败，请注意控制台提示信息')
        // 销毁 luckysheet
        window.luckysheet.destroy()
      }
    }, 500)

    this.$emit('cellAllRenderBefore', data, sheet, ctx)
  },
  cellRenderAfter: (cell, position, sheetFile, ctx) => {
    this.$emit('cellRenderAfter', cell, position, sheetFile, ctx)
    // 累加渲染次数
    this.cellRenderedTimes++
  },
  workbookCreateAfter: (options) => {
    this.$emit('workbookCreateAfter', options)
  },
},

监听函数存在的问题：

cellUpdated 无法监听到快速填充内容变化
cellUpdated 无法监听到拷贝内容变化

常用方法

单元格查询-find

可用于在 当前工作表 下查询字符串（window.luckysheet.find('value')）、查询公式（window.luckysheet.find('SUM', { type: 'f' })）
单元格获取-getCellValue

可用于查询某个单元格的值

例如：查询当前工作表的A1单元格内容 window.luckysheet.getCellValue(0, 0)

可选参数 setting 可用于配置返回值类型、查询工作表
单元格设置-setCellValue

可用于设置某个单元格的值，设定值支持类型{String|Number|Object}

例如：将当前工作表的A1单元格内容调整为Hello window.luckysheet.setCellValue(0, 0, 'Hello')

可选参数 setting 可用于配置工作表下标、是否刷新页面、操作结束回调函数

⭐注意，短时间内填充多个单元格时，应设置 setting.isRefresh 起到节流作用，避免页面卡顿
工作表切换-setSheetActive

可用于激活指定下标的工作表，即切换至指定的工作表

例如：切换至第2个工作表 window.luckysheet.setSheetActive(1)
工作表集合获取-getAllSheets

用于获取全部工作表配置集合，其可用于 luckysheet初始化时作为 options.data

公式强制刷新-refreshFormula

当你使用内部方法直接调整多个单元格的值，出现公式计算值并未更新，可尝试使用此 API 强制触发公式刷新

内容滚动-scroll

通过配置 targetRow、targetColumn 等参数，可以滚动到 当前工作表 的指定位置

行高获取-getRowHeight

可获取 指定工作表 指定行的高度

例如：获取第1行、第3行高度 window.luckysheet.getRowHeight([0, 2])

若想获取当前工作表的各行 scrollTop + offsetHeight 信息（下方称为 scrollBottom），可借助下方代码段：

  // 获取当前工作表信息
  const sheet = window.luckysheet.getSheet()
  // 获取 scrollBottom 集合信息
  const scrollBottomSet = sheet.visibledatarow
  // 获取 第2行 的scrollBottom
  const row = 2
  console.log(scrollTopSet[row - 1]) // 行号以 0 作为起始

文件解析（导入）

资源引入

通过运行 npm i luckyexcel 安装 npm依赖

于使用处，通过 import luckyexcel from 'luckyexcel' 引入

方法介绍

transformExcelToLucky

可将 File文件对象转化为 exportJson 对象，对象内部含有渲染所需的 sheets

luckyexcel.transformExcelToLucky(file, (exportJson) => {
  const { sheets } = exportJson;
  if (sheets?.length) {
    console.error('无法读取该文件内容');
    return
  }

  window.luckysheet.destroy();
  window.luckysheet.create({
    ...this.config, // luckysheet配置项，详见上方“整体配置”
    data: sheets,
  });
})

transformExcelToLuckyByUrl

可将 URL地址转化为 exportJson 对象，对象内部同样含有渲染所需的 sheets
```
luckyexcel.transformExcelToLuckyByUrl(url, (exportJson) => {
  // 内部逻辑同上
  xxx
})
```

文件导出

⭐注意：下述介绍的导出方法，无法确保样式保留

资源引入

运行 npm i exceljs、npm i filesaver 安装相关依赖

于使用处，通过👇方式引入

const ExcelJs = require('exceljs');
const FileSaver = require('filesaver')

前置方法

用于设置合并、边框、样式、内容、填充、字体、对齐方式等

参考来源：官方导入、导出案例

function setMerge(luckyMerge = {}, worksheet) {
  const mergeArr = Object.values(luckyMerge)
  mergeArr.forEach((elem) => {
    // elem格式：{ r: 0, c: 0, rs: 1, cs: 2 }
    const { r, c, rs, cs } = elem
    // 按开始行，开始列，结束行，结束列合并（相当于 K10:M12）
    worksheet.mergeCells(r + 1, c + 1, r + rs, c + cs)
  })
}

function setBorder(luckyBorderInfo, worksheet) {
  if (!Array.isArray(luckyBorderInfo)) return

  luckyBorderInfo.forEach((elem) => {
    const { rangeType, borderType, style, color, range, value } = elem

    // 现在只兼容到 borderType 为 range 的情况
    if (rangeType === 'range') {
      const border = borderConvert(borderType, style, color)
      const { row, column } = range[0]

      for (let i = row[0] + 1; i < row[1] + 2; i++) {
        for (let y = column[0] + 1; y < column[1] + 2; y++) {
          worksheet.getCell(i, y).border = border
        }
      }
    } else if (rangeType === 'cell') {
      const { col_index, row_index } = value
      const borderData = Object.assign({}, value)
      delete borderData.col_index
      delete borderData.row_index

      worksheet.getCell(row_index + 1, col_index + 1).border
        = addborderToCell(borderData, row_index, col_index)
    }
  })
}

function setStyleAndValue(cellArr, worksheet) {
  if (!Array.isArray(cellArr)) return

  cellArr.forEach((row, rowIndex) => {

    row.every((cell, columnid) => {
      if (!cell) return true

      const { f, v, ct, bg, ff, fc, bl, it, fs, cl, ul, vt, ht, tb, tr } = cell
      let fill = fillConvert(bg)
      let font = fontConvert(ff, fc, bl, it, fs, cl, ul)
      let alignment = alignmentConvert(vt, ht, tb, tr)

      let value = ''
      if (cell.f) {
        value = { formula: f, result: v }
      } else if (!v && ct?.s) {
        // xls转为xlsx之后，内部存在不同的格式，都会进到富文本里，即值不存在与cell.v，而是存在于cell.ct.s之后
        ct.s.forEach(item => { value += item.v })
      } else {
        value = v
      }

      //  style 填入到_value中可以实现填充色
      let columnStr = getColumnStr(columnid)
      let target = worksheet.getCell(`${columnStr}${rowIndex + 1}`)
      for (const key in fill) {
        target.fill = fill
        break
      }
      Object.assign(target, {
        font,
        alignment,
        value,
      })

      return true
    })
  })
}

function fillConvert(bg) {
  if (!bg) return {}

  return {
    type: 'pattern',
    pattern: 'solid',
    fgColor: { argb: bg.replace('#', '') }
  }
}

function fontConvert(
  ff = 0,
  fc = '#000000',
  bl = 0,
  it = 0,
  fs = 10,
  cl = 0,
  ul = 0
) {
  // luckysheet：ff(样式), fc(颜色), bl(粗体), it(斜体), fs(大小), cl(删除线), ul(下划线)
  const luckyToExcel = {
    0: '微软雅黑',
    1: '宋体（Song）',
    2: '黑体（ST Heiti）',
    3: '楷体（ST Kaiti）',
    4: '仿宋（ST FangSong）',
    5: '新宋体（ST Song）',
    6: '华文新魏',
    7: '华文行楷',
    8: '华文隶书',
    9: 'Arial',
    10: 'Times New Roman ',
    11: 'Tahoma ',
    12: 'Verdana',
    num2bl: (num) => {
      return num === 0 ? false : true
    }
  }
  // 出现Bug，导入的时候ff为luckyToExcel的val

  return {
    family: 1,
    name: typeof ff === 'number' ? luckyToExcel[ff] : ff,
    color: { argb: fc.replace('#', '') },
    bold: luckyToExcel.num2bl(bl),
    italic: luckyToExcel.num2bl(it),
    size: fs,
    strike: luckyToExcel.num2bl(cl),
    underline: luckyToExcel.num2bl(ul),
  }
}

function alignmentConvert(
  vt = 'default',
  ht = 'default',
  tb = 'default',
  tr = 'default'
) {
  // luckysheet:vt(垂直), ht(水平), tb(换行), tr(旋转)
  const luckyToExcel = {
    vertical: {
      0: 'middle',
      1: 'top',
      2: 'bottom',
      default: 'top'
    },
    horizontal: {
      0: 'center',
      1: 'left',
      2: 'right',
      default: 'left'
    },
    wrapText: {
      0: false,
      1: false,
      2: true,
      default: false
    },
    textRotation: {
      0: 0,
      1: 45,
      2: -45,
      3: 'vertical',
      4: 90,
      5: -90,
      default: 0
    }
  }

  return {
    vertical: luckyToExcel.vertical[vt],
    horizontal: luckyToExcel.horizontal[ht],
    wrapText: luckyToExcel.wrapText[tb],
    textRotation: luckyToExcel.textRotation[tr]
  }
}

function borderConvert(borderType, style = 1, color = '#000') {
  // 对应 luckysheet 的 config 中 borderinfo 的的参数
  if (!borderType) return {}

  const luckyToExcel = {
    type: {
      'border-all': 'all',
      'border-top': 'top',
      'border-right': 'right',
      'border-bottom': 'bottom',
      'border-left': 'left'
    },
    style: {
      0: 'none',
      1: 'thin',
      2: 'hair',
      3: 'dotted',
      4: 'dashDot', // 'Dashed',
      5: 'dashDot',
      6: 'dashDotDot',
      7: 'double',
      8: 'medium',
      9: 'mediumDashed',
      10: 'mediumDashDot',
      11: 'mediumDashDotDot',
      12: 'slantDashDot',
      13: 'thick'
    }
  }
  let template = {
    style: luckyToExcel.style[style],
    color: { argb: color.replace('#', '') }
  }

  let border = {}
  if (luckyToExcel.type[borderType] === 'all') {
    border['top'] = template
    border['right'] = template
    border['bottom'] = template
    border['left'] = template
  } else {
    border[luckyToExcel.type[borderType]] = template
  }

  return border
}

function addborderToCell(borders, row_index, col_index) {
  const luckyExcel = {
    type: {
      l: 'left',
      r: 'right',
      b: 'bottom',
      t: 'top'
    },
    style: {
      0: 'none',
      1: 'thin',
      2: 'hair',
      3: 'dotted',
      4: 'dashDot', // 'Dashed',
      5: 'dashDot',
      6: 'dashDotDot',
      7: 'double',
      8: 'medium',
      9: 'mediumDashed',
      10: 'mediumDashDot',
      11: 'mediumDashDotDot',
      12: 'slantDashDot',
      13: 'thick'
    }
  }

  return Object.keys(borders).reduce((result, key) => {
    let { color, style } = borders[key]
    // 去除十六进制颜色前置符号
    color.indexOf('rgb') === -1
      && (color = color.replace('#', ''))

    result[luckyExcel.type[key]] = {
      style: luckyExcel.style[style],
      color: { argb: color }
    }

    return result
  }, {})
}

function getColumnStr(n) {
  let ordA = 'A'.charCodeAt()
  let len = 26

  let column = ''
  while (n >= 0) {
    column = String.fromCharCode((n % len) + ordA) + column
    n = Math.floor(n / len) - 1
  }

  return column
}

导出方法

function excelExport(luckysheet, fileName) {
  // 1. 创建工作簿，可以为工作簿添加属性
  const workbook = new ExcelJS.Workbook()
  // 2. 创建表格，第二个参数可以配置创建什么样的工作表
  if (Object.prototype.toString.call(luckysheet) === '[object Object]') {
    luckysheet = [luckysheet]
  }

  luckysheet.forEach((table) => {
    if (table.data.length === 0) return true

    // ws.getCell('B2').fill = fills.
    const worksheet = workbook.addWorksheet(table.name)
    const merge = (table.config && table.config.merge) || {}
    const borderInfo = (table.config && table.config.borderInfo) || {}
    // 3. 设置 单元格样式和值、单元格合并、单元格边框
    setStyleAndValue(table.data, worksheet)
    setMerge(merge, worksheet)
    setBorder(borderInfo, worksheet)

    return true
  })

  // 4. 写入 buffer
  const buffer = workbook.xlsx.writeBuffer().then(data => {
    const blob = new Blob([data], {
      type: 'application/vnd.ms-excel;charset=utf-8'
    })
    // FileSaver.saveAs(blob, `${fileName}.xlsx`)
    window.saveAs(blob, `${fileName}.xlsx`)
  })

  return buffer
}

excelExport 两个参数分别为工作表信息集合、导出文件名称

通过下方代码，即可实现内容导出

async handleExport() {
  await excelExport(window.luckysheet.getAllSheets(), '导出名称')
  console.log('导出成功，请查收')
}

特殊情况处理

初始化时，公式计算值错误

结合官网常见问题、GitHub讨论分析得出：

luckysheet初始化过程中，每个sheet对象中 calcChain 均为空数组，需我们人为进行赋值操作

那么，需要在哪个时机进行赋值操作呢？

Luckysheet 的 cellAllRenderBefore 监听函数，便能满足我们获取相关数据，并调整 sheet.calcChain 的需求

hook: {
  cellAllRenderBefore: (data, sheet, ctx) => {
    const calcChain = []
    data.forEach((rowData, rowIndex) => {
      rowData.forEach((cellData, columnIndex) => {
        const { f, v } = cellData ?? {}
        // 判断单元格内容是否为公式
        if (f) {
          calcChain.push({
            r: rowIndex,
            c: columnIndex,
            index: sheet.index,
            func: [true, v, f],
            color: 'w',
            parent: null,
            children: {},
            times: 0,
          })
        }
      })
    })

    if (calcChain.length) {
      sheet.calcChain = calcChain

      setTimeout(() => {
        // 强制刷新公式
        window.luckysheet.refreshFormula()
      })
    }
  }
}

⭐注意：切换工作表、拖动滚动条等操作，均会触发 cellAllRenderBefore，需根据实际需求进行节流处理

渲染失败，持续显示“渲染中”

Luckysheet 可能会因字体等原因，出现渲染失败的情况

受限于其未向外抛出错误❌，因而不能通过常规的 try...catch 方式捕获，进行异常处理

在连续的测试当中，偶尔发现一个有趣的现象：

渲染成功时，Luckysheet 会先后触发 cellAllRenderBefore、cellRenderAfter，且触发时间间隔不超过 50ms
渲染失败时，Luckysheet 仅会触发 cellAllRenderBefore，而不会触发 cellRenderAfter

利用上面的特性，可间接判断是否出现 渲染失败

hook: {
  cellAllRenderBefore: () => {
    // 重置渲染次数
    this.cellRenderedTimes = 0

    setTimeout(() => {
      if (this.cellRenderedTimes === 0) {
        console.error('渲染失败，请注意控制台提示信息')
        // 销毁 luckysheet
        window.luckysheet.destroy()
      }
    }, 500)  // 延迟时间间隔大于 50ms 即可
  },
  cellRenderAfter: () => {
    // 累加渲染次数
    this.cellRenderedTimes++
  },
}

cellUpdated 可监听操作范围有限

上述内容曾提及到，cellUpdated 无法监听粘贴、下拉填充、快速删除等操作

借助官方文档，查询到另外的监听函数 updated；虽然官方描述其作用是监听协作变更，但仍能提供帮助

不过需要注意的是，其存在下方问题：

无法监听未启用页面刷新的变更

例如：window.luckysheet.setCellValue(1, 1, '测试', { isRefresh: false })
下拉填充时，模板数据也会被当作 变更内容

兼并二者，便可针对较大范围操作，实现监听操作，示例见下方代码段：

cellUpdated: (r, c, oldVal, newVal, isRefresh) => {
  // 外抛原始监听操作
  this.$emit('cellUpdated', r, c, oldVal, newVal, isRefresh)

  // 自定义监听函数，与 updated 配合
  !isRefresh && this.$emit('cellUpdatedCustom', [{ r, c, newVal }])
},
updated: (operate) => {
  // 外抛原始监听操作
  this.$emit('updated', operate)

  // 自定义监听函数，与 cellUpdated 配合
  const { range, curdata } = operate
  const {
    row: [startRow, endRow],
    column: [startColumn, endColumn],
  } = range[0]

  const updatedList = []
  for (let r = startRow; r <= endRow; r++) {
    for (let c = startColumn; c <= endColumn; c++) {
      const cell = curdata[r][c]
      updatedList.push({ r, c, newVal: cell })
    }
  }

  this.$emit('cellUpdatedCustom', updatedList)
},