# 核心功能

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/core](https://docs.univer.ai/zh-TW/guides/sheets/features/core)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/core.md](https://docs.univer.ai/zh-TW/guides/sheets/features/core.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/index.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/index.zh-TW.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-core",
      "locale": "@univerjs/preset-sheets-core/locales/zh-TW",
      "style": "@univerjs/preset-sheets-core/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/core"
    },
    {
      "client": "@univerjs/engine-formula"
    },
    {
      "client": "@univerjs/engine-render"
    },
    {
      "client": "@univerjs/design",
      "locale": "@univerjs/design/locale/zh-TW",
      "style": "@univerjs/design/lib/index.css"
    },
    {
      "client": "@univerjs/ui",
      "locale": "@univerjs/ui/locale/zh-TW",
      "style": "@univerjs/ui/lib/index.css"
    },
    {
      "client": "@univerjs/sheets"
    },
    {
      "client": "@univerjs/sheets-ui",
      "locale": "@univerjs/sheets-ui/locale/zh-TW",
      "style": "@univerjs/sheets-ui/lib/index.css",
      "facade": "@univerjs/sheets-ui/facade"
    },
    {
      "client": "@univerjs/sheets",
      "locale": "@univerjs/sheets/locale/zh-TW",
      "facade": "@univerjs/sheets/facade"
    },
    {
      "client": "@univerjs/sheets-ui",
      "locale": "@univerjs/sheets-ui/locale/zh-TW",
      "style": "@univerjs/sheets-ui/lib/index.css",
      "facade": "@univerjs/sheets-ui/facade"
    },
    {
      "client": "@univerjs/sheets-formula",
      "facade": "@univerjs/sheets-formula/facade"
    },
    {
      "client": "@univerjs/sheets-formula-ui",
      "locale": "@univerjs/sheets-formula-ui/locale/zh-TW",
      "style": "@univerjs/sheets-formula-ui/lib/index.css"
    },
    {
      "client": "@univerjs/sheets-numfmt",
      "facade": "@univerjs/sheets-numfmt/facade"
    },
    {
      "client": "@univerjs/sheets-numfmt-ui",
      "locale": "@univerjs/sheets-numfmt-ui/locale/zh-TW",
      "style": "@univerjs/sheets-numfmt-ui/lib/index.css"
    }
  ],
  "server": false
}
```

Univer Sheets 的核心功能包含了電子表格編輯器、公式引擎、渲染引擎、數字格式化引擎、設計系統和 UI 組件庫等。它們共同構成了一個強大的電子表格處理平台，支援多種電子表格格式和複雜的電子表格操作。

## 特性

Univer Sheets 的核心功能包括：

* **電子表格渲染**：支援 Univer Sheets 的渲染和游標、選區的繪製。
* **儲存格樣式**：支援對電子表格中的儲存格進行樣式設置，包括字體、顏色、邊框、對齊等。
* **公式計算**：支援在電子表格中添加和計算公式，支援幾乎所有的 Excel 公式，包括數學、統計、文本、日期等函數。
* **數字格式化**：支援對電子表格中的數字進行格式化，包括貨幣、百分比、日期等格式。
* **格線和凍結窗格**：支援顯示格線和凍結窗格功能，方便用戶查看和編輯大數據量的電子表格。
* **默認樣式**：支援對電子表格的默認樣式進行設置，包括默認字體、字號、顏色等。
* **外掛系統**：支援外掛系統，可以自訂外掛，這也是 Univer 核心架構能力之一。

## 外掛模式

### 安裝

#### npm

```bash
npm install @univerjs/core @univerjs/design @univerjs/engine-render @univerjs/engine-formula @univerjs/ui @univerjs/docs @univerjs/docs-ui @univerjs/sheets @univerjs/sheets-ui @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui
```

#### pnpm

```bash
pnpm add @univerjs/core @univerjs/design @univerjs/engine-render @univerjs/engine-formula @univerjs/ui @univerjs/docs @univerjs/docs-ui @univerjs/sheets @univerjs/sheets-ui @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui
```

#### yarn

```bash
yarn add @univerjs/core @univerjs/design @univerjs/engine-render @univerjs/engine-formula @univerjs/ui @univerjs/docs @univerjs/docs-ui @univerjs/sheets @univerjs/sheets-ui @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui
```

#### bun

```bash
bun add @univerjs/core @univerjs/design @univerjs/engine-render @univerjs/engine-formula @univerjs/ui @univerjs/docs @univerjs/docs-ui @univerjs/sheets @univerjs/sheets-ui @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui
```

### 使用

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import DesignZhTW from '@univerjs/design/locale/zh-TW'
import { UniverDocsPlugin } from '@univerjs/docs'
import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
import DocsUIZhTW from '@univerjs/docs-ui/locale/zh-TW'
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
import { UniverSheetsPlugin } from '@univerjs/sheets'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
import SheetsFormulaUIZhTW from '@univerjs/sheets-formula-ui/locale/zh-TW'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
import SheetsNumfmtUIZhTW from '@univerjs/sheets-numfmt-ui/locale/zh-TW'
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
import SheetsUIZhTW from '@univerjs/sheets-ui/locale/zh-TW'
import SheetsZhTW from '@univerjs/sheets/locale/zh-TW'
import { UniverUIPlugin } from '@univerjs/ui'
import UIZhTW from '@univerjs/ui/locale/zh-TW'
import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs/docs-ui/lib/index.css'
import '@univerjs/sheets-ui/lib/index.css'
import '@univerjs/sheets-formula-ui/lib/index.css'
import '@univerjs/sheets-numfmt-ui/lib/index.css'
import '@univerjs/engine-formula/facade'
import '@univerjs/ui/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/sheets/facade'
import '@univerjs/sheets-ui/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'

const univer = new Univer({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      DesignZhTW,
      UIZhTW,
      DocsUIZhTW,
      SheetsZhTW,
      SheetsUIZhTW,
      SheetsFormulaUIZhTW,
      SheetsNumfmtUIZhTW,
    ),
  },
})

univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
})
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverDocsUIPlugin)
univer.registerPlugin(UniverSheetsPlugin)
univer.registerPlugin(UniverSheetsUIPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsFormulaUIPlugin)
univer.registerPlugin(UniverSheetsNumfmtPlugin)
univer.registerPlugin(UniverSheetsNumfmtUIPlugin)
```

### 外掛與配置

#### @univerjs/core

本外掛是 Univer 的核心庫，提供了創建 Univer 實例、主題、語言等基礎功能。

```typescript
interface UniverParameter {
  // Univer 實例的主題，默認使用 defaultTheme
  theme: IStyleSheet
  // 是否使用暗黑模式，默認為 false
  darkMode?: boolean
  // Univer 實例的語言環境
  locale: LocaleType
  // 要使用的語言環境對象，鍵為語言環境類型，值為對應的語言環境對象
  locales: ILocales
  // Univer 實例的日誌級別
  logLevel?: LogLevel
}
```

參考：[`Univer`](https://docs.univer.ai/zh-TW/reference/classes/univer.md)

#### @univerjs/engine-render

本外掛是 Univer 的渲染引擎，負責渲染、滾動條、游標和選區等的繪製。其提供了 `UniverRenderEnginePlugin` 外掛。

參考：[@univerjs/engine-render](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/engine-render.md)

#### @univerjs/engine-formula

本外掛是 Univer 的公式引擎，負責公式的計算和處理。其提供了 `UniverFormulaEnginePlugin` 外掛。

參考：[@univerjs/engine-formula](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/engine-formula.md)

#### @univerjs/design

本外掛是 Univer 的設計系統，提供了所有的基礎組件和樣式。

詳見： [UI 章節](https://docs.univer.ai/zh-TW/guides/docs/ui/overview.md)

#### @univerjs/ui

本外掛是 Univer 的 UI 基座。其提供了 `UniverUIPlugin` 外掛。

`UniverUIPlugin` 提供了一些配置項，可用於基礎佈局的配置。

```typescript
interface IUniverUIConfig {
  // 容器元素，可以是字串或者 DOM 元素。
  container?: string | HTMLElement
  // 是否顯示頭部
  header?: boolean
  // 是否顯示頭部工具列
  toolbar?: boolean
  // 頭部工具列的類型。'classic': 默認經典模式；'grid': 兩行網格模式；'collapsed': 緊湊模式；'simple'：不分組模式
  ribbonType?: RibbonType
  // 是否顯示右鍵菜單
  contextMenu?: boolean
  // 是否禁用自動聚焦
  disableAutoFocus?: true
  // 依賴注入的覆蓋配置
  override?: DependencyOverride
  // 菜單配置
  menu?: MenuConfig
}
```

其中，`menu` 配置項可以用於簡單地設置某些特定菜單項的顯示或隱藏等狀態：

```typescript
univer.registerPlugin(UniverSheetsUIPlugin, {
  menu: {
    'sheet.command.set-range-bold': {
      hidden: true,
    },
    'sheet.command.set-range-italic': {
      hidden: true,
      disabled: true,
    },
  },
})
```

這裡的 `'sheet.command.set-range-bold'` 和 `'sheet.command.set-range-italic'` 是命令的名稱，表示對應的菜單項。可參考下方的 [菜單項 ID 列表](#menu-item-id-list)。

參考：[@univerjs/ui](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/ui.md)

#### @univerjs/docs

本外掛是 Univer Docs 的核心外掛。其提供了 `UniverDocsPlugin` 外掛。

參考：[@univerjs/docs](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/docs.md)

#### @univerjs/docs-ui

本外掛是 Univer Docs 的 UI 外掛，包含了文件編輯器的 UI 組件和交互。其提供了 `UniverDocsUIPlugin` 外掛。

參考：[@univerjs/docs-ui](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/docs-ui.md)

#### @univerjs/sheets

本外掛是 Univer Sheets 的核心外掛，提供了電子表格編輯器的核心功能。其提供了 `UniverSheetsPlugin` 外掛。

`UniverSheetsPlugin` 提供了一些配置項，可用於電子表格編輯器的配置。

```typescript
interface IUniverSheetsConfig {
  // 如果行樣式和列樣式都設置了，行樣式是否優先於列樣式
  isRowStylePrecedeColumnStyle?: boolean
  // 自動高度是否適用於合併儲存格
  autoHeightForMergedCells?: boolean
  /**
   * 是否將凍結狀態同步到實時協作中的其他用戶。
   * @default true
   */
  freezeSync?: boolean
}
```

參考：[@univerjs/sheets](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/sheets.md)

#### @univerjs/sheets-ui

本外掛是 Univer Sheets 的 UI 外掛，包含了電子表格編輯器的 UI 組件和交互。其提供了 `UniverSheetsUIPlugin` 外掛。

`UniverSheetsUIPlugin` 提供了一些配置項，可用於電子表格編輯器的 UI 配置。

```typescript
interface IUniverSheetsUIConfig {
  // 是否顯示底部。
  footer?:
    | false
    | {
        // Sheet bar 是子表管理器，包括添加/切換/刪除子表。
        sheetBar?: boolean
        // 統計欄包括当前選區的統計信息，如計數、總和、平均值等。
        statisticBar?: boolean
        // 在底部的菜單，包括高亮、格線等。
        menus?: boolean
        // 底部的縮放滑塊。
        zoomSlider?: boolean
        /**
         * 工作表欄中“添加工作表”按鈕的配置。
         */
        addSheetButtonConfig?: {
          /**
           * 是否顯示工作表欄中的“添加工作表”按鈕。
           * 當 `footer` 或 `footer.sheetBar` 為 false 時，此配置將不起作用，因為工作表欄將不會被渲染。
           * @default true
           */
          show?: boolean
          /**
           * 新建工作表的預設行數。
           * @default 1000
           */
          defaultRowCount?: number
          /**
           * 新建工作表的預設列數。
           * @default 20
           */
          defaultColumnCount?: number
        }
      }
  // 是否顯示公式欄
  formulaBar?: boolean
  clipboardConfig?: {
    // 在貼上操作後是否顯示貼上選項按鈕
    hidePasteOptions?: boolean
  }
  // 滾動條配置
  scrollConfig?: IScrollBarProps
  /**
   * 權限保護範圍陰影顯示策略。
   * - true 或 'always'：顯示所有受保護範圍的陰影（默認行為）
   * - 'non-editable'：僅顯示無法編輯的範圍的陰影（編輯權限為 false）
   * - 'non-viewable'：僅顯示無法查看的範圍的陰影（查看權限為 false）
   * - false 或 'none'：從不顯示受保護範圍的陰影
   * @default true
   */
  protectedRangeShadow?: boolean | 'always' | 'non-editable' | 'non-viewable' | 'none'
  // 是否禁用強制字串警告。
  disableForceStringAlert?: boolean
  // 是否禁用強制字串標記。
  disableForceStringMark?: boolean
}
```

參考：[@univerjs/sheets-ui](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/sheets-ui.md)

## 行動裝置支援

先設定[行動版編輯器](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md#mobile-support)。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在**開啟文件前**完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

| 套件                            | 桌面版註冊                         | 行動版註冊                               |
| ----------------------------- | ----------------------------- | ----------------------------------- |
| `@univerjs/sheets-formula-ui` | `UniverSheetsFormulaUIPlugin` | `UniverSheetsFormulaMobileUIPlugin` |
| `@univerjs/sheets-numfmt-ui`  | `UniverSheetsNumfmtUIPlugin`  | `UniverSheetsNumfmtMobileUIPlugin`  |

## 預設模式

### 安裝

#### npm

```bash
npm install @univerjs/presets @univerjs/preset-sheets-core
```

#### pnpm

```bash
pnpm add @univerjs/presets @univerjs/preset-sheets-core
```

#### yarn

```bash
yarn add @univerjs/presets @univerjs/preset-sheets-core
```

#### bun

```bash
bun add @univerjs/presets @univerjs/preset-sheets-core
```

### 使用

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(UniverPresetSheetsCoreZhTW),
  },
  presets: [UniverSheetsCorePreset()],
})

univerAPI.createWorkbook({})
```

### 預設與配置

#### @univerjs/presets

本預設提供了創建 Univer 應用所需的 `createUniver` 方法，以及暴露了 **@univerjs/core** 和 **@univerjs/design** 的所有方法和對象。

`createUniver` 方法接受一個配置對象，包含主題、語言、預設等選項，返回一個 `Univer` 實例 `univer` 和用於調用 Facade API 的 `FUniver` 實例 `univerAPI`。

```typescript
interface CreateUniverParameter {
  // Univer 實例的主題，默認使用 defaultTheme
  theme: IStyleSheet
  // 是否使用暗黑模式，默認為 false。
  darkMode?: boolean
  // Univer 實例的語言環境
  locale: LocaleType
  region?: LocaleType
  // 要使用的語言環境對象，鍵為語言環境類型，值為對應的語言環境對象
  locales: ILocales
  // Univer 實例的日誌級別
  logLevel?: LogLevel
  // 要使用的預設列表。
  presets: IPresets[]
  // 要使用的外掛列表。
  plugins: IPlugins[]
}
```

參考：[`createUniver`](https://docs.univer.ai/zh-TW/reference/methods/create-univer.md)

#### @univerjs/preset-sheets-core

本預設是 Univer Sheets 的核心預設，包含了文件編輯器、公式引擎、渲染引擎等電子文件必要的核心功能。

```typescript
interface IUniverSheetsCorePresetConfig {
  // 容器元素，可以是字串或者 DOM 元素
  container?: string | HTMLElement
  // 是否顯示頭部
  header?: boolean
  // 是否顯示頭部工具列
  toolbar?: boolean
  // 頭部工具列的類型。'classic': 默認經典模式；'grid': 兩行網格模式；'collapsed': 緊湊模式；'simple'：不分組模式
  ribbonType?: RibbonType
  // 是否顯示底部。
  footer?:
    | false
    | {
        // Sheet bar 是子表管理器，包括添加/切換/刪除子表。
        sheetBar?: boolean
        // 統計欄包括当前選區的統計信息，如計數、總和、平均值等。
        statisticBar?: boolean
        // 在底部的菜單，包括高亮、格線等。
        menus?: boolean
        // 底部的縮放滑塊。
        zoomSlider?: boolean
        /**
         * 工作表欄中“添加工作表”按鈕的配置。
         */
        addSheetButtonConfig?: {
          /**
           * 是否顯示工作表欄中的“添加工作表”按鈕。
           * 當 `footer` 或 `footer.sheetBar` 為 false 時，此配置將不起作用，因為工作表欄將不會被渲染。
           * @default true
           */
          show?: boolean
          /**
           * 新建工作表的預設行數。
           * @default 1000
           */
          defaultRowCount?: number
          /**
           * 新建工作表的預設列數。
           * @default 20
           */
          defaultColumnCount?: number
        }
      }
  // 是否顯示右鍵菜單
  contextMenu?: boolean
  // 是否禁用自動聚焦
  disableAutoFocus?: true
  // 菜單配置
  menu?: MenuConfig

  sheets?: {
    // 如果行樣式和列樣式都設置了，行樣式是否優先於列樣式
    isRowStylePrecedeColumnStyle?: boolean
    // 自動高度是否適用於合併儲存格
    autoHeightForMergedCells?: boolean
    /**
     * 是否將凍結狀態同步到實時協作中的其他用戶。
     * @default true
     */
    freezeSync?: boolean

    clipboardConfig?: {
      // 在貼上操作後是否顯示貼上選項按鈕
      hidePasteOptions?: boolean
    }
    // 滾動條配置
    scrollConfig?: IScrollBarProps
    /**
     * 權限保護範圍陰影顯示策略。
     * - true 或 'always'：顯示所有受保護範圍的陰影（默認行為）
     * - 'non-editable'：僅顯示無法編輯的範圍的陰影（編輯權限為 false）
     * - 'non-viewable'：僅顯示無法查看的範圍的陰影（查看權限為 false）
     * - false 或 'none'：從不顯示受保護範圍的陰影
     * @default true
     */
    protectedRangeShadow?: boolean | 'always' | 'non-editable' | 'non-viewable' | 'none'
    // 是否禁用強制字串警告。
    disableForceStringAlert?: boolean
    // 是否禁用強制字串標記。
    disableForceStringMark?: boolean
  }

  // ... 更多配置項
}
```

其中，`menu` 配置項可以用於簡單地設置某些特定菜單項的顯示或隱藏等狀態：

```typescript
UniverSheetsCorePreset({
  menu: {
    'sheet.command.set-range-bold': {
      hidden: true,
    },
    'sheet.command.set-range-italic': {
      hidden: true,
      disabled: true,
    },
  },
})
```

這裡的 `'sheet.command.set-range-bold'` 和 `'sheet.command.set-range-italic'` 是命令的名稱，表示對應的菜單項。可參考下方的 [菜單項 ID 列表](#menu-item-id-list)。

參考：[@univerjs/preset-sheets-core](https://docs.univer.ai/zh-TW/reference/packages/presets/univerjs/preset-sheets-core.md)

## 工具列佈局與 `RibbonType`

通過配置 `IUniverSheetsCorePresetConfig` 或 `IUniverUIConfig` 的 `ribbonType` 屬性，可以設置工具列的佈局。

`ribbonType` 支援設置為以下四種模式：

* `classic`：默認經典模式，分組在上方，工具列平鋪在下方，適合習慣傳統佈局的用戶。
* `grid`：網格模式，保留頂部頁籤，下方各工具群組以兩行網格排列，適合需要同時顯示更多工具的桌面佈局。
* `collapsed`：緊湊模式，分組與工具列平鋪在同一行，適合垂直屏幕空間有限的場景。
* `simple`：不分組模式，將所有工具放在一個平鋪的列表中，適合熟悉工具列功能的用戶。



## 選單順序與網格佈局

初始化設定與執行時的 [`univerAPI.updateMenuConfig()`](https://docs.univer.ai/zh-TW/reference/facade/univer.md#updatemenuconfig) 使用相同的 `menu` 結構。鍵可以是 Ribbon 頁籤識別碼（如 `ribbon.insert`）、群組識別碼（如 `ribbon.start.format`）或選單項目 ID。

`order` 依數值由小到大排列同層節點：Ribbon 中的頁籤、頁籤內的群組，以及群組或子選單內的項目。它不會將選單移至其他群組。頁籤與群組也可以使用 `@univerjs/ui` 匯出的 `RibbonPosition` 及各群組列舉作為鍵。

### 初始化設定

依接入模式將以下選項合併到既有的初始化設定中，保留其他外掛、語言、主題與容器設定，請勿重複註冊同一外掛。

```ts
import type { MenuConfig } from '@univerjs/ui'

const menu: MenuConfig = {
  'ribbon.insert': { order: -1 },
  'ribbon.start.format': { order: -1 },
  'sheet.command.set-range-font-family': {
    order: 0,
    gridLayout: { row: 1, column: 1, width: 160 },
  },
}
```

#### 外掛模式

```typescript
import { UniverUIPlugin } from '@univerjs/ui'

univer.registerPlugin(UniverUIPlugin, {
  ribbonType: 'grid',
  menu,
})
```

#### 預設模式

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import { createUniver } from '@univerjs/presets'

const { univerAPI } = createUniver({
  presets: [
    UniverSheetsCorePreset({
      ribbonType: 'grid',
      menu,
    }),
  ],
})
```

### 執行時更新

公開 Facade 會合併變更並立即更新 UI。未指定的屬性保留既有設定或 Schema 預設值，設定也會套用至後續註冊的選單。外掛模式下，請先匯入 `@univerjs/ui/facade`。

```ts
import '@univerjs/ui/facade'

univerAPI.updateMenuConfig({
  'sheet.command.set-range-bold': {
    order: 0,
    gridLayout: { row: 2, column: 2 },
  },
  'sheet.command.set-range-italic': {
    gridLayout: { row: 2, column: 1 },
  },
})
```

`gridLayout` 僅在 `ribbonType: 'grid'` 時生效。每個群組固定兩列，`row` 與 `column` 皆從 1 開始。明確指定的座標決定按鈕位置，因此只修改 `order` 不會移動已指定座標的按鈕；交換位置時應同時修改兩個按鈕，避免重疊。選用欄位包括 `rowSpan`、`columnSpan`、`showLabel`、`width` 與 `iconSize`，尺寸單位為像素。限制與預設值請見 [`IRibbonGridLayout`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/ui.md#iribbongridlayout)。

### 自訂選單的位置

`createMenu()` 與 `createSubmenu()` 也支援 `order` 及 `gridLayout`。對子選單而言，這兩個欄位控制 Ribbon 上的觸發入口，不會改變彈出選單的內部佈局。例如，在歷史操作群組的第三欄新增按鈕：

```ts
univerAPI
  .createMenu({
    id: 'custom-action',
    title: 'Custom action',
    action: () => console.log('Custom action clicked'),
    order: 4,
    gridLayout: { row: 1, column: 3, showLabel: true, width: 96 },
  })
  .appendTo('ribbon.start.history')
```

## 菜單項 ID 列表

> [!NOTE]
> 你可以通過菜單項 DOM 元素上的 
> 
> `data-u-command`
> 
>  屬性來獲取菜單項的 ID。

### 工具列菜單項

| 菜單項 ID                                                | 菜單項名稱         |
| ----------------------------------------------------- | ------------- |
| univer.command.undo                                   | 復原            |
| univer.command.redo                                   | 重做            |
| sheet.command.set-once-format-painter                 | 複製格式          |
| sheet.command.set-range-bold                          | 粗體            |
| sheet.command.set-range-italic                        | 斜體            |
| sheet.command.set-range-underline                     | 底線            |
| sheet.command.set-range-stroke                        | 刪除線           |
| sheet.command.set-range-font-family                   | 字體            |
| sheet.command.set-range-fontsize                      | 字號            |
| sheet.command.set-range-text-color                    | 文字顏色          |
| sheet.command.set-background-color                    | 儲存格顏色         |
| sheet.command.set-border-basic                        | 邊框            |
| sheet.command.set-horizontal-text-align               | 水平對齊          |
| sheet.command.set-vertical-text-align                 | 垂直對齊          |
| sheet.command.set-text-wrap                           | 文字換行          |
| sheet.command.set-text-rotation                       | 文字旋轉          |
| sheet.command.add-worksheet-merge                     | 合併儲存格         |
| sheet.command.add-worksheet-merge-all                 | 合併儲存格 - 全部合併  |
| sheet.command.add-worksheet-merge-vertical            | 合併儲存格 - 垂直合併  |
| sheet.command.add-worksheet-merge-horizontal          | 合併儲存格 - 水平合併  |
| sheet.command.remove-worksheet-merge                  | 合併儲存格 - 取消合併  |
| sheet.operation.open.conditional.formatting.panel     | 條件式格式設定       |
| formula-ui.operation.insert-function                  | 函數            |
| formula-ui.operation.more-functions                   | 函數 - 更多函數     |
| sheet.menu.sheets-sort                                | 排序            |
| sheet.command.sort-range-asc                          | 排序 - 當前區域升冪   |
| sheet.command.sort-range-asc-ext                      | 排序 - 拓展區域升冪   |
| sheet.command.sort-range-desc                         | 排序 - 當前區域降冪   |
| sheet.command.sort-range-desc-ext                     | 排序 - 拓展區域降冪   |
| sheet.command.sort-range-custom                       | 排序 - 自訂排序     |
| sheet.menu.image                                      | 圖片            |
| sheet.command.insert-float-image                      | 圖片 - 浮動圖片     |
| sheet.command.insert-cell-image                       | 圖片 - 儲存格圖片    |
| sheet.command.numfmt.set.currency                     | 貨幣            |
| sheet.command.numfmt.add.decimal.command              | 增加小數位         |
| sheet.command.numfmt.subtract.decimal.command         | 減少小數位         |
| sheet.command.numfmt.set.percent                      | 百分比           |
| sheet.operation.open.numfmt.panel                     | 數字格式          |
| sheet.menu.data-validation                            | 資料驗證          |
| data-validation.operation.open-validation-panel       | 資料驗證 - 管理資料驗證 |
| data-validation.command.addRuleAndOpen                | 資料驗證 - 新建規則   |
| sheet.command.smart-toggle-filter                     | 篩選            |
| sheet.command.clear-filter-criteria                   | 篩選 - 清除篩選條件   |
| sheet.command.re-calc-filter                          | 篩選 - 重新計算     |
| sheet.operation.open-pivot-table-range-selector-panel | 樞紐分析表         |
| sheet.menu.print                                      | 列印            |
| sheet.operation.print-open                            | 列印 - 列印       |
| sheet.operation.open-print-grid-sidebar               | 列印 - 列印佈局     |
| data-connector.operation.sidebar                      | 資料連接器         |
| sheet.command.menu-insert-chart                       | 插入圖表          |
| sheet.command.add-range-protection-from-toolbar       | 保護            |
| univer.operation.toggle-edit-history                  | 歷史記錄          |
| sheet.operation.open-sparkline-selector               | 走勢圖           |
| sheet.operation.toggle-comment-panel                  | 評論管理          |
| sheet.operation.insert-hyper-link-toolbar             | 插入連結          |
| ui.operation.open-find-dialog                         | 尋找與取代         |
| base-ui.operation.toggle-shortcut-panel               | 打開收起快速鍵面板     |
| sheet.toolbar.text-to-number                          | 文字轉數字         |

### 右鍵菜單項

| 菜單項 ID                                                  | 菜單項名稱             |
| ------------------------------------------------------- | ----------------- |
| sheet.command.copy                                      | 複製                |
| sheet.command.cut                                       | 剪下                |
| sheet.command.paste                                     | 貼上                |
| sheet.menu.copy-special                                 | 選擇性複製             |
| sheet.command.copy-formula-only                         | 選擇性複製 - 僅複製公式     |
| sheet.menu.paste-special                                | 選擇性貼上             |
| sheet.command.paste-values                              | 選擇性貼上 - 僅貼上值      |
| sheet.command.paste-format                              | 選擇性貼上 - 僅貼上格式     |
| sheet.command.paste-col-width                           | 選擇性貼上 - 僅貼上欄寬     |
| sheet.command.paste-besides-border                      | 選擇性貼上 - 僅貼上邊框以外內容 |
| sheet.command.paste-formula                             | 選擇性貼上 - 僅貼上公式     |
| sheet.menu.clear-selection                              | 清除                |
| sheet.command.clear-selection-content                   | 清除 - 清除內容         |
| sheet.command.clear-selection-format                    | 清除 - 清除格式         |
| sheet.command.clear-selection-all                       | 清除 - 清除全部         |
| sheet.contextMenu.text-to-number                        | 文字轉數字             |
| sheet.menu.cell-insert                                  | 插入                |
| sheet.command.insert-row-before                         | 插入 - 在上方插入行       |
| sheet.command.insert-col-before                         | 插入 - 在左側插入列       |
| sheet.command.insert-range-move-right-confirm           | 插入 - 右移           |
| sheet.command.insert-range-move-down-confirm            | 插入 - 下移           |
| sheet.menu.delete                                       | 刪除                |
| sheet.command.remove-row-confirm                        | 刪除選中行             |
| sheet.command.remove-col-confirm                        | 刪除選中列             |
| sheet.command.delete-range-move-left-confirm            | 刪除 - 左移           |
| sheet.command.delete-range-move-up-confirm              | 刪除 - 上移           |
| sheet.menu.sheet-frozen                                 | 凍結                |
| sheet.header-menu.sheet-frozen                          | 凍結（行列標題右鍵菜單項）     |
| sheet.command.set-selection-frozen                      | 凍結 - 凍結           |
| sheet.command.set-row-frozen                            | 凍結 - 凍結行          |
| sheet.command.set-col-frozen                            | 凍結 - 凍結列          |
| sheet.command.cancel-frozen                             | 凍結 - 取消凍結         |
| sheet.contextMenu.permission                            | 保護行列              |
| sheet.command.add-range-protection-from-context-menu    | 保護行列 - 新增保護範圍     |
| sheet.command.set-range-protection-from-context-menu    | 保護行列 - 設置保護範圍     |
| sheet.command.delete-range-protection-from-context-menu | 保護行列 - 移除保護範圍     |
| sheet.command.view-sheet-permission-from-context-menu   | 保護行列 - 查看所有保護範圍   |
| sheet.menu.sheets-sort-ctx                              | 排序                |
| sheet.command.sort-range-asc-ctx                        | 排序 - 當前區域升冪       |
| sheet.command.sort-range-asc-ext-ctx                    | 排序 - 拓展區域升冪       |
| sheet.command.sort-range-desc-ctx                       | 排序 - 當前區域降冪       |
| sheet.command.sort-range-desc-ext-ctx                   | 排序 - 拓展區域降冪       |
| sheet.command.sort-range-custom-ctx                     | 排序 - 自訂排序         |
| sheet.operation.show-comment-modal                      | 添加評論              |
| sheet.operation.insert-hyper-link                       | 添加連結              |
| sheet.operation.screenshot                              | 複製為截圖             |

### 右鍵菜單項 - 行標題

| 菜單項 ID                                  | 菜單項名稱  |
| --------------------------------------- | ------ |
| sheet.command.insert-multi-rows-above   | 在上方插入行 |
| sheet.command.insert-multi-rows-after   | 在下方插入行 |
| sheet.command.hide-row-confirm          | 隱藏選中行  |
| sheet.command.set-selected-rows-visible | 顯示隱藏行  |
| sheet.command.set-row-height            | 列高     |
| sheet.command.set-row-is-auto-height    | 自動調整   |

### 右鍵菜單項 - 列標題

| 菜單項 ID                                  | 菜單項名稱  |
| --------------------------------------- | ------ |
| sheet.command.insert-multi-cols-before  | 在左側插入列 |
| sheet.command.insert-multi-cols-right   | 在右側插入列 |
| sheet.command.hide-col-confirm          | 隱藏選中列  |
| sheet.command.set-selected-cols-visible | 顯示隱藏列  |
| sheet.command.set-worksheet-col-width   | 欄寬     |
| sheet.command.set-col-auto-width        | 自動調整   |