cupertino-files / NumbersDocument
Class: NumbersDocument
Defined in: src/numbers/document.ts:31
Extends
Properties
container
readonlycontainer:IWorkContainer
Defined in: src/tsa/document.ts:125
Inherited from
format
readonlyformat:FormatInfo
Defined in: src/tsa/document.ts:127
Inherited from
store
readonlystore:ObjectStore
Defined in: src/tsa/document.ts:126
Inherited from
Accessors
app
Get Signature
get app():
IWorkApp
Defined in: src/tsa/document.ts:167
Returns
Inherited from
era
Get Signature
get era():
"iwork13"|"iwork16"|"iwork19"|"modern"|"current"|"future"
Defined in: src/tsa/document.ts:285
Format era this document was written by (see tsp/version.ts).
Returns
"iwork13" | "iwork16" | "iwork19" | "modern" | "current" | "future"
Inherited from
Methods
addSheet()
addSheet(
options?):SheetInfo
Defined in: src/numbers/document.ts:166
Add a sheet by copying an existing one.
A sheet is a container for drawables, and a Numbers document with an empty one is perfectly valid — but the tables on a sheet are what make it useful, and building a table from nothing means synthesising tiles, header buckets, data lists and a calc-engine owner. Copying is both simpler and closer to what Numbers does when you duplicate a tab.
By default the copy keeps its tables (a duplicate); pass withContent: false for an empty sheet.
Parameters
options?
at?
number
copyOf?
number
name?
string
withContent?
boolean
Returns
Agent Tool
manage_sheets
addTable()
addTable(
sheetId,options?):TableModel
Defined in: src/numbers/document.ts:273
Add a table to a sheet by copying an existing one.
Building a table from nothing means synthesising tiles, header buckets, data lists and a calc-engine owner — the same reason sheets and slides are created by copying. The source defaults to the first table on the target sheet, falling back to any table in the document.
The copy is renamed, because Numbers addresses tables by name: two tables called "Table 1" on one sheet make every cross-table formula ambiguous. Names must be unique per sheet, not per document, so a copy onto a different sheet can keep the original's name.
withContent: false clears the cells but keeps the shape, styling and header bands — a blank table laid out like its source, which is what you want far more often than a duplicate of the data.
Parameters
sheetId
bigint
options?
copyOf?
bigint
name?
string
withContent?
boolean
x?
number
y?
number
Returns
Agent Tool
manage_sheets
allText()
allText():
string
Defined in: src/tsa/document.ts:228
Concatenated plain text of all in-document storages (reading order approximation).
Returns
string
Inherited from
charts()
charts():
ChartModel[]
Defined in: src/tsa/document.ts:207
Every chart, with its plotted data (see ChartModel).
Returns
Inherited from
compact()
compact():
number
Defined in: src/tsa/document.ts:310
Drop archives nothing can reach, returning how many went.
What this collects today is very little, and that is worth knowing before reaching for it. Removing a sheet or a table unlinks it from the document tree, but the calc engine keeps its own references to every table it ever knew, so those archives stay genuinely reachable. The gap is in removal — unregistering a table's formula owners is calc-engine surgery this library does not do yet — not in the walk. What compaction does reclaim is objects created and then abandoned.
Roots are the package metadata, each component's first object, and every selection archive; see ObjectStore.prune for the scan and for why it errs towards keeping things. It is a no-op on every untouched document in the corpus, which is the property that matters: a collector that trims a file nobody edited is broken.
Returns
number
Inherited from
compatibility()
compatibility():
CompatibilityReport
Defined in: src/tsa/document.ts:266
What this library can and cannot do with THIS document: declared versions, the era they place it in, structural probes (unknown type IDs, cell-storage generation, patch archives, collaboration state) and any unsupported features. Loading never fails on version grounds — this is how a caller finds out what to expect.
Returns
Inherited from
compatibilitySummary()
compatibilitySummary():
string
Defined in: src/tsa/document.ts:280
One-line human summary of compatibility.
Returns
string
Inherited from
IWorkDocument.compatibilitySummary
drawables()
drawables():
DrawableModel[]
Defined in: src/tsa/document.ts:192
Every object that carries drawable geometry (shapes, images, boxes).
Returns
Inherited from
images()
images():
ImageModel[]
Defined in: src/tsa/document.ts:212
Every image, with filter/mask access (see ImageModel).
Returns
Inherited from
moveSheet()
moveSheet(
from,to):void
Defined in: src/numbers/document.ts:232
Move a sheet to a new position in tab order.
Parameters
from
number
to
number
Returns
void
Agent Tool
manage_sheets
object()
object(
id):IwaObject|undefined
Defined in: src/tsa/document.ts:235
Parameters
id
bigint
Returns
IwaObject | undefined
Inherited from
pruneRoots()
protectedpruneRoots():bigint[]
Defined in: src/tsa/document.ts:322
Objects that must survive compact.
The package metadata anchors the component and data tables, and each component's first object anchors that component — a component whose objects all vanished would still be listed in the metadata, which is a worse state than a few extra archives.
Returns
bigint[]
Inherited from
removeSheet()
removeSheet(
index):void
Defined in: src/numbers/document.ts:202
Remove a sheet from the document's tab order.
Parameters
index
number
Returns
void
Agent Tool
manage_sheets
removeTable()
removeTable(
sheetId,tableInfoId):boolean
Defined in: src/numbers/document.ts:314
Take a table off its sheet.
The archives stay in the package, as everywhere else here; what removes the table is the sheet no longer listing it.
Parameters
sheetId
bigint
tableInfoId
bigint
Returns
boolean
renameSheet()
renameSheet(
index,name):void
Defined in: src/numbers/document.ts:217
Rename a sheet. Names must be unique, as they are in the app.
Parameters
index
number
name
string
Returns
void
Agent Tool
manage_sheets
save()
save():
Uint8Array
Defined in: src/tsa/document.ts:341
Returns
Uint8Array
Inherited from
sheetContainer()
sheetContainer(
sheetId):DrawableContainer
Defined in: src/numbers/document.ts:145
A sheet's drawable list — tables, charts, shapes and images alike.
Numbers keeps one list with no separate z-order, so paint order is the list order.
Parameters
sheetId
bigint
Returns
sheets()
sheets():
SheetInfo[]
Defined in: src/numbers/document.ts:128
The document's sheets (id + name), in tab order.
Returns
stats()
stats():
DocumentStats
Defined in: src/tsa/document.ts:243
Returns
Inherited from
stylesheets()
stylesheets():
StylesheetModel[]
Defined in: src/tsa/document.ts:183
All stylesheets (document + theme).
Returns
Inherited from
tables()
tables(
sheetId?):TableModel[]
Defined in: src/numbers/document.ts:115
Tables of one sheet, or of the whole document when no sheet is given.
Parameters
sheetId?
bigint
Returns
Overrides
tablesOnSheet()
tablesOnSheet(
sheetId):TableModel[]
Defined in: src/numbers/document.ts:251
The tables on one sheet, in the order the sheet lists them.
Parameters
sheetId
bigint
Returns
textStorages()
textStorages(
kind?):TextStorage[]
Defined in: src/tsa/document.ts:172
Every text storage in the document (bodies, headers, cells, notes …).
Parameters
kind?
number
Returns
Inherited from
typeNameOf()
typeNameOf(
obj):string|undefined
Defined in: src/tsa/document.ts:239
Parameters
obj
Returns
string | undefined
Inherited from
blank()
staticblank():NumbersDocument
Defined in: src/numbers/document.ts:110
A new, empty Numbers spreadsheet — one sheet, one table, A4 paper, no template file needed.
The embedded donor is an Apple-written corpus fixture (already iso-a4) emptied by blankFrom, so every style and identity in the "new" document was authored by an Apple app. scripts/make-blanks.ts records its provenance.
Returns
NumbersDocument
Agent Tool
create_document
blankFrom()
staticblankFrom(template,options?):NumbersDocument
Defined in: src/numbers/document.ts:67
A new, empty spreadsheet built from a document you supply.
There is no from-nothing constructor, and there will not be one. A Numbers document is dozens of interlinked archives — theme, stylesheet, calc-engine owners, table styles — and inventing that graph would produce a file nothing offline could validate. What is safe is emptying a real one: every identity, style and reference stays exactly as an Apple app wrote it, and only the content goes.
The result keeps one sheet holding one blank table, laid out like the template's first. Everything else — extra sheets, extra tables, their data — is removed.
Reach for a document you own or one the user hands you; any .numbers will do, including an empty one saved from Numbers.
Parameters
template
Uint8Array
options?
sheetName?
string
tableName?
string
Returns
NumbersDocument
load()
staticload(bytes):NumbersDocument
Defined in: src/numbers/document.ts:39
Parameters
bytes
Uint8Array
Returns
NumbersDocument
loadStore()
protectedstaticloadStore(bytes,app,extractors):object
Defined in: src/tsa/document.ts:152
Parameters
bytes
Uint8Array
app
extractors
ReadonlyMap<number, ReferenceExtractor>
Returns
object
container
container:
IWorkContainer
store
store:
ObjectStore
Inherited from
open()
staticopen(bytes):IWorkDocument
Defined in: src/tsa/document.ts:139
Load any modern iWork document, auto-detecting the app. Prefer the app subclasses' load when the type is known — they expose richer APIs.
Parameters
bytes
Uint8Array