Excel 表格包

@cat-kit/excel 面向浏览器环境，提供不可变的工作簿模型、流式读写与地址/日期等辅助工具，适合构建在线报表、导入导出与大文件处理。

主要特性：

• 不可变 Cell / Row / Worksheet / Workbook 数据结构，易于链式操作与快照管理
• 保真读写单元格样式、列宽与合并单元格，日期格式自动识别
• readWorkbook、readWorkbookStream 支持完整解析与行级流式解析
• StreamWorkbookWriter 流式写入，降低大数据量下的内存峰值
• 地址、日期格式转换工具，以及支持读/写的 Web Worker 客户端

安装

npm

npm install @cat-kit/excel

bun

bun add @cat-kit/excel

pnpm

pnpm add @cat-kit/excel

快速开始

import { Workbook, Worksheet } from '@cat-kit/excel'

// 通过表格数据快速生成工作表
const sheet = new Worksheet('销售报表', {
  table: {
    columns: [
      { name: '产品', key: 'product', width: 120 },
      { name: '区域', key: 'region', width: 100, align: 'center' },
      { name: '销量', key: 'sales', format: '#,##0' },
      { name: '日期', key: 'date' }
    ],
    data: [
      { product: '路由器', region: '华北', sales: 1880, date: new Date() },
      { product: '交换机', region: '华东', sales: 920, date: new Date() }
    ],
    headerStyle: { font: { bold: true }, fill: { fgColor: '#eef2ff', patternType: 'solid' } },
    dataStyle: { alignment: { horizontal: 'center' } }
  }
})

// 组合为工作簿并导出
const workbook = new Workbook('月度报表', { sheets: [sheet] })
const blob = await workbook.write()
// 浏览器中触发下载
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = 'report.xlsx'
a.click()
URL.revokeObjectURL(url)

核心对象

单元格与行

import { Cell, Row } from '@cat-kit/excel'

// 带样式的单元格
const price = new Cell(1999, {
  font: { bold: true, color: '#2563eb' },
  numberFormat: '#,##0'
})

// 设置行高与行级样式
const row = new Row(['商品', '价格', '状态'], { height: 24 })
  .withStyle({ alignment: { horizontal: 'center', vertical: 'middle' } })
  .withCell(2, new Cell('已上架', { fill: { fgColor: '#ecfeff', patternType: 'solid' } }))

工作表

import { Worksheet, Row, Cell } from '@cat-kit/excel'

const sheet = new Worksheet('库存', {
  rows: [
    ['SKU', '名称', '库存'],
    ['A-001', '电源适配器', 320],
    ['A-002', '键盘', 120]
  ]
})
  // 插入汇总行
  .insertRow(1, new Row(['总计', null, 440], { height: 20 }))
  // 批量更新单元格样式
  .setCellStyles('A1:C1', {
    font: { bold: true },
    fill: { fgColor: '#f5f5f5', patternType: 'solid' }
  })
  // 单元格按地址更新
  .updateCell('C3', new Cell(200, { numberFormat: '#,##0' }))

工作簿

import { Workbook } from '@cat-kit/excel'

const book = new Workbook('仓储', {
  sheets: [sheetA, sheetB],
  metadata: { creator: 'Cat Kit', created: new Date() }
})
  .addSheet(sheetC)
  .withName('仓储报表')
  .withMetadata({ customProperties: { env: 'prod' } })

读取 Excel 文件

import { readWorkbook } from '@cat-kit/excel'

const workbook = await readWorkbook(file)
const firstSheet = workbook.getSheet(0)
const firstValue = firstSheet?.getCell('A1')?.value

流式读取大文件

import { readWorkbookStream } from '@cat-kit/excel'

const stream = readWorkbookStream(file, {
  sheetIndices: [0], // 只读首个工作表
  batchSize: 1000
})

const reader = stream.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log(value.sheetName, value.rowIndex, value.row.getValues())
}

⚠️ 流式模式在解析时按工作表逐步解压并按 <row> 片段增量产出，batchSize 控制解析过程的让步频率，可减少主线程占用；处理超大文件时仍需确保可容纳单个工作表的 XML 数据。

流式写入

import { StreamWorkbookWriter } from '@cat-kit/excel'

const writer = new StreamWorkbookWriter({ workbookName: '导出报表' })
writer.addSheet(summarySheet)
writer.addSheet(detailSheet)

const blob = await writer.write()

Worker 支持

import { ExcelWorkerClient } from '@cat-kit/excel'

const client = new ExcelWorkerClient(new URL('./excel.worker', import.meta.url))
const workbook = await client.readWorkbook(file)

// 在 Worker 中完成写入（可传 Workbook 实例或可序列化的 plain object）
const blob = await client.writeWorkbook({
  name: '报表',
  sheets: [
    { name: 'Sheet1', rows: [['A1', 'B1'], ['A2', 'B2']] }
  ]
})

// 处理完毕后主动释放
client.terminate()

地址与日期工具

import {
  parseAddress,
  formatRange,
  excelNumberToDate,
  dateToExcelNumber
} from '@cat-kit/excel'

parseAddress('B2') // { row: 1, column: 1 }
formatRange({ start: { row: 0, column: 0 }, end: { row: 1, column: 2 } }) // 'A1:C2'
excelNumberToDate(45567) // Date
dateToExcelNumber(new Date()) // number

示例

• 导出一份带汇总行与样式的销售报表，并触发浏览器下载：

vue

使用 Worksheet.table 自动生成表头与样式

产品	区域	销量	日期
路由器	华北	1,880	2024-11-05
交换机	华东	920	2024-11-06
Wi-Fi 6 AP	华南	1,350	2024-11-07

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173

<template>
  <div class="excel-card">
    <div class="excel-card__actions">
      <var-button type="primary" :loading="downloading" @click="downloadReport">
        生成并下载报表
      </var-button>
      <span class="excel-card__hint">使用 Worksheet.table 自动生成表头与样式</span>
    </div>

    <table class="excel-preview">
      <thead>
        <tr>
          <th v-for="column in columns" :key="column.key">{{ column.name }}</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="(item, index) in sampleData" :key="index">
          <td>{{ item.product }}</td>
          <td>{{ item.region }}</td>
          <td class="number-cell">{{ item.sales.toLocaleString() }}</td>
          <td>{{ formatDate(item.date) }}</td>
        </tr>
      </tbody>
    </table>

    <p class="excel-card__meta" v-if="lastDownloaded">
      最近下载于：{{ lastDownloaded }}
    </p>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { Workbook, Worksheet, Row, Cell } from '@cat-kit/excel'

interface SalesItem {
  product: string
  region: string
  sales: number
  date: Date
}

const columns = [
  { name: '产品', key: 'product', width: 120 },
  { name: '区域', key: 'region', width: 100, align: 'center' },
  { name: '销量', key: 'sales', format: '#,##0' },
  { name: '日期', key: 'date' }
] as const

const sampleData: SalesItem[] = [
  { product: '路由器', region: '华北', sales: 1880, date: new Date('2024-11-05') },
  { product: '交换机', region: '华东', sales: 920, date: new Date('2024-11-06') },
  { product: 'Wi-Fi 6 AP', region: '华南', sales: 1350, date: new Date('2024-11-07') }
]

const downloading = ref(false)
const lastDownloaded = ref<string | null>(null)
const totalSales = computed(() => sampleData.reduce((sum, item) => sum + item.sales, 0))

function formatDate(value: Date) {
  return value.toISOString().slice(0, 10)
}

async function downloadReport() {
  downloading.value = true
  try {
    const sheet = new Worksheet('销售明细', {
      table: {
        columns: columns.map(col => ({
          ...col,
          // 给数字列增加右对齐
          align: col.key === 'sales' ? 'right' : col.align
        })),
        data: sampleData,
        headerStyle: {
          font: { bold: true },
          fill: { fgColor: '#eef2ff', patternType: 'solid' }
        },
        dataStyle: { alignment: { vertical: 'middle' } }
      },
      mergedCells: [{ start: { row: 0, column: 0 }, end: { row: 0, column: 1 } }]
    })

    // 插入一行汇总数据
    const summaryRow = new Row(
      [
        new Cell('本月合计', {
          font: { bold: true },
          fill: { fgColor: '#fef3c7', patternType: 'solid' }
        }),
        new Cell(null),
        new Cell(totalSales.value, {
          numberFormat: '#,##0',
          font: { bold: true, color: '#1f2937' }
        }),
        new Cell(new Date(), { numberFormat: 'yyyy-mm-dd' })
      ],
      { height: 22 }
    )

    const sheetWithSummary = sheet.insertRow(1, summaryRow)

    const workbook = new Workbook('销售报表', {
      sheets: [sheetWithSummary],
      metadata: { creator: 'Cat Kit 示例', created: new Date() }
    })

    const blob = await workbook.write()
    const url = URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.href = url
    a.download = `sales-report-${Date.now()}.xlsx`
    a.click()
    URL.revokeObjectURL(url)

    lastDownloaded.value = new Date().toLocaleTimeString()
  } finally {
    downloading.value = false
  }
}
</script>

<style scoped>
.excel-card {
  background: var(--vt-c-bg-soft);
  border: 1px solid var(--vt-c-divider);
  border-radius: 12px;
  padding: 16px;
}

.excel-card__actions {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.excel-card__hint {
  color: var(--vt-c-text-2);
  font-size: 14px;
}

.excel-card__meta {
  margin-top: 12px;
  color: var(--vt-c-text-2);
  font-size: 13px;
}

.excel-preview {
  width: 100%;
  border-collapse: collapse;
  font-size: 14px;
  background: var(--vt-c-bg);
  border: 1px solid var(--vt-c-divider);
}

.excel-preview th,
.excel-preview td {
  padding: 10px;
  border: 1px solid var(--vt-c-divider);
  text-align: left;
}

.excel-preview thead {
  background: #eef2ff;
}

.number-cell {
  text-align: right;
  font-variant-numeric: tabular-nums;
}
</style>

• 选择本地 .xlsx 文件，流式读取首个工作表并展示前几行：

vue

选择 .xlsx 文件，使用 readWorkbookStream 逐行解析（示例仅读取首个工作表）。

暂未读取数据，上传文件后展示前几行预览。

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158

<template>
  <div class="excel-card">
    <p class="excel-card__hint">
      选择 .xlsx 文件，使用 <code>readWorkbookStream</code> 逐行解析（示例仅读取首个工作表）。
    </p>

    <div class="excel-card__actions">
      <input ref="fileInput" class="file-input" type="file" accept=".xlsx" @change="handleFile" />
      <var-button type="primary" :loading="reading" @click="triggerFile">选择文件</var-button>
      <span v-if="summary" class="excel-card__summary">{{ summary }}</span>
    </div>

    <div v-if="rows.length" class="stream-list">
      <div v-for="item in rows" :key="item.id" class="stream-list__item">
        <div class="stream-list__title">{{ item.sheet }} · 第 {{ item.row }} 行</div>
        <div class="stream-list__cells">{{ item.cells }}</div>
      </div>
    </div>

    <p v-else class="placeholder">暂未读取数据，上传文件后展示前几行预览。</p>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { readWorkbookStream } from '@cat-kit/excel'

interface PreviewRow {
  id: string
  sheet: string
  row: number
  cells: string
}

const MAX_PREVIEW = 12

const rows = ref<PreviewRow[]>([])
const summary = ref('')
const reading = ref(false)
const fileInput = ref<HTMLInputElement | null>(null)

function triggerFile() {
  fileInput.value?.click()
}

function formatCells(values: any[]) {
  return values
    .slice(0, 6)
    .map(value => {
      if (value instanceof Date) return value.toISOString().slice(0, 10)
      if (value && typeof value === 'object' && 'type' in value) {
        return value.type === 'formula' ? `=${value.formula}` : value.error || ''
      }
      return value ?? ''
    })
    .join(' | ')
}

async function handleFile(event: Event) {
  const input = event.target as HTMLInputElement
  const file = input.files?.[0]
  if (!file) return

  rows.value = []
  summary.value = ''
  reading.value = true

  try {
    const stream = readWorkbookStream(file, { sheetIndices: [0] })
    const reader = stream.getReader()

    let total = 0
    while (true) {
      const { done, value } = await reader.read()
      if (done) break

      total++
      if (rows.value.length < MAX_PREVIEW) {
        rows.value.push({
          id: `${value.sheetIndex}-${value.rowIndex}`,
          sheet: value.sheetName,
          row: value.rowIndex + 1,
          cells: formatCells(value.row.getValues())
        })
      }
    }

    summary.value = `已流式读取 ${total} 行，展示前 ${rows.value.length} 行`
  } catch (error: any) {
    summary.value = error?.message || String(error)
  } finally {
    reading.value = false
    input.value = ''
  }
}
</script>

<style scoped>
.excel-card {
  background: var(--vt-c-bg-soft);
  border: 1px solid var(--vt-c-divider);
  border-radius: 12px;
  padding: 16px;
}

.excel-card__hint {
  margin: 0 0 10px;
  color: var(--vt-c-text-2);
  font-size: 14px;
}

.excel-card__actions {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
  margin-bottom: 12px;
}

.excel-card__summary {
  color: var(--vt-c-text-2);
  font-size: 13px;
}

.file-input {
  display: none;
}

.stream-list {
  display: grid;
  gap: 8px;
}

.stream-list__item {
  padding: 10px 12px;
  border: 1px solid var(--vt-c-divider);
  border-radius: 10px;
  background: var(--vt-c-bg);
}

.stream-list__title {
  font-weight: 600;
  margin-bottom: 6px;
}

.stream-list__cells {
  color: var(--vt-c-text-2);
  font-family: ui-monospace, SFMono-Regular, SFMono-Regular, Menlo, Monaco,
    Consolas, 'Liberation Mono', 'Courier New', monospace;
  font-size: 13px;
}

.placeholder {
  color: var(--vt-c-text-2);
  font-size: 13px;
}
</style>