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:

Example

Read and write a rectangular block

TypeScript

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.

TypeScript

clear(): boolean

Returns

true if cleared successfully, false if failed.

Examples

TypeScript

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.

TypeScript

getBaseId(): string

Returns

The Base id.

Examples

TypeScript

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.

TypeScript

getColumn(): number

Returns

The zero-based column index.

Examples

TypeScript

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.

TypeScript

getNumColumns(): number

Returns

The column count.

Examples

TypeScript

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.

TypeScript

getNumRows(): number

Returns

The row count.

Examples

TypeScript

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.

TypeScript

getRange(): IRange

Returns

The range position.

Examples

TypeScript

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.

TypeScript

getRow(): number

Returns

The zero-based row index.

Examples

TypeScript

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.

TypeScript

getTableId(): string

Returns

The table id.

Examples

TypeScript

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.

TypeScript

getValue(): BaseCellValue

Returns

The top-left value.

Examples

TypeScript

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.

TypeScript

getValues(): BaseCellValue[][]

Returns

A two-dimensional array matching the range size.

Examples

TypeScript

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.

TypeScript

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

TypeScript

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.

TypeScript

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

TypeScript

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.

The provided matrix must match getNumRows() by getNumColumns(). Passing the wrong shape throws before any command is executed.

TypeScript

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

TypeScript

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

How is this guide?