SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface ConstructorOptions

    Options available when creating an IWorkbook.

    interface ConstructorOptions {
        calcOnLoad?: CalcOnLoad;
        calculation?: ICalculation;
        createSheetCallback?: CreateSheetCallback;
        createSheetNameCallback?: (index: number) => string;
        disableLoadAutoFit?: boolean;
        externalBookResolver?: IResolver;
        functions?: readonly FunctionProvider[];
        json?: IWorkbook.JSON;
        names?: INamedCollection;
        opener?: (url: string, target?: string, features?: string) => void;
        origin?: string | IWorkbookIO.Origin | IWorkbookIO.OriginProvider | null;
        readonly?: boolean;
        resolveRange?: (address?: ICellRange.Address) => ICellRange | null;
        resources?: IResourceCollection;
        runtime?: IRuntime;
        strings?: IStringCollection;
        styles?: IStyleCollection;
        theme?: ITheme;
        transactions?: IStore;
        workbook?: IWorkbook;
    }

    Hierarchy (View Summary)

    Index
    calcOnLoad? calculation? createSheetCallback? createSheetNameCallback? disableLoadAutoFit? externalBookResolver? functions? json? names? opener? origin? readonly? resolveRange? resources? runtime? strings? styles? theme? transactions? workbook?
    calcOnLoad?: CalcOnLoad

    What loading is allowed to calculate.

    'auto'

    • 'auto' — the engine starts, cached values are trusted, and the load pass runs: a formula cell with no cached value is evaluated (a repair) and volatiles refresh. Everything is recalculated only when the file asks (json.calc.fullCalcOnLoad, workbooks only).
    • 'full' — as 'auto', then everything is recalculated.
    • 'none' — the engine is not started. Nothing is compiled or calculated; values stand as loaded and formulas pass through to a save exactly as read. The first mutation, or an explicit ICalculation.calculate / IWorkbook.whenCalculationReady, starts the engine and applies what was deferred. Until then a formula READ answers null.

    Ignored when calculation is provided — a borrowed engine is started by its owner.

    calculation?: ICalculation

    Option to provide a custom calculation.

    Supplying one hands the container an engine it does not own. functions, formulaTransform and calcOnLoad describe how to build the engine the container owns, so they are ignored when this is provided.

    createSheetCallback?: CreateSheetCallback

    Hook to allow for custom sheet creation.

    createSheetNameCallback?: (index: number) => string

    Returns a human readable sheet name given a 0-based index.

    Sheet${index+1}

    disableLoadAutoFit?: boolean

    If true then the initial autoFit will not be called.

    false

    This is useful when loading large sheets where autoFit may be expensive and the font's are well known.

    • Excel does this with an attribute in the XML knownFonts.
    externalBookResolver?: IResolver

    Opens the source of an external book on IExternalBook.refresh — see IExternalBook.IResolver for what it answers and the trust boundary it sits behind.

    Fixed for the workbook's life, as the engine it feeds is: a resolver is part of how a host sets a workbook up, not a setting a document carries. Without one every refresh answers 'unavailable' and the caches stand. Ignored when calculation is provided.

    functions?: readonly FunctionProvider[]

    Additional custom formula function providers, bound after the built-ins (so they override built-ins on name collision). Each provider is the initialize binder produced by the FormulaCompiler (@sheetxl/scripting) for a folder of formula sources.

    Ignored when calculation is provided.

    FunctionProvider

    json?: IWorkbook.JSON

    Load from JSON.

    names?: INamedCollection

    Option to provide shared names.

    This is not the interface because we want the instance that allows for adding items other than named ranges.

    opener?: (url: string, target?: string, features?: string) => void

    Opens an external hyperlink (e.g. an http(s)/mailto cell link).

    window.open

    In-sheet #... navigation is resolved internally and never reaches this callback. Override it to route links through a host that cannot use window.open — e.g. a VS Code webview or an Electron shell — which open links via their own shell API. On a workbook this applies to all of its sheets.

    origin?: string | IWorkbookIO.Origin | IWorkbookIO.OriginProvider | null

    The IWorkbookIO.Origin the workbook maps to — threaded through by the IO layer at read time. Omit for an in-memory workbook (an unbound origin is minted). A string is shorthand for an unbound origin with that display name.

    The initial origin; a save that resolves a new destination replaces it (see IWorkbook.getOrigin).

    A host with its own save flow can pass an IWorkbookIO.OriginProvider instead and move it itself; the IO layer then leaves the workbook's origin to that host.

    readonly?: boolean

    If true then the model is readonly and cannot be save.

    false

    Useful when you want to load a model for viewing only and prevent any accidental changes.

    resolveRange?: (address?: ICellRange.Address) => ICellRange | null

    Allows for address to be resolved in custom ways.

    • This should return null if unresolvable but only throw and error if it is identified a a parsing error.
    • This is used by INamedCollection to created named ranges.
    resources?: IResourceCollection

    Option to provide shared resources.

    runtime?: IRuntime

    Initialize a cell container with a pre-defined runtime.

    strings?: IStringCollection

    Option to provide shared strings.

    styles?: IStyleCollection

    Option to provide a shared StyleCollection. If not provided then a new StyleCollection with default theming will be used.

    theme?: ITheme

    A theme for the workbook.

    transactions?: IStore

    The store for all state changes. This is provided to enable versioning, undo/redo, distributed editing, etc.

    If not specified then an internal ITransaction.IStore will be created.

    workbook?: IWorkbook

    If the parent has a workbook

    Settings
    Member Visibility

    On This Page
    Properties