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

    Interface ICell

    A single unit of data and meta data within an ICellRange, located at a specific row and column.

    interface ICell {
        isICell: true;
        createCell(modifiers: ICell.Update, options?: CreateCellOptions): ICell;
        getAddress(r1c1?: boolean): string;
        getBestFit(
            colWidth?: number,
            minContent?: boolean,
        ): Readonly<Partial<Size>> | null;
        getCalculationStatus(): ICalculation.ResultStatus;
        getCircularReference(): ICircularReference | null;
        getColumn(): IColumn | null;
        getComments(): IComment | null;
        getConditionalDecorations(): Readonly<Decorations>;
        getCoords(): Readonly<IRange.CellCoords>;
        getDataValidation(): IDataValidation | null;
        getDate(): Date | null;
        getDependents(): Promise<ICellRanges | null>;
        getDirectDependents(): Promise<ICellRanges | null>;
        getDirectPrecedents(): Promise<ICellRanges | null>;
        getErrors(): readonly string[];
        getExtrusions(): Readonly<Coords> | null;
        getFormula(options?: FormulaTextOptions): IFormula | null;
        getFormulaText(options?: FormulaTextOptions): string | null;
        getHyperlink(): IHyperlink | null;
        getInsets(): Readonly<Rectangle>;
        getInteropType(): InteropScalarType;
        getInteropValue(): InteropScalar;
        getNumberFormat(override?: string): Parsed;
        getPrecedents(): Promise<ICellRanges | null>;
        getProtection(): ICellProtection;
        getRange(): ICellRange;
        getRenderHorizontalAlignment(): ITextFrame.HorizontalAlignment;
        getSheet(): ISheet;
        getSpans(): Readonly<Size>;
        getSpill(): ICellRange | null;
        getSpillKind(): FormulaArrayKind | null;
        getStyle(direct?: boolean): IStyle;
        getTable(): ITable | null;
        getText(options?: GetTextOptions): string;
        getTextFrame(useFormula?: boolean): ITextFrame | null;
        getTextOverflow(): Readonly<HorizontalOverflow> | null;
        getTextPlacement(size: Size, useFormula?: boolean): TextPlacement | null;
        getType(): ScalarType;
        getValue(): Scalar;
        getWarnings(): readonly string[];
        isContentful(): boolean;
        isEditAllowed(): boolean;
        isEmpty(): boolean;
        isEqual(other: ICell): boolean;
        isFormulaHidden(): boolean;
        isSpillOverflow(): boolean;
        isTopLeft(): boolean;
        select(options?: ITypes.SelectOptions): Promise<boolean>;
    }
    Index
    isICell
    createCell getAddress getBestFit getCalculationStatus getCircularReference getColumn getComments getConditionalDecorations getCoords getDataValidation getDate getDependents getDirectDependents getDirectPrecedents getErrors getExtrusions getFormula getFormulaText getHyperlink getInsets getInteropType getInteropValue getNumberFormat getPrecedents getProtection getRange getRenderHorizontalAlignment getSheet getSpans getSpill getSpillKind getStyle getTable getText getTextFrame getTextOverflow getTextPlacement getType getValue getWarnings isContentful isEditAllowed isEmpty isEqual isFormulaHidden isSpillOverflow isTopLeft select
    isICell: true

    For runtime type checking.

    • Returns the address of the cell in either A1 or R1C1 format.

      Parameters

      • Optionalr1c1: boolean

        If unspecified defaults to the environment's default format.

      Returns string

    • Calculates the optimal size required to display the cell's content.

      Parameters

      • OptionalcolWidth: number

        The column width, used for text wrapping calculations. Default value the current column width.

      • OptionalminContent: boolean

        If true, calculates the size using the min width possible. For decimal numbers this will round.

      Returns Readonly<Partial<Size>> | null

      Returns null if this cell should be ignored for sizing purposes. Either dimension can also be null, indicating that the specific direction should not be used.

    • The reference cycle this cell is in, or downstream of — or null when it is neither.

      Returns ICircularReference | null

      Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is 0 (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle whether this cell is a member or a reader (ICalculation.ICircularReference.isMember) and, under iterative calculation, whether it converged.

      The range-level view is ICellRange.Feature.Circular — getCounts for how many cells, getRegions for which, each region carrying this same object as its payload.

    • Returns the comment on the cell, or null if there is none.

      Returns IComment | null

      One per cell — the thread's root, with its replies, or a note. The sheet's ISheet.getComments is where one is added.

    • Returns what the cell's conditional formatting DRAWS in it — an in-cell bar, an icon, or neither.

      Returns Readonly<Decorations>

      The rules that restyle a cell need no accessor: they are already folded into ICell.getStyle. These two do not restyle — they paint their own mark — so they need a channel of their own, and this is it. Answers are render-ready: a bar arrives as a position on its track, an icon as a band already chosen.

      A bar and an icon can BOTH apply (Excel draws the icon over the bar), which is why this returns a slot per kind. Within a kind the first rule in evaluation order wins, and a stopIfTrue rule ends the walk exactly as it does for styles — which no scale rule ever does, however the file was authored.

      The gutter an icon needs is already reflected in ICell.getInsets, so a caller that only lays out text does not need to read this at all.

    • Returns the CellCoords.

      Returns Readonly<IRange.CellCoords>

    • Returns the cell's primary data validation: the highest-priority one that covers it, or null when none does.

      Returns IDataValidation | null

      Validations may overlap, and every one that covers the cell applies; see ICellRange.getDataValidations for all of them. The primary one is also the one Excel honors when it opens a file whose validations overlap.

    • Returns the cell's value as a JavaScript Date object if the cell contains a date.

      Returns Date | null

      Only returns a date if the number formatting is a date format and the cell's value can be interpreted as a valid JavaScript Date. Otherwise, returns null.

    • Returns all cells that are eventually affected by this cell, including those that depend on it indirectly through the full calculation chain.

      Returns Promise<ICellRanges | null>

      This performs a recursive search downstream to find the total impact of a value change. Resolves null if the cell has no dependents.

    • Returns the cells that directly reference this cell in their own formulas.

      Returns Promise<ICellRanges | null>

      These represent the immediate consumers of this cell's value. Resolves null if the cell has no dependents.

    • Returns the ranges immediately referenced by this cell's formula.

      Returns Promise<ICellRanges | null>

      These represent the direct inputs required to compute the cell's value. Resolves null if the cell has no precedents. A question for the calculation engine: it resolves once the engine has answered, in order behind the writes made before it, and with null while the engine is Off.

    • Retrieves any errors attached to the cell.

      Returns readonly string[]

    • Returns the extruding range of the cell if it extends beyond its original coordinates.

      Returns Readonly<Coords> | null

      Useful for cells that have been merged or have text overflow. This can also be included when iterating ranges with the extendedRange flag set to true.

    • Returns the hyperlink assigned to the cell.

      Returns IHyperlink | null

      Returns null if no hyperlink is set.

    • Returns the padding around the cell's content.

      Returns Readonly<Rectangle>

      Insets do not affect the fill or background of the cell.

    • Returns the type of the cell as an InteropScalarType. (e.g., text, number, date).

      Returns InteropScalarType

      This method is useful for distinguishing between dates and numbers, as both are represented as numbers in the underlying data model. By using getInteropType(), you can determine if a numeric value should be treated as a date based on its formatting and context.

    • Returns the cell's value as an InteropScalar.

      Returns InteropScalar

    • Returns the cell's value as a string with additional number format details.

      Parameters

      • Optionaloverride: string

        A custom number format to apply (optional).

      Returns Parsed

      This method always returns a formatted string and never null.

    • Returns all ranges that contribute to this cell's value, including those referenced indirectly through the full calculation chain.

      Returns Promise<ICellRanges | null>

      This performs a recursive search upstream to find all root data sources. Resolves null if the cell has no precedents.

    • Returns the cell's protection format, the same as getStyle().getProtection().

      Returns ICellProtection

      Whether the cell can be edited right now also depends on its sheet and its unlocked ranges; see ICell.isEditAllowed.

    • Returns the range of the cell.

      Returns ICellRange

      Returns a range for a single cell. Temporary cells will have to return InvalidRange

    • Returns the appropriate horizontal alignment for rendering the cell's content.

      Returns ITextFrame.HorizontalAlignment

      • This takes into account both the style's alignment settings and the type of data in the cell.
      • While this returns ITextFrame.HorizontalAlignment type it only uses 'left', 'right', and 'center' values, as 'general' is resolved to left or right based on the cell's content type.

    • Returns the span dimensions for merged cells.

      Returns Readonly<Size>

    • Returns the range of the cell if it is a spill cell.

      Returns ICellRange | null

    • Returns which kind of array block the cell belongs to, or null if it is not part of one.

      Returns FormulaArrayKind | null

      Answers for every cell of the block, not only the anchor — a fixed (array-entered) block shows {=…} on all of its cells, as Excel does.

    • Returns the style information applied to the cell.

      Parameters

      • Optionaldirect: boolean

        Only the style directly applied to the cell.

      Returns IStyle

      If true, Returns the style directly set on the cell. Otherwise, returns the rendered style, which may include effects like conditional or table formatting.

    • If the cell is in a table this will return it.

      Returns ITable | null

    • Returns the cell's value as a formatted string, applying any number formatting.

      Parameters

      Returns string

    • Retrieves a ITextFrame containing text layout details, such as wrapping and alignment.

      Parameters

      • OptionaluseFormula: boolean

        If true this will return a text frame for formula (if there is one).

      Returns ITextFrame | null

      Returns null if the cell does not contain text or does not contain a formula. This includes text formatting, rich text, and number formatting.

    • Returns the overflow details for the cell's text overflow or null if the cell does not overflow.

      Returns Readonly<HorizontalOverflow> | null

      • This will only return a value if iterating using ICellRange.Orientation.Row.

    • Resolve where this cell's text is placed within a cell box of size — applying the cell's insets and vertical/horizontal alignment. This is the single source of truth for content placement, shared by the cell renderer and the inline editor so they align exactly.

      Parameters

      • size: Size

        The cell box in logical (un-zoomed) px.

      • OptionaluseFormula: boolean

        If true, place the formula text (when there is one).

      Returns TextPlacement | null

      All returned geometry is logical px in cell-local coordinates (origin = the cell's top-left). An empty cell still resolves its content box and line height (from the style font) with a zero-width text block — so a caret placed in a blank cell lands consistently. Vertical Justify/Distributed anchor at the content top here; per-line distribution remains a renderer concern.

    • Returns the type of the cell (e.g., text, number).

      Returns ScalarType

    • Returns the value of the cell.

      Returns Scalar

      Returns null if the cell has no value.

    • Retrieves any warnings attached to the cell.

      Returns readonly string[]

      Warnings differ from errors in that they may alter the display of the cell's value or type. A cell in a reference cycle, or downstream of one, carries one here — the text form of getCircularReference: the walk from this cell around the cycle and back ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".

    • Returns true if the cell contains a value.

      Returns boolean

      A cell can be contentful even if it has no value but contains styling or other characteristics like row/col spans or borders.

    • Returns true if the cell is read-only.

      Returns boolean

      A cell can be read-only due to protection or other reasons.

    • Returns true if the cell is empty, meaning it has no value and its style is set to 'Normal'.

      Returns boolean

      ICell.isContentful

    • Compares the current cell to another instance to determine if they are logically equal.

      Parameters

      • other: ICell

        The cell to compare to.

      Returns boolean

      • To be equal the cells must have the same values and be at the same address.
      • Useful when ICells are dynamically generated because '===' comparison is not valid.

    • Returns true if protection hides this cell's formula.

      Returns boolean

      The sheet is protected (not paused), and neither the sheet's showFormulas nor the cell style's allows it. A hidden formula reads as no formula: ICell.getFormula and ICell.getFormulaText return null. It still calculates, and is still saved with the workbook.

    • Returns true if the cell is a spill and not the top left.

      Returns boolean

    • Returns true if the cell is the top-left cell of a merged region, or if it is not part of a merged region.

      Returns boolean

    • Selects the current cell.

      Parameters

      Returns Promise<boolean>

      An async boolean indicating the cell was selected.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods