# Menu & UI

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

| Packages | `@univerjs/ui` |
| -------- | -------------- |

This is the builder for adding a menu to Univer. You shall never construct this
class by yourself. Instead, call `createMenu` of `FUniver` to create a instance.

Please notice that until the `appendTo` method is called, the menu item is not added to the UI.

Please note that this menu cannot have submenus. If you want to
have submenus, please use `FSubmenu`.

> This class should not be instantiated directly. Use factory methods on `univerAPI` instead.

## Overview

### @univerjs/ui

| Method                                                  | Description                                                                           |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`addSeparator`](#addseparator)                         | Add a separator to the submenu                                                        |
| [`addSubmenu`](#addsubmenu)                             | Add a menu to the submenu                                                             |
| [`appendTo`](#appendto)                                 | Append the menu to any menu position on Univer UI                                     |
| [`disableShortcut`](#disableshortcut)                   | Disable shortcuts of Univer                                                           |
| [`dispatchShortcutEvent`](#dispatchshortcutevent)       | Dispatch a KeyboardEvent to the shortcut service and return the matched shortcut item |
| [`enableShortcut`](#enableshortcut)                     | Enable shortcuts of Univer                                                            |
| [`MenuManagerPosition`](#menumanagerposition)           | -                                                                                     |
| [`registerCellCustomRender`](#registercellcustomrender) | Register custom cell renderers for sheets                                             |
| [`RibbonPosition`](#ribbonposition)                     | -                                                                                     |
| [`RibbonStartGroup`](#ribbonstartgroup)                 | -                                                                                     |
| [`triggerShortcut`](#triggershortcut)                   | Trigger shortcut of Univer by a KeyboardEvent and return the matched shortcut item    |

## APIs

### Lifecycle & Creation

### `addSeparator`

Add a separator to the submenu.

**Signature**

```typescript
addSeparator(): this
```

**Returns**

* `this` — The FSubmenu itself for chaining calls.

**Examples**

```ts
// Create two leaf menus.
const menu1 = univerAPI.createMenu({
  id: 'submenu-nested-1',
  title: 'Item 1',
  action: () => {
    console.log('Item 1 clicked');
  }
});
const menu2 = univerAPI.createMenu({
  id: 'submenu-nested-2',
  title: 'Item 2',
  action: () => {
    console.log('Item 2 clicked');
  }
});

// Add the leaf menus to a submenu and add a separator between them.
// Append the submenu to the `contextMenu.others` section.
univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })
  .addSubmenu(menu1)
  .addSeparator()
  .addSubmenu(menu2)
  .appendTo('contextMenu.others');
```

Source: 

`@univerjs/ui`

### `addSubmenu`

Add a menu to the submenu. It can be a `FMenu` or a `FSubmenu`.

**Signature**

```typescript
addSubmenu(submenu: FMenu | FSubmenu): this
```

**Parameters**

* `submenu` `FMenu | FSubmenu` — *No description*

**Returns**

* `this` — The FSubmenu itself for chaining calls.

**Examples**

```ts
// Create two leaf menus.
const menu1 = univerAPI.createMenu({
  id: 'submenu-nested-1',
  title: 'Item 1',
  action: () => {
    console.log('Item 1 clicked');
  }
});
const menu2 = univerAPI.createMenu({
  id: 'submenu-nested-2',
  title: 'Item 2',
  action: () => {
    console.log('Item 2 clicked');
  }
});

// Add the leaf menus to a submenu.
const submenu = univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })
  .addSubmenu(menu1)
  .addSeparator()
  .addSubmenu(menu2);

// Create a root submenu append to the `contextMenu.others` section.
univerAPI.createSubmenu({ id: 'custom-submenu', title: 'Custom Submenu' })
  .addSubmenu(submenu)
  .appendTo('contextMenu.others');
```

Source: 

`@univerjs/ui`

### Setters & Modifiers

### `disableShortcut`

Disable shortcuts of Univer.

**Signature**

```typescript
disableShortcut(): this
```

**Returns**

* `this` — The Facade API instance itself for chaining.

**Examples**

```ts
const fShortcut = univerAPI.getShortcut();
fShortcut.disableShortcut();
```

Source: 

`@univerjs/ui`

### `enableShortcut`

Enable shortcuts of Univer.

**Signature**

```typescript
enableShortcut(): this
```

**Returns**

* `this` — The Facade API instance itself for chaining.

**Examples**

```ts
fShortcut.enableShortcut(); // Use the FShortcut instance used by disableShortcut before, do not create a new instance
```

Source: 

`@univerjs/ui`

### Miscellaneous

### `registerCellCustomRender`

Register custom cell renderers for sheets.

**Signature**

```typescript
registerCellCustomRender(customRender: Nullable<ICellCustomRender[]>, effect?: InterceptorEffectEnum, priority?: number): IDisposable
```

**Parameters**

* `customRender` `Nullable<ICellCustomRender[]>` — Custom renderer definitions, or `null` to clear the registration.
* `effect` `InterceptorEffectEnum` *(optional)* — Interceptor effect phase. Defaults to `InterceptorEffectEnum.Style`.
* `priority` `number` *(optional)* — Optional interceptor priority.

**Returns**

* `IDisposable` — A disposable registration handle.

Source: 

`@univerjs/sheets-ui`

### `appendTo`

Append the menu to any menu position on Univer UI.

**Signature**

```typescript
appendTo(path: string | string[]): void
```

**Parameters**

* `path` `string | string[]` — *No description*

**Examples**

```ts
// This menu item will appear on every `contextMenu.others` section.
univerAPI.createMenu({
  id: 'custom-menu-id-1',
  title: 'Custom Menu 1',
  action: () => {
    console.log('Custom Menu 1 clicked');
  },
}).appendTo('contextMenu.others');

// This menu item will only appear on the `contextMenu.others` section on the main area.
univerAPI.createMenu({
  id: 'custom-menu-id-2',
  title: 'Custom Menu 2',
  action: () => {
    console.log('Custom Menu 2 clicked');
  },
}).appendTo(['contextMenu.mainArea', 'contextMenu.others']);
```

Source: 

`@univerjs/ui`

### `dispatchShortcutEvent`

Dispatch a KeyboardEvent to the shortcut service and return the matched shortcut item.

**Signature**

```typescript
dispatchShortcutEvent(e: KeyboardEvent): IShortcutItem<object> | undefined
```

**Parameters**

* `e` `KeyboardEvent` — *No description*

**Returns**

* `any` — The matched shortcut item.

**Examples**

```ts
const fShortcut = univerAPI.getShortcut();
const pseudoEvent = new KeyboardEvent('keydown', { key: 's', ctrlKey: true });
const ifShortcutItem = fShortcut.dispatchShortcutEvent(pseudoEvent);
if (ifShortcutItem) {
  const commandId = ifShortcutItem.id;
  // Do something with the commandId.
}
```

Source: 

`@univerjs/ui`

### `MenuManagerPosition`

**Signature**

```typescript
MenuManagerPosition: any
```

**Returns**

* `any` — See signature above.

Source: 

`@univerjs/ui`

### `RibbonPosition`

**Signature**

```typescript
RibbonPosition: any
```

**Returns**

* `any` — See signature above.

Source: 

`@univerjs/ui`

### `RibbonStartGroup`

**Signature**

```typescript
RibbonStartGroup: any
```

**Returns**

* `any` — See signature above.

Source: 

`@univerjs/ui`

### `triggerShortcut`

Trigger shortcut of Univer by a KeyboardEvent and return the matched shortcut item.

**Signature**

```typescript
triggerShortcut(e: KeyboardEvent): IShortcutItem<object> | undefined
```

**Parameters**

* `e` `KeyboardEvent` — *No description*

**Returns**

* `any` — The matched shortcut item.

**Examples**

```ts
// Assum the current sheet is empty sheet.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1');

// Set A1 cell active and set value to 'Hello Univer'.
fRange.activate();
fRange.setValue('Hello Univer');
console.log(fRange.getCellStyle().bold); // false

// Set A1 cell bold by shortcut.
const fShortcut = univerAPI.getShortcut();
const pseudoEvent = new KeyboardEvent('keydown', {
  key: 'b',
  ctrlKey: true,
  keyCode: univerAPI.Enum.KeyCode.B
});
const ifShortcutItem = fShortcut.triggerShortcut(pseudoEvent);
if (ifShortcutItem) {
  const commandId = ifShortcutItem.id;
  console.log(fRange.getCellStyle().bold); // true
}
```

Source: 

`@univerjs/ui`