# FBaseTableRange

- Human documentation: [https://docs.univer.ai/reference/facade/base-table-range](https://docs.univer.ai/reference/facade/base-table-range)

- Agent Markdown: [https://docs.univer.ai/reference/facade/base-table-range.md](https://docs.univer.ai/reference/facade/base-table-range.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/base-table-range.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/base-table-range.mdx)

---

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()`](https://docs.univer.ai/reference/facade/base-table.md#getrange)
* [`FBaseTable.getDataRange()`](https://docs.univer.ai/reference/facade/base-table.md#getdatarange)

## Example

Read and write a rectangular block

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) 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](https://docs.univer.ai/guides/bases/getting-started/facade.md).

## `@univerjs-pro/bases`

### `FBaseTableRange.clear`

Clear all values in this range.

```typescript
clear(): boolean
```

**Returns**

`true` if cleared successfully, `false` if failed.

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getBaseId`

Get the Base id.

```typescript
getBaseId(): string
```

**Returns**

The Base id.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getColumn`

Get the first column index of this range.

```typescript
getColumn(): number
```

**Returns**

The zero-based column index.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getNumColumns`

Get the number of columns in this range.

```typescript
getNumColumns(): number
```

**Returns**

The column count.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getNumRows`

Get the number of rows in this range.

```typescript
getNumRows(): number
```

**Returns**

The row count.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getRange`

Get the raw range position.

```typescript
getRange(): IRange
```

**Returns**

The range position.

**Examples**

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

**Types:** [`IRange`](https://docs.univer.ai/reference/types/range.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getRow`

Get the first row index of this range.

```typescript
getRow(): number
```

**Returns**

The zero-based row index.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getTableId`

Get the table id.

```typescript
getTableId(): string
```

**Returns**

The table id.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `FBaseTableRange.getValue`

Get the first value in this range.

```typescript
getValue(): BaseCellValue
```

**Returns**

The top-left value.

**Examples**

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

**Types:** [`BaseCellValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `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**

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

**Types:** [`BaseCellValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `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**

```ts
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`](https://docs.univer.ai/reference/facade/base-table-range.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `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**

```ts
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`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseCellData`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)

### `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**

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`BaseCellValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseCellData`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-range.d.ts)