@jitword/sheet-sdk

A self-contained spreadsheet SDK wrapping the Univer.js engine. Provides structured APIs for cell data manipulation, sheet management, Excel import/export, permissions, and real-time collaboration.

一个封装了 Univer.js 引擎的独立电子表格 SDK。提供单元格数据操作、工作表管理、Excel 导入导出、权限控制和实时协作等结构化 API。

Installation (CDN)

安装（CDN）

Load the SDK via <script> tags. The full bundle includes all dependencies (Univer engine, ExcelJS, etc.) in a single file.

通过 <script> 标签加载 SDK。完整包将所有依赖（Univer 引擎、ExcelJS 等）打包为单一文件。

<!-- 1. Univer CSS -->
<link rel="stylesheet" href="./lib/univer.css" />

<!-- 2. Process polyfill (required for bundled Node.js deps) -->
<script>
  if (typeof window.process === 'undefined') {
    window.process = {
      env: { NODE_ENV: 'production' },
      versions: { node: '' },
      nextTick: function(fn) { setTimeout(fn, 0) },
      browser: true
    };
  }
</script>

<!-- 3. JitSheet SDK (full bundle, UMD) -->
<script src="./lib/jit-sheet.full.js"></script>

Quick Start

快速开始

// Access the constructor from UMD global
// 从 UMD 全局变量获取构造函数
var JitSheet = window.JitSheet.JitSheet

// 1. Create instance | 创建实例
var sheet = new JitSheet({
  container: '#spreadsheet',
  locale: 'zh-CN',
  editable: true,
  onChange: function(snapshot) {
    console.log('Data changed', snapshot)
  }
})

// 2. Use sub-APIs | 使用子 API
sheet.data.setCellValue('sheet1', 0, 0, 'Hello')
sheet.sheets.createSheet('New Sheet')
sheet.io.exportExcel('report.xlsx')

// 3. Listen to events | 监听事件
sheet.on('change', function(snapshot) {
  console.log('Data changed', snapshot)
})

// 4. Cleanup | 销毁
sheet.destroy()

Configuration Options

配置选项

JitSheet Facade

The main entry point. All sub-APIs are accessed via its properties.

主入口类。所有子 API 通过其属性访问。

DataAPI sheet.data

Cell-level data CRUD and full workbook snapshot operations.

单元格数据增删改查和工作簿快照操作。

// Read & write cells | 读写单元格
const val = sheet.data.getCellValue('sheet1', 0, 0)
sheet.data.setCellValue('sheet1', 0, 0, 'Hello World')

// Batch write | 批量写入
sheet.data.setCells('sheet1', {
  0: { 0: { v: 'Name' }, 1: { v: 'Age' } },
  1: { 0: { v: 'Alice' }, 1: { v: 30 } },
})

// Smart patch from server | 从服务端智能补丁
const ok = sheet.data.patchFromSnapshot(remoteSnapshot)
if (!ok) sheet.reinit(remoteSnapshot)

SheetAPI sheet.sheets

Sheet (tab) management — create, delete, rename, list, and switch sheets.

工作表（标签页）管理 — 创建、删除、重命名、列表和切换工作表。

// Manage sheets | 管理工作表
const sheets = sheet.sheets.getSheets()
const newId = sheet.sheets.createSheet('Q1 Revenue')
sheet.sheets.switchSheet(newId)
sheet.sheets.renameSheet(newId, 'Q1 Revenue (Final)')

IOAPI sheet.io

Import and export workbook data in Excel (.xlsx) and JSON formats.

以 Excel (.xlsx) 和 JSON 格式导入导出工作簿数据。

// Export to Excel | 导出 Excel
await sheet.io.exportExcel('report.xlsx')

// Import from file input | 从文件输入导入
const file = fileInput.files[0]
await sheet.io.importExcel(file)

// JSON round-trip | JSON 往返
const json = sheet.io.exportJSON()
localStorage.setItem('backup', JSON.stringify(json))
sheet.io.importJSON(JSON.parse(localStorage.getItem('backup')))

PermissionAPI sheet.permission

Runtime permission toggling and sheet-level protection.

运行时权限切换与工作表级保护。

// Toggle based on user role | 根据用户角色切换
if (user.role === 'viewer') {
  sheet.permission.setReadonly()
}

// Sheet protection | 工作表保护
sheet.permission.setSheetProtection('sheet1', {
  password: 'secret',
  selectLockedCells: true,
  formatCells: false,
  insertRows: false,
  deleteRows: false,
})

CollabAPI sheet.collab

Real-time collaboration via Yjs + y-websocket. Uses cell-level sync for minimal latency.

基于 Yjs + y-websocket 的实时协作。采用单元格级同步以实现最低延迟。

// Connect to collaboration | 连接协作
await sheet.collab.connect('doc-123')

sheet.on('collab:users', (users) => {
  console.log('Online:', users.map(u => u.name))
})

sheet.on('collab:status', (status) => {
  console.log('Connection:', status)
})

Events EventBus

事件 EventBus

Types TypeScript

类型定义 TypeScript

interface SheetSnapshot {
  id?: string
  name?: string
  sheets: Record<string, SheetData>
  sheetOrder: string[]
  styles?: Record<string, any>
  resources?: any[]
  drawings?: DrawingData[]
}

interface SheetData {
  id: string
  name: string
  cellData: Record<number, Record<number, CellData>>
  rowCount?: number
  columnCount?: number
  rowData?: Record<number, { h?: number }>
  columnData?: Record<number, { w?: number }>
  mergeData?: MergeRange[]
}

interface CellData {
  v?: any        // Cell value
  f?: string     // Formula
  s?: string | number  // Style id
  t?: number     // Cell type
  p?: any        // Rich text paragraph
}

interface SheetInfo {
  id: string
  name: string
  index: number
  isActive: boolean
  rowCount: number
  columnCount: number
}

interface ProtectionConfig {
  password?: string
  selectLockedCells?: boolean
  formatCells?: boolean
  insertRows?: boolean
  deleteRows?: boolean
  sort?: boolean
  autoFilter?: boolean
}

interface SelectionEvent { row: number; col: number; sheetId: string }
interface ScrollEvent { top: number; left: number; raw?: any }
interface ZoomEvent { ratio: number }
interface TabSwitchEvent { sheetId: string }

interface CollabUser { userId: string; name: string; color: string; clientId: number }
interface CollabCursor { clientId: number; userId: string; name: string; color: string; row: number; col: number; sheetId: string }

type PermissionMode = 'edit' | 'readonly'
type CollabStatus = 'idle' | 'connecting' | 'connected' | 'disconnected'