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

    Interface INamed<T>

    Defined names are descriptive texts that are used to represents a cell, range of cells, formula, or constant value.

    interface INamed<T = any> {
        isIModel: true;
        isINamed: true;
        addListeners(
            listeners: INamed.IListeners,
            options?: IListener.Options,
        ): Remove;
        beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
        close(): void;
        delete?(options?: ITransaction.OperationOptions): void;
        doBatch<R = any>(
            callback: (commit: ICommit) => R | Promise<R>,
            options?: string | ITransaction.OperationOptions,
        ): R | Promise<R>;
        getComment(): string | null;
        getId(): string;
        getName(): string;
        getPartReference?(
            coords: readonly Coords[],
            home?: CellCoords | null,
        ): string | null;
        getRanges?(): ICellRanges | null;
        getScope(): string | null;
        getType(): string;
        getValue(): T;
        getVersionId(): number;
        isClosed(): boolean;
        isDeleted(): boolean;
        isHidden(): boolean;
        isReadOnly(): boolean;
        select(options?: ITypes.SelectOptions): Promise<INamed<T>>;
        setComment(
            comment: string | null,
            options?: ITransaction.OperationOptions,
        ): this;
        setHidden?(hidden: boolean, options?: ITransaction.OperationOptions): this;
        setName(name: string, options?: ITransaction.OperationOptions): this;
        toJSON?(): INamed.JSON | null;
    }

    Type Parameters

    • T = any

    Hierarchy (View Summary)

    Index
    isIModel isINamed
    addListeners beginCommit close delete? doBatch getComment getId getName getPartReference? getRanges? getScope getType getValue getVersionId isClosed isDeleted isHidden isReadOnly select setComment setHidden? setName toJSON?
    isIModel: true

    For runtime type checking.

    isINamed: true

    For runtime type checking.

    • Batches all 'transactional' changes until they have all be committed or rolled back.

      Parameters

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns ITransaction

      Any changes that are made to this object will be reflected in the local record but not committed to the transactional store until the batch is popped.

      Useful for operations that are longer running but generally not recommended as it keeps a transaction open. doBatch is the preferred option.

    • Close the record and cleans resources. Can't be undone.

      Returns void

    • Provides a mechanism to perform a set of operations in a batch.

      Type Parameters

      • R = any

      Parameters

      • callback: (commit: ICommit) => R | Promise<R>

        A callback that performs multiple operations all within the same transaction.

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns R | Promise<R>

      Writes are tracked automatically: a batch that performs no state updates (a read-only batch) is elided — the commit id is unchanged, no events fire, and nothing is added to the undo stack or commit log.

    • setComment

      Returns string | null

      The comment or null if none has been set.

    • A unique stable id.

      Returns string

    • setName

      Returns string

    • A reference to a part of this item that the given coords designate exactly, or null.

      Parameters

      • coords: readonly Coords[]

        The coords to match, sheet-qualified (scope) and in row-first order.

      • Optionalhome: CellCoords | null

        The cell of the formula the reference is for, when there is one. A reference can be written relative to it: Sales[@Amount] for a table cell in the formula's own row, and from inside the table [@Amount] and [Amount].

      Returns string | null

      • Optional

      Backs INamedCollection.getByRanges with includeParts. Some named things address regions that are not themselves names: a table's column is written Sales[Amount], its header row Sales[#Headers]. Those are structured references, not entries in the collection — there is no INamed to return for one, which is why this returns text rather than an item.

      Implemented by whatever owns the parts (a table), so the collection stays out of the business of knowing what kinds of items have insides.

    • Return the ranges that are associated with the named item or null if no ranges are available.

      Returns ICellRanges | null

      • Optional — but only at this level of the hierarchy. Every defined name implements it (ICalculation.INamedFormula redeclares it as required), so a caller holding one does not need a guard. Optionality here is what lets a named thing that designates no cells exist at all; it is not an invitation to reach for ?.() on a name.

    • A string identifying the scope. This is normally a sheet name.

      Returns string | null

      If null then this will be treated as a global scope.

      Read-only — there is deliberately no setScope. Scope is half a name's identity, not a property of it: it decides the symbol the definition compiles into, so Total and Sheet1!Total are two names rather than one name in two states. Excel takes the same line — its Name object has no scope property, the Name Manager greys the dropdown out when editing, and assigning a prefixed string to .Name does not move a name (Excel re-applies the original scope, turning One!Beta into One!One!Beta).

      To change scope, delete the name and define it again in the new one — which is also what dependent formulas expect, since they re-resolve by name.

    • A string to identify the type of named item.

      Returns string

      Immutable

    • The underlying item that is being referenced.

      Returns T

      Immutable

      What T is depends on getType, and for the common case it is text. A defined name (type 'formula') is an ICalculation.INamedFormula, so this is its refers-to EXPRESSION as a string with no leading = — Sheet1!$B$4, or 0.21 for a name holding a constant. A table's is the ITable. It is never the target: the string Sheet1!$B$4 is what the name says, not the cells it designates and not what they contain.

      The two questions this is mistaken for have their own calls:

      • Which cells? getRanges — the ranges, or null for a name holding an expression.
      • What is it worth right now? ICalculation.IFormula.evaluate(), which every named formula has. Returns a Scalar for a value name and an IRange for a reference one, so there is no parse-the-text-and-re-query hop. Note that a name written with relative references evaluates per calling CELL, so its one anchored answer is not the answer every dependent sees.

    • Every committed update gives the record a new, strictly increasing version id.

      Returns number

      Used with getId to uniquely identify a version of the record.

      The id is an identity, not a per-record count: ids are drawn from a single store-wide sequence bumped once per commit, so all records written in the same commit share an id and a given record's ids increase but are not sequential.

      Records are immutable so a restore/revert doesn't change them — it repoints, and the version id reported is the one for the snapshot the store is currently at. Version ids are never reused: a write after an undo receives an id higher than any previously issued, so a stale reader can always detect the change.

    • Returns true if no more operations are allowed.

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    • setHidden

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    Settings
    Member Visibility

    On This Page
    Properties
    Methods