Cell

Cell class

Encapsulates the object that represents a single Workbook cell.

class Cell;

Methods

MethodDescription
getWorksheet()Gets the parent worksheet.
getDateTimeValue()Gets the DateTime value contained in the cell.
getRow()Gets row number (zero based) of the cell.
getColumn()Gets column number (zero based) of the cell.
isFormula()Represents if the specified cell contains formula.
getType()Represents cell value type.
getName()Gets the name of the cell.
isErrorValue()Checks if the value of this cell is an error.
isNumericValue()Indicates whether the value of this cell is numeric(int, double and datetime)
getNumberCategoryType()Represents the category type of this cell’s number formatting.
getDisplayStringValue()Gets the formatted string value of this cell by cell’s display style.
getIntValue()Gets the integer value contained in the cell.
getDoubleValue()Gets the double value contained in the cell.
getFloatValue()Gets the float value contained in the cell.
getBoolValue()Gets the boolean value contained in the cell.
getHasCustomStyle()Indicates whether this cell has custom style settings(different from the default one inherited from corresponding row, column, or workbook).
getSharedStyleIndex()Gets cell’s shared style index in the style pool.
setFormula(string)Gets or sets a formula of the Cell.
getFormulaLocal()Get the locale formatted formula of the cell.
setFormulaLocal(string)Get the locale formatted formula of the cell.
getR1C1Formula()Gets or sets a R1C1 formula of the Cell.
setR1C1Formula(string)Gets or sets a R1C1 formula of the Cell.
getContainsExternalLink()Indicates whether this cell contains an external link. Only applies when the cell is a formula cell.
isArrayHeader()Indicates the cell’s formula is an array formula and it is the first cell of the array.
isDynamicArrayFormula()Indicates whether the cell’s formula is dynamic array formula(true) or legacy array formula(false).
isArrayFormula()Indicates whether the cell formula is an array formula.
isSharedFormula()Indicates whether the cell formula is part of shared formula.
isTableFormula()Indicates whether this cell is part of table formula.
isStyleSet()Indicates if the cell’s style is set. If return false, it means this cell has a default cell format.
isMerged()Checks if a cell is part of a merged range or not.
getComment()Gets the comment of this cell.
setHtmlString(string)Gets and sets the html string which contains data and some formats in this cell.
getEmbeddedImage()Gets and sets the embeddedn image in the cell.
setEmbeddedImage(number[])Gets and sets the embeddedn image in the cell.
calculate(CalculationOptions)Calculates the formula of the cell.
putValue(boolean)Puts a boolean value into the cell.
putValue(number)Puts an integer value into the cell.
putValue(number)Puts a double value into the cell.
putValue(string, boolean, boolean)Puts a value into the cell, if appropriate the value will be converted to other data type and cell’s number format will be reset.
putValue(string, boolean)Puts a string value into the cell and converts the value to other data type if appropriate.
putValue(string)Puts a string value into the cell.
putValue(Date)Puts a DateTime value into the cell.
getStringValue(CellValueFormatStrategy)Gets the string value by specific formatted strategy.
getWidthOfValue()Gets the width of the value in unit of pixels.
getHeightOfValue()Gets the height of the value in unit of pixels.
getDisplayStyle()Gets the display style of the cell. If this cell is also affected by other settings such as conditional formatting, list objects, etc., then the display style may be different from cell.GetStyle().
getDisplayStyle(boolean)Gets the display style of the cell. If the cell is conditional formatted, the display style is not same as the cell.GetStyle().
getFormatConditions()Gets format conditions which applies to this cell.
getStyle()Gets the cell style.
getStyle(boolean)If checkBorders is true, check whether other cells’ borders will effect the style of this cell.
setStyle(Style)Sets the cell style.
setStyle(Style, boolean)Apply the changed property of style to the cell.
setStyle(Style, StyleFlag)Apply the cell style based on flags.
getFormula(boolean, boolean)Get the formula of this cell.
setArrayFormula(string, number, number)Sets an array formula(legacy array formula entered via CTRL+SHIFT+ENTER in ms excel) to a range of cells.
setArrayFormula(string, number, number, FormulaParseOptions)Sets an array formula to a range of cells.
setSharedFormula(string, number, number)Sets shared formulas to a range of cells.
setSharedFormula(string, number, number, FormulaParseOptions)Sets shared formulas to a range of cells.
getPrecedents()Gets all references appearing in this cell’s formula.
getDependents(boolean)Get all cells whose formula references to this cell directly.
getPrecedentsInCalculation()Gets all precedents(reference to cells in current workbook) used by this cell’s formula while calculating it.
getDependentsInCalculation(boolean)Gets all cells whose calculated result depends on this cell.
getArrayRange()Gets the array range if the cell’s formula is an array formula.
setDynamicArrayFormula(string, FormulaParseOptions, boolean)Sets dynamic array formula and make the formula spill into neighboring cells if possible.
removeArrayFormula(boolean)Remove array formula.
copy(Cell)Copies data from a source cell.
characters(number, number)Returns a Characters object that represents a range of characters within the cell text.
replace(string, string, ReplaceOptions)Replace text of the cell with options.
insertText(number, string)Insert some characters to the cell. If the cell is rich formatted, this method could keep the original formatting.
isRichText()Indicates whether the string value of this cell is a rich formatted text.
getCharacters()Returns all Characters objects that represents a range of characters within the cell text.
getCharacters(boolean)Returns all Characters objects that represents a range of characters within the cell text.
setCharacters(FontSetting[])Sets rich text format of the cell.
getMergedRange()Returns a Range object which represents a merged range.
getHtmlString(boolean)Gets the html string which contains data and some formats in this cell.
toString()Returns a string represents the current Cell object.
toJson()Convert Cell to JSON struct data.
getHashCode()Serves as a hash function for a particular type.
equals(Cell)Checks whether this object refers to the same cell with another cell object.
getConditionalFormattingResult()Get the result of the conditional formatting.
getValidation()Gets the validation applied to this cell.
getValidationValue()Gets the value of validation which applied to this cell.
getTable()Gets the table which contains this cell.
dispose()

getWorksheet()

Gets the parent worksheet.

getWorksheet() : Worksheet;

Returns

Worksheet

getDateTimeValue()

Gets the DateTime value contained in the cell.

getDateTimeValue() : Date;

getRow()

Gets row number (zero based) of the cell.

getRow() : number;

getColumn()

Gets column number (zero based) of the cell.

getColumn() : number;

isFormula()

Represents if the specified cell contains formula.

isFormula() : boolean;

getType()

Represents cell value type.

getType() : CellValueType;

Returns

CellValueType

getName()

Gets the name of the cell.

getName() : string;

Remarks

A cell name includes its column letter and row number. For example, the name of a cell in row 0 and column 0 is A1.

isErrorValue()

Checks if the value of this cell is an error.

isErrorValue() : boolean;

Remarks

Also applies to formula cell to check whether the calculated result is an error.

isNumericValue()

Indicates whether the value of this cell is numeric(int, double and datetime)

isNumericValue() : boolean;

Remarks

Also applies to formula cell to check the calculated result

getNumberCategoryType()

Represents the category type of this cell’s number formatting.

getNumberCategoryType() : NumberCategoryType;

Returns

NumberCategoryType

Remarks

When cell’s formatting pattern is combined with conditional formatting patterns, then the returned type is corresponding to the part which is used for current value of this cell. For example, if the formatting pattern for this cell is “#,##0;(#,##0);”-";@", then when cell’s value is numeric and not 0, the returned type is NumberCategoryType.Number; When cell’s value is 0 or not numeric value, the returned type is NumberCategoryType.Text.

getDisplayStringValue()

Gets the formatted string value of this cell by cell’s display style.

getDisplayStringValue() : string;

getIntValue()

Gets the integer value contained in the cell.

getIntValue() : number;

getDoubleValue()

Gets the double value contained in the cell.

getDoubleValue() : number;

getFloatValue()

Gets the float value contained in the cell.

getFloatValue() : number;

getBoolValue()

Gets the boolean value contained in the cell.

getBoolValue() : boolean;

getHasCustomStyle()

Indicates whether this cell has custom style settings(different from the default one inherited from corresponding row, column, or workbook).

getHasCustomStyle() : boolean;

getSharedStyleIndex()

Gets cell’s shared style index in the style pool.

getSharedStyleIndex() : number;

setFormula(string)

Gets or sets a formula of the Cell.

setFormula(value: string) : void;

Parameters:

ParameterTypeDescription
valuestringThe value to set.

Remarks

A formula string always begins with an equal sign (=). And please always use comma(,) as parameters delimiter, such as “=SUM(A1, E1, H2)”.

getFormulaLocal()

Get the locale formatted formula of the cell.

getFormulaLocal() : string;

setFormulaLocal(string)

Get the locale formatted formula of the cell.

setFormulaLocal(value: string) : void;

Parameters:

ParameterTypeDescription
valuestringThe value to set.

getR1C1Formula()

Gets or sets a R1C1 formula of the Cell.

getR1C1Formula() : string;

setR1C1Formula(string)

Gets or sets a R1C1 formula of the Cell.

setR1C1Formula(value: string) : void;

Parameters:

ParameterTypeDescription
valuestringThe value to set.

Indicates whether this cell contains an external link. Only applies when the cell is a formula cell.

getContainsExternalLink() : boolean;

isArrayHeader()

Indicates the cell’s formula is an array formula and it is the first cell of the array.

isArrayHeader() : boolean;

isDynamicArrayFormula()

Indicates whether the cell’s formula is dynamic array formula(true) or legacy array formula(false).

isDynamicArrayFormula() : boolean;

isArrayFormula()

Indicates whether the cell formula is an array formula.

isArrayFormula() : boolean;

isSharedFormula()

Indicates whether the cell formula is part of shared formula.

isSharedFormula() : boolean;

isTableFormula()

Indicates whether this cell is part of table formula.

isTableFormula() : boolean;

isStyleSet()

Indicates if the cell’s style is set. If return false, it means this cell has a default cell format.

isStyleSet() : boolean;

isMerged()

Checks if a cell is part of a merged range or not.

isMerged() : boolean;

getComment()

Gets the comment of this cell.

getComment() : Comment;

Returns

Comment

Remarks

If there is no comment applies to the cell, returns null.

setHtmlString(string)

Gets and sets the html string which contains data and some formats in this cell.

setHtmlString(value: string) : void;

Parameters:

ParameterTypeDescription
valuestringThe value to set.

getEmbeddedImage()

Gets and sets the embeddedn image in the cell.

getEmbeddedImage() : number[];

Returns

number[]

setEmbeddedImage(number[])

Gets and sets the embeddedn image in the cell.

setEmbeddedImage(value: number[]) : void;

Parameters:

ParameterTypeDescription
valuenumber[]The value to set.

calculate(CalculationOptions)

Calculates the formula of the cell.

calculate(options: CalculationOptions) : void;

Parameters:

ParameterTypeDescription
optionsCalculationOptionsOptions for calculation

putValue(boolean)

Puts a boolean value into the cell.

putValue(boolValue: boolean) : void;

Parameters:

ParameterTypeDescription
boolValueboolean

putValue(number)

Puts an integer value into the cell.

putValue(intValue: number) : void;

Parameters:

ParameterTypeDescription
intValuenumberInput value

putValue(number)

Puts a double value into the cell.

putValue(doubleValue: number) : void;

Parameters:

ParameterTypeDescription
doubleValuenumberInput value

putValue(string, boolean, boolean)

Puts a value into the cell, if appropriate the value will be converted to other data type and cell’s number format will be reset.

putValue(stringValue: string, isConverted: boolean, setStyle: boolean) : void;

Parameters:

ParameterTypeDescription
stringValuestringInput value
isConvertedbooleanTrue: converted to other data type if appropriate.
setStylebooleanTrue: set the number format to cell’s style when converting to other data type

putValue(string, boolean)

Puts a string value into the cell and converts the value to other data type if appropriate.

putValue(stringValue: string, isConverted: boolean) : void;

Parameters:

ParameterTypeDescription
stringValuestringInput value
isConvertedbooleanTrue: converted to other data type if appropriate.

putValue(string)

Puts a string value into the cell.

putValue(stringValue: string) : void;

Parameters:

ParameterTypeDescription
stringValuestringInput value

putValue(Date)

Puts a DateTime value into the cell.

putValue(dateTime: Date) : void;

Parameters:

ParameterTypeDescription
dateTimeDateInput value

Remarks

Setting a DateTime value for a cell dose not means the cell will be formatted as date time automatically. DateTime value was maintained as numeric value in the data model of both ms excel and Aspose.Cells. Whether the numeric value will be taken as the numeric value itself or date time depends on the number format applied on this cell. If this cell has not been formatted as date time, it will be displayed as a numeric value even though what you input is DateTime.

getStringValue(CellValueFormatStrategy)

Gets the string value by specific formatted strategy.

getStringValue(formatStrategy: CellValueFormatStrategy) : string;

Parameters:

ParameterTypeDescription
formatStrategyCellValueFormatStrategyThe formatted strategy.

getWidthOfValue()

Gets the width of the value in unit of pixels.

getWidthOfValue() : number;

getHeightOfValue()

Gets the height of the value in unit of pixels.

getHeightOfValue() : number;

getDisplayStyle()

Gets the display style of the cell. If this cell is also affected by other settings such as conditional formatting, list objects, etc., then the display style may be different from cell.GetStyle().

getDisplayStyle() : Style;

Returns

Style

getDisplayStyle(boolean)

Gets the display style of the cell. If the cell is conditional formatted, the display style is not same as the cell.GetStyle().

getDisplayStyle(includeMergedBorders: boolean) : Style;

Parameters:

ParameterTypeDescription
includeMergedBordersbooleanIndicates whether checking borders of the merged cells.

Returns

Style

getFormatConditions()

Gets format conditions which applies to this cell.

getFormatConditions() : FormatConditionCollection[];

Returns

Returns FormatConditionCollection object

getStyle()

Gets the cell style.

getStyle() : Style;

Returns

Style object.

Remarks

To change the style of the cell, please call Cell.SetStyle() method after modifying the returned style object. This method is same with GetStyle(bool) with true value for the parameter.

getStyle(boolean)

If checkBorders is true, check whether other cells’ borders will effect the style of this cell.

getStyle(checkBorders: boolean) : Style;

Parameters:

ParameterTypeDescription
checkBordersbooleanCheck other cells’ borders

Returns

Style object.

setStyle(Style)

Sets the cell style.

setStyle(style: Style) : void;

Parameters:

ParameterTypeDescription
styleStyleThe cell style.

Remarks

If the border settings are changed, the border of adjust cells will be updated too.

setStyle(Style, boolean)

Apply the changed property of style to the cell.

setStyle(style: Style, explicitFlag: boolean) : void;

Parameters:

ParameterTypeDescription
styleStyleThe cell style.
explicitFlagbooleanTrue, only overwriting formatting which is explicitly set.

setStyle(Style, StyleFlag)

Apply the cell style based on flags.

setStyle(style: Style, flag: StyleFlag) : void;

Parameters:

ParameterTypeDescription
styleStyleThe cell style.
flagStyleFlagThe style flag.

getFormula(boolean, boolean)

Get the formula of this cell.

getFormula(isR1C1: boolean, isLocal: boolean) : string;

Parameters:

ParameterTypeDescription
isR1C1booleanWhether the formula needs to be formatted as R1C1.
isLocalbooleanWhether the formula needs to be formatted by locale.

Returns

the formula of this cell.

setArrayFormula(string, number, number)

Sets an array formula(legacy array formula entered via CTRL+SHIFT+ENTER in ms excel) to a range of cells.

setArrayFormula(arrayFormula: string, rowNumber: number, columnNumber: number) : void;

Parameters:

ParameterTypeDescription
arrayFormulastringArray formula.
rowNumbernumberNumber of rows to populate result of the array formula.
columnNumbernumberNumber of columns to populate result of the array formula.

setArrayFormula(string, number, number, FormulaParseOptions)

Sets an array formula to a range of cells.

setArrayFormula(arrayFormula: string, rowNumber: number, columnNumber: number, options: FormulaParseOptions) : void;

Parameters:

ParameterTypeDescription
arrayFormulastringArray formula.
rowNumbernumberNumber of rows to populate result of the array formula.
columnNumbernumberNumber of columns to populate result of the array formula.
optionsFormulaParseOptionsOptions for parsing the formula.

setSharedFormula(string, number, number)

Sets shared formulas to a range of cells.

setSharedFormula(sharedFormula: string, rowNumber: number, columnNumber: number) : void;

Parameters:

ParameterTypeDescription
sharedFormulastringShared formula.
rowNumbernumberNumber of rows to populate the formula.
columnNumbernumberNumber of columns to populate the formula.

setSharedFormula(string, number, number, FormulaParseOptions)

Sets shared formulas to a range of cells.

setSharedFormula(sharedFormula: string, rowNumber: number, columnNumber: number, options: FormulaParseOptions) : void;

Parameters:

ParameterTypeDescription
sharedFormulastringShared formula.
rowNumbernumberNumber of rows to populate the formula.
columnNumbernumberNumber of columns to populate the formula.
optionsFormulaParseOptionsOptions for parsing the formula.

getPrecedents()

Gets all references appearing in this cell’s formula.

getPrecedents() : ReferredAreaCollection;

Returns

Collection of all references appearing in this cell’s formula.

Remarks

  • Returns null if this is not a formula cell.
  • All references appearing in this cell's formula will be returned no matter they are referenced or not while calculating. For example, although cell A2 in formula "=IF(TRUE,A1,A2)" is not used while calculating, it is still taken as the formula's precedents.
  • To get those references which influence the calculation only, please use [GetPrecedentsInCalculation()](../getprecedentsincalculation()/).

getDependents(boolean)

Get all cells whose formula references to this cell directly.

getDependents(isAll: boolean) : Cell[];

Parameters:

ParameterTypeDescription
isAllbooleanIndicates whether check formulas in other worksheets

Returns

Cell[]

Remarks

  • If one reference containing this cell appears in one cell's formula, that cell will be taken as the dependent of this cell, no matter the reference or this cell is used or not while calculating. For example, although cell A2 in formula "=IF(TRUE,A1,A2)" is not used while calculating, this formula is still be taken as A2's dependent.
  • To get those formulas whose calculated results depend on this cell, please use [GetDependentsInCalculation(bool)](../getdependentsincalculation(bool)/).
  • When tracing dependents for one cell, all formulas in the workbook or worksheet will be analized and checked. So it is a time consumed process. If user need to trace dependents for lots of cells, using this method will cause poor performance. For performance consideration, user should use [GetDependentsInCalculation(bool)](../getdependentsincalculation(bool)/) instead. Or, user may gather precedents map of all cells by [GetPrecedents()](../getprecedents()/) firstly, and then build the dependents map according to the precedents map.

getPrecedentsInCalculation()

Gets all precedents(reference to cells in current workbook) used by this cell’s formula while calculating it.

getPrecedentsInCalculation() : ReferredAreaEnumerator;

Returns

Enumerator to enumerate all references(ReferredArea)

Remarks

This method can only work with the situation that FormulaSettings.EnableCalculationChain is true for the workbook and the workbook has been fully calculated. If this cell is not a formula or it does not reference to any other cells, null will be returned.

getDependentsInCalculation(boolean)

Gets all cells whose calculated result depends on this cell.

getDependentsInCalculation(recursive: boolean) : CellEnumerator;

Parameters:

ParameterTypeDescription
recursivebooleanWhether returns those dependents which do not reference to this cell directly /// but reference to other leafs of this cell

Returns

Enumerator to enumerate all dependents(Cell objects)

Remarks

To use this method, please make sure the workbook has been set with true value for FormulaSettings.EnableCalculationChain and has been fully calculated with this setting. If there is no formula reference to this cell, null will be returned.

getArrayRange()

Gets the array range if the cell’s formula is an array formula.

getArrayRange() : CellArea;

Returns

The array range.

Remarks

Only applies when the cell’s formula is an array formula

setDynamicArrayFormula(string, FormulaParseOptions, boolean)

Sets dynamic array formula and make the formula spill into neighboring cells if possible.

setDynamicArrayFormula(arrayFormula: string, options: FormulaParseOptions, calculateValue: boolean) : CellArea;

Parameters:

ParameterTypeDescription
arrayFormulastringthe formula expression
optionsFormulaParseOptionsoptions to parse formula. /// “Parse” option will be ignored and the formula will always be parsed immediately
calculateValuebooleanwhether calculate this dynamic array formula for those cells in the spilled range.

Returns

the range that the formula should spill into.

Remarks

the returned range may be not same with the actual one that this dynamic array formula spills into. If there are non-empty cells in the range, the formula will be set for current cell only and marked as “#SPILL!”. But for such kind of situation we still return the whole range that this formula should spill into.

removeArrayFormula(boolean)

Remove array formula.

removeArrayFormula(leaveNormalFormula: boolean) : void;

Parameters:

ParameterTypeDescription
leaveNormalFormulabooleanTrue represents converting the array formula to normal formula.

copy(Cell)

Copies data from a source cell.

copy(cell: Cell) : void;

Parameters:

ParameterTypeDescription
cellCellSource Cell object.

characters(number, number)

Returns a Characters object that represents a range of characters within the cell text.

characters(startIndex: number, length: number) : FontSetting;

Parameters:

ParameterTypeDescription
startIndexnumberThe index of the start of the character.
lengthnumberThe number of characters.

Returns

Characters object.

Remarks

This method only works on cell with string value.

replace(string, string, ReplaceOptions)

Replace text of the cell with options.

replace(placeHolder: string, newValue: string, options: ReplaceOptions) : void;

Parameters:

ParameterTypeDescription
placeHolderstringCell placeholder
newValuestringString value to replace
optionsReplaceOptionsThe replace options

insertText(number, string)

Insert some characters to the cell. If the cell is rich formatted, this method could keep the original formatting.

insertText(index: number, text: string) : void;

Parameters:

ParameterTypeDescription
indexnumberThe index.
textstringInserted text.

isRichText()

Indicates whether the string value of this cell is a rich formatted text.

isRichText() : boolean;

getCharacters()

Returns all Characters objects that represents a range of characters within the cell text.

getCharacters() : FontSetting[];

Returns

All Characters objects

getCharacters(boolean)

Returns all Characters objects that represents a range of characters within the cell text.

getCharacters(flag: boolean) : FontSetting[];

Parameters:

ParameterTypeDescription
flagbooleanIndicates whether applying table style to the cell if the cell is in the table.

Returns

All Characters objects

setCharacters(FontSetting[])

Sets rich text format of the cell.

setCharacters(characters: FontSetting[]) : void;

Parameters:

ParameterTypeDescription
charactersFontSetting[]All Characters objects.

getMergedRange()

Returns a Range object which represents a merged range.

getMergedRange() : Range;

Returns

Range object. Null if this cell is not merged.

getHtmlString(boolean)

Gets the html string which contains data and some formats in this cell.

getHtmlString(html5: boolean) : string;

Parameters:

ParameterTypeDescription
html5booleanIndicates whether the value is compatible for html5

toString()

Returns a string represents the current Cell object.

toString() : string;

toJson()

Convert Cell to JSON struct data.

toJson() : string;

getHashCode()

Serves as a hash function for a particular type.

getHashCode() : number;

Returns

A hash code for current Cell object.

equals(Cell)

Checks whether this object refers to the same cell with another cell object.

equals(cell: Cell) : boolean;

Parameters:

ParameterTypeDescription
cellCellanother cell object

Returns

true if two cell objects refers to the same cell.

getConditionalFormattingResult()

Get the result of the conditional formatting.

getConditionalFormattingResult() : ConditionalFormattingResult;

Returns

ConditionalFormattingResult

Remarks

Returns null if no conditional formatting is applied to this cell,

getValidation()

Gets the validation applied to this cell.

getValidation() : Validation;

Returns

Validation

getValidationValue()

Gets the value of validation which applied to this cell.

getValidationValue() : boolean;

getTable()

Gets the table which contains this cell.

getTable() : ListObject;

Returns

ListObject

dispose()

dispose() : void;