FBaseTableRange

Facade API object bound to a rectangular Base table range.

A Base range is addressed by row and column indexes over records and fields, similar to a spreadsheet range over worksheet cells.

Row indexes resolve through the table's current recordOrder; column indexes resolve through fieldOrder. Writes are converted to Base cell updates under the hood, so the persisted snapshot still stores values by record id and field id.

Access

Access through:

• FBaseTable.getRange()
• FBaseTable.getDataRange()

Example

Read and write a rectangular block

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getRange(0, 0, 2, 2)console.log(range.getValues())range.setValues([  ['Task A', 'todo'],  ['Task B', 'done'],])const statusColumn = range.offset(0, 1, range.getNumRows(), 1)statusColumn.clear()

Setup

Register @univerjs-pro/bases or a preset that includes it. In plugin mode, import @univerjs-pro/bases/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/bases

FBaseTableRange.clear

Clear all values in this range.

To clear multiple cells, call this method once on the target range instead of clearing each cell separately.

clear(): boolean

Returns

true if cleared successfully, false if failed.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()const success = range.clear()console.log(success ? 'Range cleared successfully' : 'Failed to clear range')

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getBaseId

Get the Base id.

getBaseId(): string

Returns

The Base id.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getBaseId())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getColumn

Get the first column index of this range.

getColumn(): number

Returns

The zero-based column index.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getColumn())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getNumColumns

Get the number of columns in this range.

getNumColumns(): number

Returns

The column count.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getNumColumns())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getNumRows

Get the number of rows in this range.

getNumRows(): number

Returns

The row count.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getNumRows())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getRange

Get the raw range position.

getRange(): IRange

Returns

The range position.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getRange())

Types: IRange

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getRow

Get the first row index of this range.

getRow(): number

Returns

The zero-based row index.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getRow())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getTableId

Get the table id.

getTableId(): string

Returns

The table id.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getTableId())

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getValue

Get the first value in this range.

For multiple cells, create the target range with FBaseTable.getRange and call FBaseTableRange.getValues once instead of reading each cell separately.

getValue(): BaseCellValue

Returns

The top-left value.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getValue())

Types: BaseCellValue

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.getValues

Get all values in this range.

The outer array is rows and the inner array is columns. Empty cells are returned as null.

getValues(): BaseCellValue[][]

Returns

A two-dimensional array matching the range size.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getDataRange()console.log(range.getValues())

Types: BaseCellValue

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.offset

Create a new range offset from this range.

Offsets are validated against the table's current row and column bounds.

offset(rowOffset: number, columnOffset: number, numRows?: number, numColumns?: number): FBaseTableRange

Parameters

• rowOffset — Required. Number of rows to move. Positive values move down.
• columnOffset — Required. Number of columns to move. Positive values move right.
• numRows — Optional. Default: this.getNumRows(). Number of rows in the returned range. Defaults to the current row count.
• numColumns — Optional. Default: this.getNumColumns(). Number of columns in the returned range. Defaults to the current column count.

Returns

A new range offset from this range.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getRange(0, 0)const nextColumn = range.offset(0, 1)console.log(nextColumn)

Types: FBaseTableRange

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.setValue

Set the top-left value in this range.

For multiple cells, create the target range with FBaseTable.getRange and call FBaseTableRange.setValues with a two-dimensional array instead of writing each cell separately.

setValue(value: BaseCellValue | IBaseCellData): boolean

Parameters

• value — Required. The value to write. It may be a raw Base cell value, a full IBaseCellData object, or null to clear the cell.

Returns

true if set value successfully, false if failed.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getRange(0, 0, 2, 3)const success = range.setValue('Task title')console.log(success ? 'Value set successfully' : 'Failed to set value')

Types: BaseCellValue · IBaseCellData

Package: @univerjs-pro/bases · Type definitions

FBaseTableRange.setValues

Set all values in this range.

For multiple cells, pass the complete value matrix in one call instead of calling this method on individual cell ranges. Values are addressed relative to this range's top-left cell.

The provided matrix must fit within getNumRows() by getNumColumns(); omitted cells are unchanged. A matrix extending beyond the range throws before any command is executed.

setValues(values: Array<Array<BaseCellValue | IBaseCellData>>): boolean

Parameters

• values — Required. A two-dimensional array matching the range size. Each cell may be a raw Base cell value, an IBaseCellData object, or null.

Returns

true if set values successfully, false if failed.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getRange(0, 1, 2, 2)const success = range.setValues([  ['todo', 10],  ['done', 20],])console.log(success ? 'Values set successfully' : 'Failed to set values')

Types: Array · BaseCellValue · IBaseCellData

Package: @univerjs-pro/bases · Type definitions