SpreadsheetImportProgress

SpreadsheetImportProgress:

{
  phase: SpreadsheetImportPhase;
  sheet: number | null;
  sheetCount: number | null;
  done: number;
  total: number | null;
  unit: "bytes" | "rows" | "spans" | "sheets";
}

How far opening a spreadsheet has got.

Experimental: the spreadsheet API may change or be removed in any release, including minor and patch releases.

Each report describes one phase: done and total count that phase’s work and start again when the next phase begins, so show progress per phase rather than as one number for the whole file.

Examples

// A status line that follows the phases: "Reading sheet 2 of 5 — 40%", then "Indexing — 63%", then "Opening…"
const percent = ({ done, total }: SpreadsheetImportProgress) =>
  total === null ? '' : ` — ${Math.min(100, Math.round((done / total) * 100))}%`;

const describe = (progress: SpreadsheetImportProgress): string => {
  const { phase, sheet, sheetCount } = progress;
  switch (phase) {
    case 'reading':
      return sheet === null || sheetCount === null
        ? 'Reading…'
        : `Reading sheet ${sheet + 1} of ${sheetCount}${percent(progress)}`;
    case 'indexing':
      return `Indexing${percent(progress)}`;
    case 'loading':
      return 'Opening…';
  }
};

const spreadsheet = await system.importSpreadsheet(file, {
  onProgress: (progress) => statusLabel.replaceChildren(describe(progress)),
});

// One <progress> bar per phase. A phase with no total shows its bar as indeterminate, and a phase the file
// never goes through (a saved spreadsheet is not read like an .xlsx) leaves its bar untouched.
const bars: Record<SpreadsheetImportPhase, HTMLProgressElement> = {
  reading: readingBar,
  indexing: indexingBar,
  loading: loadingBar,
};

const spreadsheet = await system.importSpreadsheet(file, {
  onProgress: ({ phase, done, total }) => {
    const bar = bars[phase];
    if (total === null) bar.removeAttribute('value');
    else bar.value = Math.min(1, done / total);
  },
});

Experimental

This API should not be used in production and may be trimmed from a public release.

Properties

phase

readonly phase: SpreadsheetImportPhase

---

sheet

readonly sheet: number | null

Which sheet is being worked on, 0-based, or null in a phase that is not about one sheet.

---

sheetCount

readonly sheetCount: number | null

How many sheets the spreadsheet has, or null before the file has said.

---

done

readonly done: number

How much of this phase is done, counted in SpreadsheetImportProgress.unit.

---

total

readonly total: number | null

What done is counted towards, or null when the file states no total for this phase.

Never a guess. A sheet in the file is not required to declare how many rows it has, and one that declares a figure is permitted to be wrong about it — so done may exceed a non-null total. Treat a percentage built from these as an estimate and clamp it before showing it.

---

unit

readonly unit: "bytes" | "rows" | "spans" | "sheets"

What done and total count, which depends on the phase.

• reading counts rows of the sheet named by sheet, after a sheets report as each sheet starts.
• indexing counts bytes of the file, or spans — blocks of rows — when a spreadsheet saved by an earlier version has to be read a second time.
• loading reports sheets once, with no total.