# Sheets

This topic focuses on worksheet creation, worksheet structure, row or column presentation, freezing, gridlines, and visibility changes.

## What This Topic Is For

Use this topic when the task is about sheet-level or row/column-level structure instead of direct cell value changes.

## Worksheet Lifecycle

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
- `getSheetId() -> number` - worksheet id
- `getSheetName() -> string` - worksheet name
- `setName(name) -> void` - rename the worksheet

Example:

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

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

## Rows And Columns

- `insertRows(rowIndex, numRows) -> FWorksheet` - insert rows at a 0-based starting index
- `deleteRows(rowIndex, numRows) -> FWorksheet` - delete rows at a 0-based starting index
- `insertColumns(columnIndex, numColumns) -> FWorksheet` - insert columns at a 0-based starting index
- `deleteColumns(columnIndex, numColumns) -> FWorksheet` - delete columns at a 0-based starting index
- `getLastRow() -> number` - 0-based index of the last row with data
- `getLastColumn() -> number` - 0-based index of the last column with data

## Freeze Rows And Columns

- `setFrozenRows(rows)` or `setFrozenRows(startRow, endRow) -> FWorksheet` - freeze the first `rows` rows, or freeze a row range
- `setFrozenColumns(columns)` or `setFrozenColumns(startColumn, endColumn) -> FWorksheet` - freeze the first `columns` columns, or freeze a column range

Insert rows and freeze the header:

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

  sheet.insertRows(1, 2);
  sheet.setFrozenRows(1);

  return { success: true, lastRow: sheet.getLastRow() };
};
```

## Gridlines

- `hasHiddenGridLines() -> boolean` - check whether gridlines are hidden
- `setHiddenGridlines(hidden) -> FWorksheet` - show or hide sheet gridlines
- `setGridLinesColor(color) -> FWorksheet` - set gridline color; `undefined` or `null` resets to default

Hide gridlines and set their color:

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

  sheet.setHiddenGridlines(true);
  sheet.setGridLinesColor("#D9D9D9");

  return { success: true, hidden: sheet.hasHiddenGridLines() };
};
```

## Row And Column Presentation

- `setRowHeight(rowIndex, height) -> FWorksheet` - set one row height in pixels
- `setRowHeights(startRow, numRows, height) -> FWorksheet` - set multiple row heights
- `showRows(rowIndex, numRows) -> FWorksheet` - show hidden rows
- `hideRows(rowIndex, numRows) -> FWorksheet` - hide rows
- `autoResizeRows(startRow, numRows) -> FWorksheet` - auto-size row heights to content
- `setColumnWidth(columnIndex, width) -> FWorksheet` - set one column width in pixels
- `setColumnWidths(startColumn, numColumns, width) -> FWorksheet` - set multiple column widths
- `showColumns(columnIndex, numColumns) -> FWorksheet` - show hidden columns
- `hideColumns(columnIndex, numColumns) -> FWorksheet` - hide columns
- `autoResizeColumns(startColumn, numColumns) -> FWorksheet` - auto-size column widths to content

## Getchas

- imported workbooks can contain non-English worksheet names and still work normally
- quote the full range string in the shell, for example `--range '工作表1!A1:J3'`
- verify imported templates by reading a small anchor range and checking a few exact cells plus one non-empty cell
- for workbook-visible structure checks, prefer `inspect workbook` over package metadata

## Related Topics

- See `core` for workbook entry points, `getRange()`, A1 notation, and coordinates.
- See `formatting` for cell-level visual formatting after the sheet structure is in place.
