---

title: 读写与流式解析 description: readWorkbook / readWorkbookStream / writeWorkbook 的输入输出与事件模型 sidebarOrder: 2 outline: deep

读写与流式解析

介绍

@cat-kit/excel 提供三类 I/O API：

• writeWorkbook：将内存模型写成 xlsx 字节流
• readWorkbook：一次性读取完整工作簿
• readWorkbookStream：按事件流读取，适合大文件分步处理

快速使用

import { readWorkbook, readWorkbookStream, writeWorkbook, Workbook } from '@cat-kit/excel'

const workbook = new Workbook()
workbook.addWorksheet('Sheet1').setCell('A1', 'hello')

const bytes = writeWorkbook(workbook)
const parsed = await readWorkbook(bytes)
console.log(parsed.getWorksheet('Sheet1')?.getCell('A1')?.value)

for await (const event of readWorkbookStream(bytes, { includeEmptyRows: true })) {
  if (event.type === 'row') {
    console.log(event.sheetName, event.rowIndex, event.values)
  }
}

vue

包含空行事件 工作表过滤

工作表: 0行事件: 0空行: 0

上传文件后，这里会用表格展示读取结果（最多 30 行）。

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262

<template>
  <div class="stream-card">
    <div class="stream-card__toolbar">
      <button type="button" class="btn btn-primary" :disabled="reading" @click="pickFile">
        {{ reading ? '解析中...' : '选择 .xlsx 文件' }}
      </button>
      <label class="inline-field">
        <input v-model="includeEmptyRows" type="checkbox" />
        包含空行事件
      </label>
      <label class="inline-field">
        工作表过滤
        <input
          v-model.trim="sheetFilter"
          type="text"
          placeholder="留空表示全部；例如 Sales"
          :disabled="reading"
        />
      </label>
      <input
        ref="fileInput"
        class="file-input"
        type="file"
        accept=".xlsx"
        @change="handleFileChange"
      />
    </div>

    <div class="stream-card__stats">
      <span>工作表: {{ stats.sheetCount }}</span>
      <span>行事件: {{ stats.rowCount }}</span>
      <span>空行: {{ stats.emptyRowCount }}</span>
      <span v-if="message">{{ message }}</span>
    </div>

    <var-table v-if="rows.length" class="stream-table" :scroller-height="320" :elevation="0">
      <thead>
        <tr>
          <th>Sheet</th>
          <th>Row</th>
          <th v-for="column in displayColumns" :key="column">C{{ column }}</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="row in rows" :key="row.id">
          <td>{{ row.sheetName }}</td>
          <td>{{ row.rowIndex }}</td>
          <td
            v-for="column in displayColumns"
            :key="`${row.id}-${column}`"
            class="cell-mono"
          >
            {{ row.values[column - 1] || '' }}
          </td>
        </tr>
      </tbody>
    </var-table>
    <p v-else class="placeholder">上传文件后，这里会用表格展示读取结果（最多 30 行）。</p>
  </div>
</template>

<script lang="ts" setup>
import { computed, reactive, ref } from 'vue'
import { readWorkbookStream, type CellValue, type ReadStreamOptions } from '@cat-kit/excel'

interface RowPreview {
  id: string
  sheetName: string
  rowIndex: number
  values: string[]
}

const PREVIEW_LIMIT = 30
const MAX_COLUMNS = 8

const fileInput = ref<HTMLInputElement | null>(null)
const includeEmptyRows = ref(false)
const sheetFilter = ref('')
const reading = ref(false)
const message = ref('')
const rows = ref<RowPreview[]>([])

const stats = reactive({
  sheetCount: 0,
  rowCount: 0,
  emptyRowCount: 0
})

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

function resetState() {
  rows.value = []
  message.value = ''
  stats.sheetCount = 0
  stats.rowCount = 0
  stats.emptyRowCount = 0
}

function formatCell(value: CellValue): string {
  if (value === null) return 'null'
  if (value instanceof Date) return value.toISOString()
  if (typeof value === 'object' && value && 'formula' in value) {
    return value.result === undefined
      ? `=${value.formula}`
      : `=${value.formula} (result: ${String(value.result)})`
  }
  return String(value)
}

function buildOptions(): ReadStreamOptions {
  const options: ReadStreamOptions = {
    includeEmptyRows: includeEmptyRows.value
  }

  const name = sheetFilter.value.trim()
  if (name) {
    options.sheets = [name]
  }

  return options
}

const displayColumns = computed(() => {
  let max = 1
  for (const row of rows.value) {
    if (row.values.length > max) max = row.values.length
  }
  const limit = Math.min(max, MAX_COLUMNS)
  return Array.from({ length: limit }, (_, index) => index + 1)
})

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

  resetState()
  reading.value = true

  try {
    for await (const item of readWorkbookStream(file, buildOptions())) {
      if (item.type === 'sheetStart') {
        stats.sheetCount += 1
        continue
      }

      if (item.type === 'sheetEnd') {
        continue
      }

      stats.rowCount += 1
      if (item.values.length === 0) {
        stats.emptyRowCount += 1
      }

      if (rows.value.length < PREVIEW_LIMIT) {
        rows.value.push({
          id: `${item.sheetIndex}-${item.rowIndex}`,
          sheetName: item.sheetName,
          rowIndex: item.rowIndex,
          values: item.values.slice(0, MAX_COLUMNS).map(formatCell)
        })
      }
    }

    message.value = `解析完成，已预览 ${rows.value.length} 行`
  } catch (error) {
    message.value = error instanceof Error ? error.message : String(error)
  } finally {
    reading.value = false
    input.value = ''
  }
}
</script>

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

.stream-card__toolbar {
  display: flex;
  flex-wrap: wrap;
  gap: 10px;
  align-items: center;
}

.inline-field {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  color: var(--vp-c-text-2);
  font-size: 13px;
}

.inline-field input[type='text'] {
  min-width: 220px;
}

.stream-card input[type='text'] {
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 6px 8px;
  background: var(--vp-c-bg);
  color: var(--vp-c-text-1);
}

.file-input {
  display: none;
}

.btn {
  border: 1px solid var(--vp-c-divider);
  background: var(--vp-c-bg);
  color: var(--vp-c-text-1);
  border-radius: 8px;
  padding: 6px 10px;
  cursor: pointer;
}

.btn:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

.btn-primary {
  border-color: #16a34a;
  background: #16a34a;
  color: #fff;
}

.stream-card__stats {
  margin-top: 10px;
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  font-size: 13px;
  color: var(--vp-c-text-2);
}

.stream-table {
  margin-top: 12px;
}

.cell-mono {
  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Courier New', monospace;
  font-size: 12px;
  word-break: break-word;
}

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

API参考

readWorkbook

readWorkbook(input: WorkbookInput, options?: ReadOptions): Promise<Workbook>

• 支持输入：Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>
• options.dateSystem：1900 | 1904，用于日期序列号解释（默认 1900）

readWorkbookStream

readWorkbookStream(
  input: WorkbookInput,
  options?: ReadStreamOptions
): AsyncIterable<StreamEvent>

• options.sheets?: string[]：按工作表名称过滤
• options.includeEmptyRows?: boolean：是否补齐空行 row 事件
• 事件类型：
  • sheetStart：工作表开始
  • row：行数据（rowIndex 为 1-based）
  • sheetEnd：工作表结束

writeWorkbook

writeWorkbook(workbook: Workbook, options?: WriteOptions): Uint8Array

• 入参必须是 Workbook 实例，且至少包含一个工作表
• options.useSharedStrings 默认 true
• options.compressionLevel 可控制 zip 压缩级别

StreamEvent 类型

type StreamEvent =
  | { type: 'sheetStart'; sheetName: string; sheetIndex: number }
  | { type: 'sheetEnd'; sheetName: string; sheetIndex: number }
  | { type: 'row'; sheetName: string; sheetIndex: number; rowIndex: number; values: CellValue[] }