# Core

This topic groups the workbook, worksheet, and structural APIs behind most `run` tasks.

## Object Hierarchy

```text
univerAPI
  -> getActiveWorkbook() -> FWorkbook
    -> getSheetByName(name) -> FWorksheet | null
      -> getRange(...) -> FRange
```

## Entry Point

Start from the active workbook:

```javascript
const workbook = univerAPI.getActiveWorkbook();
```

Top-level APIs used most often:

- `univerAPI.getActiveWorkbook() -> FWorkbook` - get the current active workbook
- `univerAPI.getFormula() -> FFormula` - get the formula engine instance used for calculation synchronization

Dimension constants used by `insertCells()` and `deleteCells()`:

- `univerAPI.Enum.Dimension.ROWS` - row dimension constant for `insertCells()` and `deleteCells()`
- `univerAPI.Enum.Dimension.COLUMNS` - column dimension constant for `insertCells()` and `deleteCells()`

## Workbook And Worksheet Access

Use the workbook object to locate, list, create, and delete sheets.

- `getSheetByName(name) -> FWorksheet | null` - recommended explicit lookup by sheet name
- `getSheets() -> FWorksheet[]` - list all worksheets; useful when the task first needs sheet names
- `create(name, rows, cols) -> FWorksheet` - create a new worksheet with an initial shape
- `deleteSheet(sheetId) -> boolean` - delete the specified worksheet by sheet id

Common worksheet reads:

- `getSheetId() -> number`
- `getSheetName() -> string`
- `getLastRow() -> number` - 0-based index of the last row with data
- `getLastColumn() -> number` - 0-based index of the last column with data
- `hasHiddenGridLines() -> boolean`

Common worksheet writes:

- `setName(name) -> void`
- `insertRows(rowIndex, numRows) -> FWorksheet`
- `deleteRows(rowIndex, numRows) -> FWorksheet`
- `insertColumns(columnIndex, numColumns) -> FWorksheet`
- `deleteColumns(columnIndex, numColumns) -> FWorksheet`
- `setFrozenRows(rows)` or `setFrozenRows(startRow, endRow) -> FWorksheet`
- `setFrozenColumns(columns)` or `setFrozenColumns(startColumn, endColumn) -> FWorksheet`
- `setHiddenGridlines(hidden) -> FWorksheet`
- `setGridLinesColor(color) -> FWorksheet` - `undefined` or `null` resets to default
- `setRowHeight(rowIndex, height) -> FWorksheet`
- `setRowHeights(startRow, numRows, height) -> FWorksheet`
- `showRows(rowIndex, numRows) -> FWorksheet`
- `hideRows(rowIndex, numRows) -> FWorksheet`
- `autoResizeRows(startRow, numRows) -> FWorksheet`
- `setColumnWidth(columnIndex, width) -> FWorksheet`
- `setColumnWidths(startColumn, numColumns, width) -> FWorksheet`
- `showColumns(columnIndex, numColumns) -> FWorksheet`
- `hideColumns(columnIndex, numColumns) -> FWorksheet`
- `autoResizeColumns(startColumn, numColumns) -> FWorksheet`

Example:

```javascript
() => {
  const workbook = univerAPI.getActiveWorkbook();
  const existing = workbook.getSheetByName("Summary");
  if (existing) {
    return { success: true, sheetName: existing.getSheetName() };
  }

  const sheet = workbook.create("Summary", 100, 20);
  return { success: true, sheetName: sheet.getSheetName() };
};
```

Formula wait API:

- `onCalculationResultApplied() -> Promise<void>` - wait until formula-calculation results are applied before reading computed values
- note: if a real calculation runs, it resolves when results are applied; if no calculation starts quickly, it can resolve automatically instead of hanging forever

## getRange()

`getRange()` is the standard bridge from a worksheet to cell-level work.

Supported forms:

- `getRange('A1')`
- `getRange('A1:C10')`
- `getRange('A:A')`
- `getRange('1:1')`
- `getRange(row, col)`
- `getRange(row, col, rowCount, colCount)`

Example:

```javascript
() => {
  const workbook = univerAPI.getActiveWorkbook();
  const sheet = workbook.getSheetByName("Sales");
  if (!sheet) return { success: false, error: 'Sheet "Sales" not found' };

  const header = sheet.getRange("A1:C1").getValues();
  const firstCell = sheet.getRange(0, 0).getValue();

  return { success: true, header, firstCell };
};
```

## Coordinate Model

Numeric coordinates are 0-based:

- `getRange(0, 0)` is `A1`
- `getRange(1, 2)` is `C2`
- `getRange(0, 0, 2, 2)` is `A1:B2`
- `insertRows(4, 3)` inserts 3 rows starting at spreadsheet row 5
- `insertColumns(1, 2)` inserts 2 columns starting at spreadsheet column B

Use numeric coordinates for loops or generated positions. Use A1 notation when the target is fixed and workbook-facing.

## A1 Notation

Prefer A1 notation for explicit workbook-facing locations:

- `'A1'`
- `'A1:B10'`
- `'A:A'`
- `'1:1'`

## Related Topics

- See `sheets` for worksheet-focused structure and presentation tasks.
- See `ranges` for cell reads, writes, formulas, merges, clear, cell shifts, and AutoFill.
- See `overview` when you need the command shape, execution rules, and hard rules.
