# FWorkbook

> Language fallback: requested `ko-KR`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/ko-KR/reference/facade/workbook](https://docs.univer.ai/ko-KR/reference/facade/workbook)

- Agent Markdown: [https://docs.univer.ai/ko-KR/reference/facade/workbook.md](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.

Get this object from the initialized `univerAPI` instance. The example assumes a workbook is already open.

```ts
const workbook = univerAPI.getActiveWorkbook()
if (!workbook) throw new Error('No active workbook')
console.log(workbook.getSheets().map((sheet) => sheet.getName()))
```

## Access

Access through:

* [`FUniver.createWorkbook()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#createworkbook)
* [`FUniver.getActiveWorkbook()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getactiveworkbook)
* [`FUniver.getWorkbook()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getworkbook)
* [`FUniver.getSheetCommandTarget()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getsheetcommandtarget)
* [`FUniver.getActiveSheet()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getactivesheet)
* [`FCollaboration.loadSheetAsync()`](https://docs.univer.ai/ko-KR/reference/facade/collaboration.md#loadsheetasync)

## Setup

Register [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) or a preset that includes it. In plugin mode, import `@univerjs/sheets/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md).

## `@univerjs/sheets`

### `FWorkbook.addStyles`

Add styles to the workbook styles.

```typescript
addStyles(styles: Record<string, IStyleData>): void
```

**Parameters**

* `styles` — Required. Styles to add

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Add styles to the workbook styles
const styles = {
  'custom-style-1': {
    bg: {
      rgb: 'rgb(255, 0, 0)',
    },
  },
  'custom-style-2': {
    fs: 20,
    n: {
      pattern: '@',
    },
  },
}
fWorkbook.addStyles(styles)

// Set values with the new styles
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  [
    { v: 'Hello', s: 'custom-style-1' },
    { v: 'Univer', s: 'custom-style-1' },
  ],
  [
    { v: 'To', s: 'custom-style-1' },
    { v: '0001', s: 'custom-style-2' },
  ],
])
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IStyleData`](https://docs.univer.ai/ko-KR/reference/types/style-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.create`

Create a new worksheet and returns a handle to it.

```typescript
create(name: string, rows: number, columns: number, options?: { index?: number; sheet?: Partial<IWorksheetData>; }): FWorksheet
```

**Parameters**

* `name` — Required. Name of the new sheet
* `rows` — Required. How many rows would the new sheet have
* `columns` — Required. How many columns would the new sheet have
* `options` — Optional. The options for the new sheet

**Returns**

The new created sheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Create a new sheet named 'MyNewSheet' with 10 rows and 10 columns
const newSheet = fWorkbook.create('MyNewSheet', 10, 10)
console.log(newSheet)

// Create a new sheet named 'MyNewSheetWithData' with 10 rows and 10 columns and some data, and set it as the first sheet
const sheetData = {
  // ... Omit other properties
  cellData: {
    0: {
      0: {
        v: 'Hello Univer!',
      },
    },
  },
  // ... Omit other properties
}
const newSheetWithData = fWorkbook.create('MyNewSheetWithData', 10, 10, {
  index: 0,
  sheet: sheetData,
})
console.log(newSheetWithData)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IWorksheetData`](https://docs.univer.ai/ko-KR/reference/types/worksheet-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.createRangeThemeStyle`

Create a range theme style.

```typescript
createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyle
```

**Parameters**

* `themeName` — Required. The name of the theme to register
* `themeStyleJson` — Optional. The theme style json to register

**Returns**

* The created range theme style

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    },
  },
})
console.log(rangeThemeStyle)
```

**Types:** [`RangeThemeStyle`](https://unpkg.com/@univerjs/sheets/lib/types/models/range-theme-util.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IRangeThemeStyleJSON`](https://unpkg.com/@univerjs/sheets/lib/types/models/range-theme-util.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.deleteActiveSheet`

Deletes the currently active sheet.

```typescript
deleteActiveSheet(): boolean
```

**Returns**

true if the sheet was deleted, false otherwise

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.deleteActiveSheet()
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.deleteDefinedName`

Delete the defined name with the given name.

```typescript
deleteDefinedName(name: string): boolean
```

**Parameters**

* `name` — Required. The name of the defined name to delete

**Returns**

true if the defined name was deleted, false otherwise

**Examples**

```ts
// The code below deletes the defined name with the given name
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.deleteDefinedName('MyDefinedName')
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.deleteSheet`

Deletes the specified worksheet.

```typescript
deleteSheet(sheet: FWorksheet | string): boolean
```

**Parameters**

* `sheet` — Required. The instance or id of the worksheet to delete.

**Returns**

True if the worksheet was deleted, false otherwise.

**Examples**

```ts
// The code below deletes the specified worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// The code below deletes the specified worksheet by id
// fWorkbook.deleteSheet(sheet.getSheetId());
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.dispose`

Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit.

```typescript
dispose(): void
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.duplicateActiveSheet`

Duplicates the active sheet.

```typescript
duplicateActiveSheet(): FWorksheet
```

**Returns**

The duplicated worksheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const duplicatedSheet = fWorkbook.duplicateActiveSheet()
console.log(duplicatedSheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.duplicateSheet`

Duplicates the given worksheet.

```typescript
duplicateSheet(sheet: FWorksheet): FWorksheet
```

**Parameters**

* `sheet` — Required. The worksheet to duplicate.

**Returns**

The duplicated worksheet

**Examples**

```ts
// The code below duplicates the given worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const activeSheet = fWorkbook.getSheetByName('Sheet1')
if (!activeSheet) throw new Error('activeSheet is not available')
const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet)
console.log(duplicatedSheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getActiveCell`

Returns the active cell in this spreadsheet.

```typescript
getActiveCell(): FRange | null
```

**Returns**

The active cell

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
console.log(fWorkbook.getActiveCell().getA1Notation())
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getActiveRange`

Returns the selected range in the active sheet, or null if there is no active range.

```typescript
getActiveRange(): FRange | null
```

**Returns**

The active range

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const activeRange = fWorkbook.getActiveRange()
console.log(activeRange)
```

**Types:** [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getActiveSheet`

Get the active sheet of the workbook.

```typescript
getActiveSheet(): FWorksheet
```

**Returns**

The active sheet of the workbook

**Examples**

```ts
// The code below gets the active sheet of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
if (!fWorksheet) throw new Error('fWorksheet is not available')
console.log(fWorksheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getCustomMetadata`

Get custom metadata of workbook

```typescript
getCustomMetadata(): CustomData | undefined
```

**Returns**

custom metadata

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const custom = fWorkbook.getCustomMetadata()
console.log(custom)
```

**Types:** [`CustomData`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getDefinedName`

Get the defined name by name.

```typescript
getDefinedName(name: string): FDefinedName | null
```

**Parameters**

* `name` — Required. The name of the defined name to get

**Returns**

The defined name with the given name

**Examples**

```ts
// The code below gets the defined name by name
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())
```

**Types:** [`FDefinedName`](https://docs.univer.ai/ko-KR/reference/facade/defined-name.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getDefinedNames`

Get all the defined names in the workbook.

```typescript
getDefinedNames(): FDefinedName[]
```

**Returns**

All the defined names in the workbook

**Examples**

```ts
// The code below gets all the defined names in the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const definedNames = fWorkbook.getDefinedNames()
console.log(definedNames, definedNames[0]?.getFormulaOrRefString())
```

**Types:** [`FDefinedName`](https://docs.univer.ai/ko-KR/reference/facade/defined-name.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getId`

Get the id of the workbook.

```typescript
getId(): string
```

**Returns**

The id of the workbook.

**Examples**

```ts
// The code below gets the id of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
console.log(unitId)
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getName`

Get the name of the workbook.

```typescript
getName(): string
```

**Returns**

The name of the workbook.

**Examples**

```ts
// The code below gets the name of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const name = fWorkbook.getName()
console.log(name)
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getNumSheets`

Get the number of sheets in the workbook.

```typescript
getNumSheets(): number
```

**Returns**

The number of sheets in the workbook

**Examples**

```ts
// The code below gets the number of sheets in the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
console.log(fWorkbook.getNumSheets())
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getRegisteredRangeThemes`

Gets the registered range themes.

```typescript
getRegisteredRangeThemes(): string[]
```

**Returns**

The name list of registered range themes.

**Examples**

```ts
// The code below gets the registered range themes
const fWorkbook = univerAPI.getActiveWorkbook()
const themes = fWorkbook.getRegisteredRangeThemes()
console.log(themes)
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getSheetByName`

Get a worksheet by sheet name.

```typescript
getSheetByName(name: string): FWorksheet | null
```

**Parameters**

* `name` — Required. The name of the sheet to get.

**Returns**

The worksheet with given sheet name

**Examples**

```ts
// The code below gets a worksheet by sheet name
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheetByName('Sheet1')
console.log(sheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getSheetBySheetId`

Get a worksheet by sheet id.

```typescript
getSheetBySheetId(sheetId: string): FWorksheet | null
```

**Parameters**

* `sheetId` — Required. The id of the sheet to get.

**Returns**

The worksheet with given sheet id

**Examples**

```ts
// The code below gets a worksheet by sheet id
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheetBySheetId('sheetId')
console.log(sheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getSheets`

Gets all the worksheets in this workbook

```typescript
getSheets(): FWorksheet[]
```

**Returns**

An array of all the worksheets in the workbook

**Examples**

```ts
// The code below gets all the worksheets in the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
console.log(sheets)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getUrl`

Get the URL of the workbook.

```typescript
getUrl(): string
```

**Returns**

The URL of the workbook

**Examples**

```ts
// The code below gets the URL of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const url = fWorkbook.getUrl()
console.log(url)
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getWorkbook`

Get the Workbook instance.

```typescript
getWorkbook(): Workbook
```

**Returns**

The Workbook instance.

**Examples**

```ts
// The code below gets the Workbook instance
const fWorkbook = univerAPI.getActiveWorkbook()
const workbook = fWorkbook.getWorkbook()
console.log(workbook)
```

**Types:** [`Workbook`](https://unpkg.com/@univerjs/core/lib/types/sheets/workbook.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getWorkbookPermission`

Get the WorkbookPermission instance for managing workbook-level permissions.
This is the new permission API that provides a more intuitive and type-safe interface.

```typescript
getWorkbookPermission(): FWorkbookPermission
```

**Returns**

* The WorkbookPermission instance.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const permission = fWorkbook.getWorkbookPermission()

// Set workbook to read-only mode
await permission.setMode('viewer')

// Add a collaborator
await permission.addCollaborator({
  userId: 'user123',
  name: 'John Doe',
  role: 'editor',
})

// Subscribe to permission changes
permission.permission$.subscribe((snapshot) => {
  console.log('Permissions changed:', snapshot)
})
```

**Types:** [`FWorkbookPermission`](https://docs.univer.ai/ko-KR/reference/facade/workbook-permission.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.id`

The workbook unit id used to identify this workbook in commands and snapshots.

```typescript
readonly id: string
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.insertDefinedName`

Insert a defined name.

```typescript
insertDefinedName(name: string, formulaOrRefString: string): FWorkbook
```

**Parameters**

* `name` — Required. The name of the defined name to insert
* `formulaOrRefString` — Required. The formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert

**Returns**

The current FWorkbook instance

**Examples**

```ts
// The code below inserts a defined name
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1')
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.insertDefinedNameBuilder`

Insert a defined name by builder param.

```typescript
insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): void
```

**Parameters**

* `param` — Required. The param to insert the defined name

**Examples**

```ts
// The code below inserts a defined name by builder param
const fWorkbook = univerAPI.getActiveWorkbook()
const definedNameParam = fWorkbook
  .newDefinedNameBuilder()
  .setRef('Sheet1!$A$1')
  .setName('MyDefinedName')
  .setComment('This is a comment')
  .build()
fWorkbook.insertDefinedNameBuilder(definedNameParam)
```

**Types:** [`ISetDefinedNameMutationParam`](https://unpkg.com/@univerjs/engine-formula/lib/types/commands/mutations/set-defined-name.mutation.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.insertSheet`

Inserts a new worksheet into the workbook.
Using a default sheet name. The new sheet becomes the active sheet

```typescript
insertSheet(sheetName?: string, options?: { index?: number; sheet?: Partial<IWorksheetData>; }): FWorksheet
```

**Parameters**

* `sheetName` — Optional. The name of the new sheet
* `options` — Optional. The options for the new sheet

**Returns**

The new sheet

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Create a new sheet with default configuration
const newSheet = fWorkbook.insertSheet()
console.log(newSheet)

// Create a new sheet with custom name and default configuration
const newSheetWithName = fWorkbook.insertSheet('MyNewSheet')
console.log(newSheetWithName)

// Create a new sheet with custom name and custom configuration
const sheetData = {
  // ... Omit other properties
  cellData: {
    0: {
      0: {
        v: 'Hello Univer!',
      },
    },
  },
  // ... Omit other properties
}
const newSheetWithData = fWorkbook.insertSheet('MyNewSheetWithData', {
  index: 0,
  sheet: sheetData,
})
console.log(newSheetWithData)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IWorksheetData`](https://docs.univer.ai/ko-KR/reference/types/worksheet-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.moveActiveSheet`

Move the active sheet to the specified index.

```typescript
moveActiveSheet(index: number): FWorkbook
```

**Parameters**

* `index` — Required. The index to move the active sheet to

**Returns**

This workbook, for chaining

**Examples**

```ts
// The code below moves the active sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.moveActiveSheet(1)
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.moveSheet`

Move the sheet to the specified index.

```typescript
moveSheet(sheet: FWorksheet, index: number): FWorkbook
```

**Parameters**

* `sheet` — Required. The sheet to move
* `index` — Required. The index to move the sheet to

**Returns**

This workbook, for chaining

**Examples**

```ts
// The code below moves the sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheetByName('Sheet1')
if (!sheet) throw new Error('sheet is not available')
fWorkbook.moveSheet(sheet, 1)
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.newDefinedNameBuilder`

Create a new defined name builder.

```typescript
newDefinedNameBuilder(): FDefinedNameBuilder
```

**Returns**

* The defined name builder.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const definedNameParam = fWorkbook
  .newDefinedNameBuilder()
  .setRef('Sheet1!$A$1')
  .setName('MyDefinedName')
  .setComment('This is a comment')
  .build()
console.log(definedNameParam)
fWorkbook.insertDefinedNameBuilder(definedNameParam)
```

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/ko-KR/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.onBeforeCommandExecute`

Callback for command execution.

Register a callback that will be triggered before invoking a command targeting the Univer sheet.

```typescript
onBeforeCommandExecute(callback: CommandListener): IDisposable
```

**Parameters**

* `callback` — Required. the callback.

**Returns**

A function to dispose the listening.

**Examples**

```ts
// The code below registers a callback that will be triggered before invoking a command targeting the Univer sheet
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onBeforeCommandExecute((command) => {
  console.log('Before command execute:', command)
})
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts) · [`CommandListener`](https://unpkg.com/@univerjs/core/lib/types/services/command/command.service.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.onCommandExecuted`

Callback for command execution.

Register a callback that will be triggered when a command is invoked targeting the Univer sheet.

```typescript
onCommandExecuted(callback: CommandListener): IDisposable
```

**Parameters**

* `callback` — Required. the callback.

**Returns**

A function to dispose the listening.

**Examples**

```ts
// The code below registers a callback that will be triggered when a command is invoked targeting the Univer sheet
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onCommandExecuted((command) => {
  console.log('Command executed:', command)
})
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts) · [`CommandListener`](https://unpkg.com/@univerjs/core/lib/types/services/command/command.service.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.onSelectionChange`

Callback for selection changes.

Register a callback that will be triggered when the selection changes.

```typescript
onSelectionChange(callback: (selections: IRange[]) => void): IDisposable
```

**Parameters**

* `callback` — Required. The callback.

**Returns**

A function to dispose the listening

**Examples**

```ts
// The code below registers a callback that will be triggered when the selection changes
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onSelectionChange((selections) => {
  console.log('Selection changed:', selections)
})
```

**Types:** [`IDisposable`](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts) · [`IRange`](https://docs.univer.ai/ko-KR/reference/types/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.redo`

Redo the last undone action.

```typescript
redo(): FWorkbook
```

**Returns**

This workbook, for chaining.

**Examples**

```ts
// The code below redoes the last undone action
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.redo()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.registerRangeTheme`

Register a custom range theme style.

```typescript
registerRangeTheme(rangeThemeStyle: RangeThemeStyle): void
```

**Parameters**

* `rangeThemeStyle` — Required. The range theme style to register

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
  secondRowStyle: {
    bg: {
      rgb: 'rgb(214,231,241)',
    },
  },
})
fWorkbook.registerRangeTheme(rangeThemeStyle)
```

**Types:** [`RangeThemeStyle`](https://unpkg.com/@univerjs/sheets/lib/types/models/range-theme-util.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.removeStyles`

Remove styles from the workbook styles.

```typescript
removeStyles(styleKeys: string[]): void
```

**Parameters**

* `styleKeys` — Required. Style keys to remove

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Add styles to the workbook styles
const styles = {
  'custom-style-1': {
    bg: {
      rgb: 'rgb(255, 0, 0)',
    },
  },
  'custom-style-2': {
    fs: 20,
    n: {
      pattern: '@',
    },
  },
}
fWorkbook.addStyles(styles)

// Set values with the new styles
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  [
    { v: 'Hello', s: 'custom-style-1' },
    { v: 'Univer', s: 'custom-style-1' },
  ],
  [
    { v: 'To', s: 'custom-style-1' },
    { v: '0001', s: 'custom-style-2' },
  ],
])

// Remove the style `custom-style-1` after 2 seconds
setTimeout(() => {
  fWorkbook.removeStyles(['custom-style-1'])
  fWorksheet.refreshCanvas()
}, 2000)
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.save`

Save workbook snapshot data, including conditional formatting, data validation, and other plugin data.

```typescript
save(): IWorkbookData
```

**Returns**

Workbook snapshot data

**Examples**

```ts
// The code below saves the workbook snapshot data
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
console.log(snapshot)
```

**Types:** [`IWorkbookData`](https://docs.univer.ai/ko-KR/reference/types/workbook-data.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setActiveRange`

Sets the selection region for active sheet.

```typescript
setActiveRange(range: FRange): FWorkbook
```

**Parameters**

* `range` — Required. The range to set as the active selection.

**Returns**

FWorkbook instance

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const range = fWorksheet.getRange('A10:B10')
fWorkbook.setActiveRange(range)
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`FRange`](https://docs.univer.ai/ko-KR/reference/facade/range.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setActiveSheet`

Sets the given worksheet to be the active worksheet in the workbook.

```typescript
setActiveSheet(sheet: FWorksheet | string): FWorksheet
```

**Parameters**

* `sheet` — Required. The instance or id of the worksheet to set as active.

**Returns**

The active worksheet

**Examples**

```ts
// The code below sets the given worksheet to be the active worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)
```

**Types:** [`FWorksheet`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setCustomMetadata`

Set custom metadata of workbook

```typescript
setCustomMetadata(custom: CustomData | undefined): FWorkbook
```

**Parameters**

* `custom` — Required. custom metadata

**Returns**

FWorkbook

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setCustomMetadata({ key: 'value' })
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`CustomData`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setEditable`

Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.

```typescript
setEditable(value: boolean): FWorkbook
```

**Parameters**

* `value` — Required. editable value want to set

**Returns**

FWorkbook instance

**Examples**

```ts
// The code below sets the editing permissions of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setEditable(false)
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setName`

Set the name of the workbook.

```typescript
setName(name: string): this
```

**Parameters**

* `name` — Required. The new name of the workbook.

**Returns**

The current FWorkbook instance for chaining.

**Examples**

```ts
// The code below sets the name of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setName('MyWorkbook')
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.undo`

Undo the last action.

```typescript
undo(): FWorkbook
```

**Returns**

This workbook, for chaining.

**Examples**

```ts
// The code below undoes the last action
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.undo()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.unregisterRangeTheme`

Unregister a custom range theme style.

```typescript
unregisterRangeTheme(themeName: string): void
```

**Parameters**

* `themeName` — Required. The name of the theme to unregister

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.unregisterRangeTheme('MyTheme')
```

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.updateDefinedNameBuilder`

Update the defined name with the given name.

```typescript
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void
```

**Parameters**

* `param` — Required. The param to insert the defined name

**Examples**

```ts
// The code below updates the defined name with the given name
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

// Update the defined name
if (definedName) {
  const newDefinedNameParam = definedName
    .toBuilder()
    .setName('NewDefinedName')
    .setRef('Sheet1!$A$2')
    .build()
  fWorkbook.updateDefinedNameBuilder(newDefinedNameParam)
}
```

**Types:** [`ISetDefinedNameMutationParam`](https://unpkg.com/@univerjs/engine-formula/lib/types/commands/mutations/set-defined-name.mutation.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-data-validation`

### `FWorkbook.getAllDataValidationErrorAsync`

Get all data validation errors for current workbook.

```typescript
getAllDataValidationErrorAsync(): Promise<IDataValidationError[]>
```

**Returns**

A promise that resolves to an array of validation errors.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const errors = await fWorkbook.getAllDataValidationErrorAsync()
console.log(errors)
```

**Types:** [`IDataValidationError`](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-workbook.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getValidatorStatus`

Get data validation validator status for current workbook.

```typescript
getValidatorStatus(): Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>>
```

**Returns**

A promise resolving to an object keyed by sheet ID, with a validation-status matrix for each sheet.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const status = await fWorkbook.getValidatorStatus()
console.log(status)
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ObjectMatrix`](https://unpkg.com/@univerjs/core/lib/types/shared/object-matrix.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts) · [`DataValidationStatus`](https://unpkg.com/@univerjs/core/lib/types/types/enum/data-validation-status.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-data-validation`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-data-validation.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-data-validation/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-formula`

### `FWorkbook.getAllFormulaError`

Get all formula errors in the workbook

```typescript
getAllFormulaError(): ISheetFormulaError[]
```

**Returns**

Array of formula errors

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const errors = fWorkbook.getAllFormulaError()
console.log('Formula errors:', errors)
```

**Types:** [`ISheetFormulaError`](https://unpkg.com/@univerjs/engine-formula/lib/types/basics/error-type.d.ts)

**Package:** [`@univerjs/sheets-formula`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-formula.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-formula/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-hyper-link`

### `FWorkbook.getUrlOfDefineName`

Create a hyperlink url for the defined name.
The defined name must exist in the current workbook and must be a reference to a range, otherwise an error will be thrown.

```typescript
getUrlOfDefineName(name: string): string
```

**Parameters**

* `name` — Required. The name of the defined name.

**Returns**

The hyperlink url of the defined name.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Create a defined name "TestRange" for the range A1:B10 of the active sheet
const definedNameParam = fWorkbook
  .newDefinedNameBuilder()
  .setName('TestRange')
  .setRef('Sheet1!$A$1:$B$10')
  .build()
fWorkbook.insertDefinedNameBuilder(definedNameParam)

// Create a hyperlink to the defined name "TestRange" on cell C1
const url = fWorkbook.getUrlOfDefineName('TestRange')
console.log(url)
const fRange = fWorksheet.getRange('C1')
fRange.setHyperLink(url, 'Link to TestRange')

// Create a hyperlink to the exiting defined name on cell C2
const definedNames = fWorkbook.getDefinedNames()
console.log(definedNames)
const exitsDefinedNameUrl = fWorkbook.getUrlOfDefineName(definedNames[0].getName())
console.log(exitsDefinedNameUrl)
const fRange2 = fWorksheet.getRange('C2')
fRange2.setHyperLink(exitsDefinedNameUrl, `Link to ${definedNames[0].getName()}`)
```

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.parseSheetHyperlink`

Parse the hyperlink string to get the hyperlink info.

```typescript
parseSheetHyperlink(hyperlink: string): ISheetHyperLinkInfo
```

**Parameters**

* `hyperlink` — Required. The hyperlink string.

**Returns**

The hyperlink info.

**Examples**

```ts
// Create a hyperlink to the range A1:D10 of the current sheet
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const fRange = fWorksheet.getRange('A1:D10')
const hyperlink = fRange.getUrl()

// Parse the hyperlink
const hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlink)
console.log(hyperlinkInfo)
```

**Types:** [`ISheetHyperLinkInfo`](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/services/parser.service.d.ts)

**Package:** [`@univerjs/sheets-hyper-link`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-hyper-link-ui`

### `FWorkbook.navigateToSheetHyperlink`

Navigate to the sheet hyperlink.

```typescript
navigateToSheetHyperlink(hyperlink: string): void
```

**Parameters**

* `hyperlink` — Required. The hyperlink string

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()

// Create a hyperlink to the cell F6 in the first sheet
const sheet1 = sheets[0]
const range = sheet1.getRange('F6')
const hyperlink = range.getUrl()

// Switch to the second sheet
fWorkbook.setActiveSheet(sheets[1])
console.log(fWorkbook.getActiveSheet().getSheetName())

// Navigate to the hyperlink after 3 seconds
setTimeout(() => {
  fWorkbook.navigateToSheetHyperlink(hyperlink)
  console.log(fWorkbook.getActiveSheet().getSheetName())
}, 3000)
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets-hyper-link-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-hyper-link-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-hyper-link-ui/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-numfmt`

### `FWorkbook.setNumfmtLocal`

Set the locale for number formatting.

```typescript
setNumfmtLocal(locale: INumfmtLocaleTag): FWorkbook
```

**Parameters**

* `locale` — Required. zh_CN,zh_TW,zh_HK,ja,ko,th,cs,da,nl,en,en_AU,en_CA,en_GB,en_IE,fi,fr,fr_CA,fr_CH,de,de_CH,el,hu,is,id,it,it_CH,nb,no,pl,pt,pt_BR,ru,sk,es,es_AR,es_BO,es_CL,es_CO,es_EC,es_MX,es_PY,es_UY,es_VE,sv,tr,cy,az,be,bg,ca,fil,gu,he,hr,hy,ka,kk,kn,lt,lv,ml,mn,mr,my,pa,ro,sl,sr,ta,te,uk,vi,ar,bn,hi

**Returns**

The FWorkbook instance for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')

// Set the locale en_US for number formatting.
fWorkbook.setNumfmtLocal('en_US')
console.log(fRange.getDisplayValue()) // 1,234.57

// Set the locale de_DE for number formatting.
fWorkbook.setNumfmtLocal('de_DE')
console.log(fRange.getDisplayValue()) // 1.234,57
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`INumfmtLocaleTag`](https://unpkg.com/@univerjs/core/lib/types/shared/numfmt/utils.d.ts)

**Package:** [`@univerjs/sheets-numfmt`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-numfmt.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-numfmt/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-table`

### `FWorkbook.addTable`

Add table

```typescript
addTable(subUnitId: string, tableName: string, rangeInfo: ITableRange, tableId?: string, options?: ITableOptions): Promise<string | undefined>
```

**Parameters**

* `subUnitId` — Required. The sub unit id
* `tableName` — Required. The table name
* `rangeInfo` — Required. The table range information
* `tableId` — Optional. The table id
* `options` — Optional. The table options

**Returns**

A promise resolving to the table ID, or `undefined` if the name is invalid or creation fails.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const id = await fWorkbook.addTable(fWorksheet.getSheetId(), 'name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (id) {
  const tableInfo = fWorkbook.getTableInfo(id)
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ITableRange`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts) · [`ITableOptions`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getTableInfo`

Get table information

```typescript
getTableInfo(tableId: string): ITableInfoWithUnitId | undefined
```

**Parameters**

* `tableId` — Required. The table id

**Returns**

The table information, including workbook and worksheet IDs, or `undefined` if not found.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`ITableInfoWithUnitId`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getTableInfoByName`

Get table information by name

```typescript
getTableInfoByName(tableName: string): ITableInfoWithUnitId | undefined
```

**Parameters**

* `tableName` — Required. The table name

**Returns**

The table information, including workbook and worksheet IDs, or `undefined` if not found.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  const tableInfo = fWorkbook.getTableInfoByName('name-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`ITableInfoWithUnitId`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getTableList`

Get table list

```typescript
getTableList(): ITableInfoWithUnitId[]
```

**Returns**

The table list

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const tables = fWorkbook.getTableList()
console.log('debugger tables', tables)
```

**Types:** [`ITableInfoWithUnitId`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.removeTable`

Remove table

```typescript
removeTable(tableId: string): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id

**Returns**

A promise resolving to whether the table was removed; `false` if the table is not found.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const tableInfo = fWorkbook.getTableInfo('id-1')
console.log('debugger tableInfo', tableInfo)

if (tableInfo) {
  // Remove the table with the specified id
  await fWorkbook.removeTable('id-1')
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.setTableFilter`

set table filter

```typescript
setTableFilter(tableId: string, column: number, filter: ITableFilterItem | undefined): Promise<boolean>
```

**Parameters**

* `tableId` — Required. The table id
* `column` — Required. The column index, starting from 0.
* `filter` — Required. The filter to apply, or `undefined` to clear the column filter.

**Returns**

The result of set table filter

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable('name-1', fRange.getRange(), 'id-1', {
  tableStyleId: 'table-default-4',
})

if (success) {
  // Set the filter for the second column
  await fWorkbook.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ITableFilterItem`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts)

**Package:** [`@univerjs/sheets-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-table.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-table/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-thread-comment`

### `FWorkbook.clearComments`

Clear all comments in the current workbook

```typescript
clearComments(): Promise<boolean>
```

**Returns**

Whether the comments are cleared successfully.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const result = await fWorkbook.clearComments()
console.log(result)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getComments`

Get all comments in the current workbook

```typescript
getComments(): FThreadComment[]
```

**Returns**

All comments in the current workbook

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const comments = fWorkbook.getComments()
comments.forEach((comment) => {
  const isRoot = comment.getIsRoot()

  if (isRoot) {
    console.log('root comment:', comment.getCommentData())

    const replies = comment.getReplies()
    replies.forEach((reply) => {
      console.log('reply comment:', reply.getCommentData())
    })
  }
})
```

**Types:** [`FThreadComment`](https://docs.univer.ai/ko-KR/reference/facade/thread-comment.md)

**Package:** [`@univerjs/sheets-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-thread-comment/lib/types/facade/f-workbook.d.ts)

## `@univerjs/sheets-ui`

### `FWorkbook.abortEditingAsync`

End the editing process of the current active cell, and discard the changes.

```typescript
abortEditingAsync(): Promise<boolean>
```

**Returns**

Whether the editing process is ended successfully

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
await fWorkbook.abortEditingAsync()
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.customizeColumnHeader`

Customize the column header of the all worksheets in the workbook.

```typescript
customizeColumnHeader(cfg: IColumnsHeaderCfgParam): void
```

**Parameters**

* `cfg` — Required. The configuration of the column header.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.customizeColumnHeader({
  headerStyle: {
    fontColor: '#fff',
    backgroundColor: '#4e69ee',
    fontSize: 9,
  },
  columnsCfg: {
    0: 'kuma II',
    3: {
      text: 'Size',
      textAlign: 'left', // CanvasTextAlign
      fontColor: '#fff',
      fontSize: 12,
      borderColor: 'pink',
      backgroundColor: 'pink',
    },
    4: 'Wow',
  },
})
```

**Types:** [`IColumnsHeaderCfgParam`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/extensions/column-header-layout.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.customizeRowHeader`

Customize the row header of the all worksheets in the workbook.

```typescript
customizeRowHeader(cfg: IRowsHeaderCfgParam): void
```

**Parameters**

* `cfg` — Required. The configuration of the row header.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.customizeRowHeader({
  headerStyle: {
    backgroundColor: 'pink',
    fontSize: 12,
  },
  rowsCfg: {
    0: 'Moka II',
    3: {
      text: 'Size',
      textAlign: 'left', // CanvasTextAlign
    },
  },
})
```

**Types:** [`IRowsHeaderCfgParam`](https://unpkg.com/@univerjs/engine-render/lib/types/components/sheets/extensions/row-header-layout.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.disableSelection`

Disable selection. After disabled, there would be no response for selection.

```typescript
disableSelection(): FWorkbook
```

**Returns**

FWorkbook instance for chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.disableSelection()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.enableSelection`

Enable selection. After this you can select range.

```typescript
enableSelection(): FWorkbook
```

**Returns**

FWorkbook instance for chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.enableSelection()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.endEditingAsync`

End the editing process of the current active cell

```typescript
endEditingAsync(save?: boolean): Promise<boolean>
```

**Parameters**

* `save` — Optional. Default: `true`. Whether to save the changes, default is true

**Returns**

Whether the editing process is ended successfully

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
await fWorkbook.endEditingAsync(false)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getScrollStateBySheetId`

Get scroll state of specified sheet.

```typescript
getScrollStateBySheetId(sheetId: string): Nullable<IScrollState>
```

**Parameters**

* `sheetId` — Required. sheet id

**Returns**

The sheet scroll state, or a nullish value when no state is available.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')

// scroll to cell D10
fWorksheet.scrollToCell(9, 3)

// get scroll state
const scrollState = fWorkbook.getScrollStateBySheetId(fWorksheet.getSheetId())
const { offsetX, offsetY, sheetViewStartRow, sheetViewStartColumn } = scrollState
console.log(scrollState) // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
```

**Types:** [`IScrollState`](https://unpkg.com/@univerjs/sheets-ui/lib/types/services/scroll-manager.service.d.ts) · [`Nullable`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.isCellEditing`

Check if the current active cell is in editing state

```typescript
isCellEditing(): boolean
```

**Returns**

True if the current active cell is in editing state, false otherwise

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const isEditing = fWorkbook.isCellEditing()
console.log(isEditing)
```

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.showSelection`

Set selection visible.

```typescript
showSelection(): FWorkbook
```

**Returns**

FWorkbook instance for chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.showSelection()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.startEditing`

Start the editing process of the current active cell

```typescript
startEditing(): boolean
```

**Returns**

Whether the editing process is started successfully

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.startEditing()
```

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.transparentSelection`

Set selection invisible, Unlike disableSelection, selection still works, you just can not see them.

```typescript
transparentSelection(): FWorkbook
```

**Returns**

FWorkbook instance for chaining

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.transparentSelection()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md)

**Package:** [`@univerjs/sheets-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/sheets-ui.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-ui/lib/types/facade/f-workbook.d.ts)

## `@univerjs-pro/range-preprocess`

### `FWorkbook.getPreprocessRanges`

Get all preprocess range information

```typescript
getPreprocessRanges(responseDataMode?: string): Record<string, ITableJson[]>
```

**Parameters**

* `responseDataMode` — Optional. The response data mode.

**Returns**

All preprocess range information

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const allTableInfo = fWorkbook.getPreprocessRanges()
console.log('debugger allTableInfo', allTableInfo)
```

**Types:** [`ITableJson`](https://unpkg.com/@univerjs/sheets-table/lib/types/types/type.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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

## `@univerjs-pro/sheets-pivot`

### `FWorkbook.addPivotTable`

Add a pivot table to the Workbook.

```typescript
addPivotTable(sourceInfo: IUnitRangeName & { subUnitId: string; }, positionType: PositionType, anchorCellInfo: IPivotCellPositionInfo): Promise<FPivotTable | undefined>
```

**Parameters**

* `sourceInfo` — Required. The source data range info of the pivot table.
* `positionType` — Required. whether new a sheet or insert a pivot table to the existing sheet.
* `anchorCellInfo` — Required. The target cell info of the pivot table.

**Returns**

A promise that resolves to the added pivot table instance.

**Examples**

```ts
// should ensure the sheet range A1:G9 is not empty
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const subUnitId = fWorksheet.getSheetId()
const sheetName = fWorksheet.getSheetName()
const sourceInfo = {
  unitId,
  subUnitId,
  sheetName,
  range: {
    startRow: 0,
    endRow: 8,
    startColumn: 0,
    endColumn: 6,
  },
}
const anchorCellInfo = {
  unitId,
  subUnitId,
  row: 0,
  col: 8,
}
const fPivotTable = await fWorkbook.addPivotTable(
  sourceInfo,
  univerAPI.Enum.PositionTypeEnum.Existing,
  anchorCellInfo,
)
await fPivotTable?.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
await fPivotTable?.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0)
```

**Types:** [`FPivotTable`](https://docs.univer.ai/ko-KR/reference/facade/pivot-table.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IUnitRangeName`](https://unpkg.com/@univerjs/core/lib/types/sheets/typedef.d.ts) · [`PositionType`](https://unpkg.com/@univerjs-pro/sheets-pivot/lib/types/const/const.d.ts) · [`IPivotCellPositionInfo`](https://unpkg.com/@univerjs-pro/sheets-pivot/lib/types/const/type.d.ts)

**Package:** [`@univerjs-pro/sheets-pivot`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-pivot.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-pivot/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getPivotTableByCell`

Get the pivot table id by the cell.

```typescript
getPivotTableByCell(unitId: string, subUnitId: string, row: number, col: number): FPivotTable | undefined
```

**Parameters**

* `unitId` — Required. The unit id of workbook.
* `subUnitId` — Required. The sheet id, which  pivot table belongs to.
* `row` — Required. The checked row.
* `col` — Required. The checked column.

**Returns**

The pivot table instance or undefined.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const subUnitId = fWorksheet.getSheetId()
const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8)
if (fPivotTable) {
  fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
}
```

**Types:** [`FPivotTable`](https://docs.univer.ai/ko-KR/reference/facade/pivot-table.md)

**Package:** [`@univerjs-pro/sheets-pivot`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-pivot.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-pivot/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.getPivotTableById`

Get the pivot table by the pivot table id.

```typescript
getPivotTableById(pivotTableId: string): FPivotTable | undefined
```

**Parameters**

* `pivotTableId` — Required. The pivot table id.

**Returns**

The pivot table instance or undefined.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const mockId = 'abc123456'
const fPivotTable = fWorkbook.getPivotTableById(mockId)
if (fPivotTable) {
  fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
}
```

**Types:** [`FPivotTable`](https://docs.univer.ai/ko-KR/reference/facade/pivot-table.md)

**Package:** [`@univerjs-pro/sheets-pivot`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-pivot.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-pivot/lib/types/facade/f-workbook.d.ts)

## `@univerjs-pro/sheets-pivot-chart`

### `FWorkbook.getPivotChartById`

Returns a PivotChart in this workbook by its stable identifier.

```typescript
getPivotChartById(pivotChartId: string): FSheetPivotChart | null
```

**Parameters**

* `pivotChartId` — Required. The identifier returned by `FSheetPivotChart.getId()`.

**Returns**

A live facade, or `null` if it is absent from this workbook.

**Examples**

```ts
import '@univerjs-pro/sheets-pivot-chart/facade'

const fWorkbook = univerAPI.getActiveWorkbook()
const fPivotChart = fWorkbook.getPivotChartById('pivot-chart-1')
console.log(fPivotChart?.getInfo())
```

**Types:** [`FSheetPivotChart`](https://docs.univer.ai/ko-KR/reference/facade/sheet-pivot-chart.md)

**Package:** [`@univerjs-pro/sheets-pivot-chart`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-pivot-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-pivot-chart/lib/types/facade/f-workbook.d.ts)

## `@univerjs-pro/sheets-print`

### `FWorkbook.closePrintDialog`

Close print preview dialog.

```typescript
closePrintDialog(): void
```

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.openPrintDialog()

// Close print dialog after 3 seconds
setTimeout(() => {
  fWorkbook.closePrintDialog()
}, 3000)
```

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.openPrintDialog`

Open print preview dialog.

```typescript
openPrintDialog(): void
```

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.openPrintDialog()
```

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.print`

Using current print config and render config to print.

```typescript
print(): void
```

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Update print layout config by default
fWorkbook.updatePrintConfig({})

// Update print render config by default
fWorkbook.updatePrintRenderConfig({})

// Start print
fWorkbook.print()
```

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.saveScreenshotToClipboard`

Save screenshot of current range to clipboard.
This API is only available with a license. Without a license, usage is restricted, and save operations will return `false`.
We use the Clipboard API to save the image to the clipboard, which may fail in an insecure network environment or in some unsupported browsers. A successful save will return `true`.

```typescript
saveScreenshotToClipboard(): Promise<boolean>
```

**Returns**

* The result of saving the screenshot to the clipboard.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const result = await fWorkbook.saveScreenshotToClipboard()
console.log(result) // true or false
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.updatePrintConfig`

Update print config, include print area, page-setting, scale, freeze, margin, and etc.

```typescript
updatePrintConfig(config: ISheetPrintLayoutConfig): FWorkbook
```

**Parameters**

* `config` — Required. The print layout config.

**Returns**

* The current workbook instance for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
if (!fWorksheet) throw new Error('fWorksheet is not available')
const subUnitId = fWorksheet.getSheetId()

// Update print layout config
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet, // print current sheet
  subUnitIds: [subUnitId],
  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 paper size
  scale: univerAPI.Enum.PrintScale.FitPage, // fit content to page
  freeze: [univerAPI.Enum.PrintFreeze.Row], // freeze row headers
  margin: univerAPI.Enum.PrintPaperMargin.Normal, // normal margin
  // ... other settings
})

// Start print
fWorkbook.print()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`ISheetPrintLayoutConfig`](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/common/types.d.ts)

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)

### `FWorkbook.updatePrintRenderConfig`

Update print render config, include print header-footer setting, alignment, gridline, and etc.

```typescript
updatePrintRenderConfig(config: ISheetPrintRenderConfig): FWorkbook
```

**Parameters**

* `config` — Required. The print render config.

**Returns**

* The current workbook instance for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Update print layout config by default
fWorkbook.updatePrintConfig({})

// Update print render config
fWorkbook.updatePrintRenderConfig({
  gridlines: true, // show gridlines
  hAlign: univerAPI.Enum.PrintAlign.Middle, // horizontal align middle
  vAlign: univerAPI.Enum.PrintAlign.Middle, // vertical align middle
  headerFooter: [
    // the array of header and footer elements to include, here is page numbers and worksheet name
    univerAPI.Enum.PrintHeaderFooter.PageSize,
    univerAPI.Enum.PrintHeaderFooter.WorksheetTitle,
  ],
  // ... other settings
})

// Start print
fWorkbook.print()
```

**Types:** [`FWorkbook`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md) · [`ISheetPrintRenderConfig`](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/common/types.d.ts)

**Package:** [`@univerjs-pro/sheets-print`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/sheets-print.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-print/lib/types/facade/f-workbook.d.ts)