quickspeadsheet 1.0.0

package/dist/types/excel/core/excelio.d.ts

@@ -0,0 +1,415 @@
+/**
+ * ExcelIO 类型定义 - 对齐 gc.spread.excelio API
+ */
+
+export const ErrorCode: {
+  fileIOError: 0
+  fileFormatError: 1
+  noPassword: 2
+  invalidPassword: 3
+}
+
+export interface ExcelIOError {
+  errorCode: number
+  errorMessage: string
+  fileName?: string
+}
+
+export interface ExcelIOOpenOptions {
+  /** 密码（加密文件） */
+  password?: string
+  /** 0=DataURL, 1=ArrayBuffer，默认 1 */
+  loadType?: 0 | 1
+  /** 仅解析指定 sheet 索引，如 [0, 1] */
+  parseSheets?: number[]
+  /** 每个 sheet 最多解析行数 */
+  maxRows?: number
+  /** 加载进度回调 (loaded, total) */
+  onProgress?: (loaded: number, total: number) => void
+  /** 调试模式，输出解析阶段与耗时 */
+  debug?: boolean
+  /** 延迟解析 preservedFiles，首次 save 时从 zip 按需加载，降低大文件内存占用，默认 true */
+  lazyPreservedFiles?: boolean
+  /** 仅校验结构不解析数据，快速检测损坏文件，返回 ValidateResult */
+  validateOnly?: boolean
+  /** 打开时预计算公式值，将结果写入单元格 v（依赖 formulaEngine 支持的函数） */
+  precomputeFormulas?: boolean
+  /** 加密文件解密时使用 Web Worker，避免 PBKDF2 阻塞主线程（需浏览器支持 Worker） */
+  useWorkerForDecrypt?: boolean
+  /** Worker 中对 worksheet 使用 SAX/token 解析（大文件建议开启） */
+  useSaxWorksheetParser?: boolean
+  /** worksheet SAX 解析批大小，默认 1000 */
+  rowBatchSize?: number
+  /**
+   * Worker 将大表 `sheet.data` 流式 post 到主线程时每块行数（仅 dataLength 超过该值时分块）。
+   * 更大可减少 `onmessage` 与 structured clone 次数；过大可能抬高单次克隆峰值。默认 40000，范围约 2000～120000。
+   */
+  sheetPostChunkRows?: number
+  /**
+   * 每条主线程消息合并几个行数据分片（`sheet_chunks`），降低 `worker.onmessage` 调度开销。
+   * 默认 3；可设 1 关闭合并；最大 16。与 `sheetPostChunkRows` 同时调大时注意单次克隆内存峰值。
+   */
+  sheetChunksPerPost?: number
+  /** Worker 路径下跳过大段 XML 序列化回填，降低峰值内存 */
+  skipXmlSerializationInWorker?: boolean
+  /** 开发调试：对比 SAX 与 DOM 解析结果字段差异（Worker progress: worksheet_sax_diff） */
+  debugWorksheetSaxDiff?: boolean
+}
+
+export interface ValidateResult {
+  valid: true
+  sheetCount: number
+  sheetNames: string[]
+  /** OPC：与完整解析结果中字段一致 */
+  workbookPartPath?: string
+  officeDocumentTarget?: string | null
+}
+
+/** OOXML c:spPr 简化结构（parseChart / buildChartXml 对齐） */
+export interface ChartSpPrJson {
+  noFill?: boolean
+  fillColor?: string
+  fillSchemeClr?: string
+  [key: string]: unknown
+}
+
+export interface ChartAxisTitleJson {
+  text?: string
+  spPr?: ChartSpPrJson
+  txPr?: unknown
+  layout?: unknown
+  [key: string]: unknown
+}
+
+/** parseAxis / parseAxisFallback 输出的轴（catAx、valAx、dateAx、serAx） */
+export interface ChartAxisJson {
+  axisType?: 'cat' | 'val' | 'date' | 'ser' | string
+  axId?: number
+  axPos?: string
+  crossAx?: number
+  crosses?: string
+  crossesAt?: number
+  crossBetween?: string
+  scaling?: unknown
+  numFmt?: { formatCode?: string; sourceLinked?: boolean }
+  title?: ChartAxisTitleJson
+  delete?: boolean
+  majorGridlines?: boolean
+  minorGridlines?: boolean
+  lblOffset?: number
+  majorTickMark?: string
+  minorTickMark?: string
+  tickLblPos?: string
+  [key: string]: unknown
+}
+
+/** c:legend（与 parseLegend / buildLegendXml 对齐） */
+export interface ChartLegendJson {
+  pos?: string
+  overlay?: boolean
+  layout?: unknown
+  spPr?: ChartSpPrJson
+  txPr?: unknown
+  [key: string]: unknown
+}
+
+/** c:dTable（绘图区数据表，ECMA-376 CT_DTable） */
+export interface ChartDataTableJson {
+  showHorzBorder?: boolean
+  showVertBorder?: boolean
+  showOutline?: boolean
+  showKeys?: boolean
+  spPr?: ChartSpPrJson
+  txPr?: unknown
+  [key: string]: unknown
+}
+
+export interface ChartSeriesErrBarsJson {
+  errBarType?: string
+  errValType?: string
+  errDir?: string
+  noEndCap?: boolean
+  val?: number
+  plus?: number[]
+  minus?: number[]
+  plusFormula?: string
+  minusFormula?: string
+  plusNumFmt?: { formatCode?: string }
+  minusNumFmt?: { formatCode?: string }
+  spPr?: ChartSpPrJson
+  [key: string]: unknown
+}
+
+/** parseChart 输出的单张图表 JSON（字段随类型扩展，未列出的仍可能存在） */
+export interface WorkbookChartJson {
+  chartType?: string | null
+  title?: unknown
+  legend?: ChartLegendJson
+  chartStyleId?: number
+  /** chartSpace / c:lang @val（BCP 47） */
+  lang?: string
+  /** c:chart / c:roundedCorners */
+  roundedCorners?: boolean
+  /** 与 plotArea.dataTable 等价入口（写 chart 时若 plotArea 未带 dataTable 则用此项） */
+  dataTable?: ChartDataTableJson
+  /** 与 plotArea.axes 同一引用（多轴、写回 buildChartXml） */
+  axes?: ChartAxisJson[]
+  /** chartSpace 直接子级 c:spPr（在 c:chart 之后等） */
+  chartSpaceSpPr?: ChartSpPrJson
+  /** c:chart 下 c:spPr */
+  chartSpPr?: ChartSpPrJson
+  /** 自 charts/_rels/chartN.xml.rels 解析的 chartColorStyle 关系（如 colorsN.xml） */
+  chartColorStyleRel?: {
+    rId?: string
+    relationshipType?: string
+    target?: string
+    targetMode?: string
+    [key: string]: unknown
+  }
+  /** 自 chart .rels 解析的 chartStyle 关系（如 styleN.xml，不含 chartColorStyle） */
+  chartStyleRel?: {
+    rId?: string
+    relationshipType?: string
+    target?: string
+    targetMode?: string
+    [key: string]: unknown
+  }
+  /** 自包内读入的 colorsN.xml 全文（回写时优先于占位 XML） */
+  chartColorStyleXml?: string
+  /** 自包内读入的 styleN.xml 全文 */
+  chartStyleXml?: string
+  /** chartSpace / c:externalData；保存时 workbookJsonToZip 会写 charts/_rels/chartN.xml.rels */
+  externalData?: {
+    rId?: string
+    autoUpdate?: boolean
+    /** 默认 officeDocument；外链可设 hyperlink 等 */
+    relationshipType?: string
+    /** 相对 chart 部件的 Target；缺省按 workbookPartPath 算到主 workbook */
+    target?: string
+    targetMode?: string
+    [key: string]: unknown
+  }
+  chartGroups?: unknown[]
+  dLbls?: unknown
+  dispBlanksAs?: string
+  view3D?: unknown
+  /** 部分属性自 plotArea 主图组同步到根级 */
+  wireframe?: boolean
+  radarStyle?: string
+  /** 首图组 c:dropLines / c:hiLowLines / c:upDownBars（与 parseChartGroupProps 一致） */
+  dropLines?: { spPr?: ChartSpPrJson; [key: string]: unknown }
+  hiLowLines?: { spPr?: ChartSpPrJson; [key: string]: unknown }
+  upDownBars?: {
+    gapWidth?: number
+    upBars?: { spPr?: ChartSpPrJson; [key: string]: unknown }
+    downBars?: { spPr?: ChartSpPrJson; [key: string]: unknown }
+    [key: string]: unknown
+  }
+  plotArea?: {
+    chartType?: string | null
+    radarStyle?: string
+    wireframe?: boolean
+    series?: unknown[]
+    axes?: ChartAxisJson[]
+    catAx?: ChartAxisJson | null
+    valAx?: ChartAxisJson | null
+    dateAx?: ChartAxisJson | null
+    serAx?: ChartAxisJson | null
+    spPr?: ChartSpPrJson
+    dataTable?: ChartDataTableJson
+    layout?: unknown
+    chartGroups?: unknown[]
+    [key: string]: unknown
+  } | null
+  series?: Array<{
+    idx?: number
+    order?: number
+    name?: string | null
+    catFormula?: string | null
+    valFormula?: string | null
+    errBars?: ChartSeriesErrBarsJson
+    [key: string]: unknown
+  }>
+  [key: string]: unknown
+}
+
+/** calcChain.xml 中 `<c>` 项（`r` 为单元格引用；`i`/`l`/`s` 为 ECMA-376 可选整数属性） */
+export interface CalcChainCell {
+  r: string
+  i?: number
+  l?: number
+  s?: number
+}
+
+/** `parseCalcChain` / `buildCalcChainXml` 使用的结构化模型（与 `ooxml/calcChain.js` 一致） */
+export interface CalcChainParsed {
+  cells: CalcChainCell[]
+}
+
+export interface ExcelIOSaveOptions {
+  /** 保存时加密密码 */
+  password?: string
+  /** true 时返回 ArrayBuffer，false 时返回 Blob；未指定时在无 Blob 环境（如旧版 Node）自动用 ArrayBuffer */
+  useArrayBuffer?: boolean
+  /** 压缩级别 0-9，大文件可降低以加快保存 */
+  compressionLevel?: number
+  /** 是否使用 Web Worker 执行保存（默认 true；失败会自动回退主线程） */
+  useWorker?: boolean
+}
+
+export interface WorkbookJson {
+  version?: string
+  sheets: SheetJson[]
+  stylesXml?: string
+  /** x14:slicerStyles 从 styles extLst 提取（显式访问） */
+  slicerStylesXml?: string
+  /** x14:slicerStyles 结构化解析 { defaultSlicerStyle, styles: [{ name, styleElements }] } */
+  slicerStyles?: { defaultSlicerStyle: string; styles: Array<{ name: string; styleElements?: Array<{ type: string; dxfId: string }> }> }
+  themeXml?: string
+  themeColors?: Record<string, string>
+  themeFonts?: { name?: string; majorFont?: { latin?: string }; minorFont?: { latin?: string } }
+  sharedStringsItems?: unknown[]
+  preservedFiles?: Record<string, string>
+  preservedRootRels?: string
+  /** 图表结构化解析（P3-10，key 为 `{spreadsheetRoot}/charts/chartN.xml` 形式包内路径） */
+  charts?: Record<string, WorkbookChartJson>
+  preservedWbRels?: string
+  /** workbook 级关联部件（externalLinks/connections/pivotCache/calcChain 等） */
+  workbookLinkedParts?: Array<{
+    relId: string
+    type: string
+    path: string
+    xml: string | null
+    parsed?: CalcChainParsed
+  }>
+  externalLinks?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  connections?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  queryTables?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  pivotCaches?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  pivotCacheRecords?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  pivotTables?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  slicerCaches?: Array<{ relId: string; type: string; path: string; xml: string | null }>
+  pivotCacheDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  pivotCacheRecordDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  pivotTableDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  slicerCacheDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  externalLinkDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  connectionDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  queryTableDefinitions?: Array<{ relId: string; type: string; path: string; xml: string | null; parsed?: Record<string, unknown> }>
+  /**
+   * calcChain 部件快捷引用（与 `workbookLinkedParts` 中 calcChain 项宜为同一引用）。
+   * 保存前可将顶层的 `parsed` / `xml` 合并进 linkedParts：`mergeTopLevelCalcChainIntoWorkbookLinkedParts(json)`（与 ExcelIO 内部一致）。
+   */
+  calcChain?: {
+    relId: string
+    type: string
+    path: string
+    xml: string | null
+    parsed?: CalcChainParsed
+  } | null
+  workbookPr?: Record<string, unknown>
+  workbookExtLstXml?: string
+  wbPassthrough?: string
+  customProperties?: Array<{ name: string; value: string }>
+  definedNames?: Array<{ name: string; formula: string; localSheetId?: number }>
+  bookViews?: unknown
+  calcPr?: unknown
+  [key: string]: unknown
+}
+
+export interface SheetJson {
+  name: string
+  data: Record<number, Record<number, CellValue>>
+  spans?: Array<{ row: number; col: number; rowCount: number; colCount: number }>
+  visible?: boolean
+  state?: string
+  rId?: string
+  sheetId?: number
+  uuid?: string
+  rowMeta?: Record<number, { hidden?: boolean; ht?: number; outlineLevel?: number; collapsed?: boolean; resizable?: boolean }>
+  colMeta?: Record<number, { width?: number; hidden?: boolean; outlineLevel?: number; collapsed?: boolean; resizable?: boolean }>
+  preservedWorksheetXml?: string
+  preservedWsRels?: string
+  /** autoFilter 结构化（ref、filterColumns） */
+  autoFilter?: { ref: string; filterColumns?: Array<{ colId: number; filtersXml?: string; customFiltersXml?: string }>; sortState?: unknown }
+  /** sortState 结构化（ref、sortConditions） */
+  sortState?: { ref: string; columnSort?: boolean; caseSensitive?: boolean; sortMethod?: string; sortConditions?: Array<{ ref?: string; descending?: boolean; sortType?: string }> }
+  /** 绘图 shapes（P3-11 解析 xdr:twoCellAnchor 等） */
+  shapes?: Array<{
+    type: string
+    anchorType: string
+    from: { col: number; row: number; colOff: number; rowOff: number }
+    to?: { col: number; row: number; colOff: number; rowOff: number }
+    ext?: { cx: number; cy: number }
+    element?: string
+    editAs?: string | null
+    innerXml?: string
+  }>
+  /** 切片器结构化（解析 sle:slicers） */
+  slicers?: Array<{ name?: string; cache?: string; caption?: string; columnCount?: number; style?: string; cachePath?: string; [key: string]: unknown }>
+  /** worksheet 级 pivot table parts 原始 XML */
+  pivotTablePartsXml?: string
+  /** worksheet 级 pivot table 定义（来自 sheet rels） */
+  pivotTables?: Array<{ relId?: string; type?: string; path?: string; xml?: string | null; parsed?: Record<string, unknown> }>
+  /** worksheet 级 query table 定义（来自 sheet rels） */
+  queryTables?: Array<{ relId?: string; type?: string; path?: string; xml?: string | null; parsed?: Record<string, unknown> }>
+  /** 表结构化（解析 `{spreadsheetRoot}/tables/tableN.xml`） */
+  tables?: Array<{
+    id?: number
+    name?: string
+    displayName?: string
+    ref: string
+    headerRowCount?: number
+    totalsRowCount?: number
+    totalsRowShown?: boolean
+    columns?: Array<{ id?: number; name: string; totalsRowLabel?: string; totalsRowFunction?: string }>
+    style?: {
+      name?: string
+      showFirstColumn?: boolean
+      showLastColumn?: boolean
+      showRowStripes?: boolean
+      showColumnStripes?: boolean
+    }
+    autoFilter?: { ref?: string; xml?: string }
+    path?: string
+  }>
+  [key: string]: unknown
+}
+
+export interface CellValue {
+  v?: string | number | { _error?: string; _code?: number }
+  f?: string
+  styleId?: number
+  comment?: string | { text: string; textRunsXml?: string; authorId?: number }
+  hyperlink?: string
+  [key: string]: unknown
+}
+
+export class ExcelIO {
+  open(
+    file: string | Blob | ArrayBuffer | File,
+    successCallback: (workbookJson: WorkbookJson) => void,
+    errorCallback: (error: ExcelIOError) => void,
+    options?: ExcelIOOpenOptions
+  ): void
+
+  openAsync(file: string | Blob | ArrayBuffer | File, options?: ExcelIOOpenOptions): Promise<WorkbookJson | ValidateResult>
+
+  save(
+    workbookJson: WorkbookJson | string,
+    successCallback: (out: Blob | ArrayBuffer) => void,
+    errorCallback: (error: ExcelIOError) => void,
+    options?: ExcelIOSaveOptions
+  ): void
+
+  saveAsync(workbookJson: WorkbookJson | string, options?: ExcelIOSaveOptions): Promise<Blob | ArrayBuffer>
+}
+
+export interface CreateExcelIOOptions {
+  /** true 时仅支持 open，save 将报错 */
+  readOnly?: boolean
+}
+
+export function createExcelIO(options?: CreateExcelIOOptions): ExcelIO
+
+export function getCommentDisplayText(comment: string | { text?: string } | null | undefined): string

package/dist/types/index.d.ts

@@ -0,0 +1,33 @@
+export * from './types/spread'
+
+export type { Workbook, Worksheet, Cell } from './types/spread'
+
+export type {
+  ApplyRemoteOperationsResult,
+  CollaborationHistoryVersionsPage,
+  CollaborationJsonRecord,
+  CollaborationServicesConfig,
+  CollaborationSessionLike,
+  CollaborationStateSnapshot,
+  ConnectDocumentInput,
+  ExcelIO,
+  FormulaBoxInstance,
+  HostActionMissingPayload,
+  HostActionReturn,
+  PublishOperationsResult,
+  RemoteReplayReportInput,
+  RemoteReplayReportResult,
+  ResolveConflictInput,
+  RuntimeAddInDefinition,
+  RuntimeDownloadRequest,
+  RuntimeImportFileResult,
+  RuntimeImportUrlResult,
+  RuntimeIoHooks,
+  SpreadExtensionHostLike,
+  SpreadLicenseSnapshot,
+  SpreadRuntime,
+  SpreadRuntimeHostActions,
+  SpreadRuntimeOptions,
+  SpreadWorkbookInstance,
+  SpreadWorkbookOpcPackageFields,
+} from './runtime-public'

package/dist/types/pro.d.ts

@@ -0,0 +1,10 @@
+export * from './index'
+
+export declare const proEditionPlugin: {
+  install(app: any, options?: Record<string, any>): any
+}
+
+export declare const install: typeof proEditionPlugin.install
+
+declare const _default: typeof proEditionPlugin
+export default _default