# 核心功能

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-docs-core",
      "locale": "@univerjs/preset-docs-core/locales/zh-TW",
      "style": "@univerjs/preset-docs-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/docs"
    },
    {
      "client": "@univerjs/docs-ui",
      "locale": "@univerjs/docs-ui/locale/zh-TW",
      "style": "@univerjs/docs-ui/lib/index.css",
      "facade": "@univerjs/docs-ui/facade"
    }
  ],
  "server": false
}
```

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

## 特性

Univer Docs 的核心功能包括：

* **文件渲染**：支援 Univer Docs 的渲染和游標、選區的繪製。
* **文件排版**：支援全文排版，包括段落設置，段前後間距、段落對齊、縮進和懸掛等，也包括段落中的排版能力，標點擠壓、標點懸掛、字偶間距、西文斷詞等。
* **公式計算**：支援 Univer 公式的添加和計算（開發中）。
* **表格能力**：支援插入基本表格和表格的編輯，新增、刪除行類操作，編輯儲存格等。
* **文件風格**：Univer Docs 不僅支援類似 Microsoft Word 的*傳統文件風格*（包含分頁、頁眉頁腳等），也支援類似 Notion 的*現代文件風格*。在現代文件風格中，無需分頁，內容可以無限擴充，支援多種官方或第三方塊級元素（如文本、圖片、表格等）的混合排版（計劃中）。
* **頁眉頁腳**：支援插入頁眉頁腳和編輯頁眉頁腳內容，可以區分首頁及奇偶頁等，僅傳統文件支援。
* **列表功能**：支援有序、無序列表和任務列表的插入和編輯，支援列表的縮進和反縮進等。
* **表情與符號**：可從 Docs 功能區插入表情和符號。
* **外掛系統**：支援外掛系統，可以自訂外掛，如公式外掛、圖片外掛、圖表外掛等，這也是 Univer 核心架構能力之一。

## 外掛模式

### 安裝

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

### 使用

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
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 { UniverUIPlugin } from '@univerjs/ui'
import UIZhTW from '@univerjs/ui/locale/zh-TW'
import '@univerjs/docs/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs/docs-ui/lib/index.css'

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

univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
})
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverDocsUIPlugin)

const univerAPI = FUniver.newAPI(univer)

univerAPI.createDocument({})
```

### 外掛與配置

#### @univerjs/core

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

```typescript
import type { IUniverConfig } from '@univerjs/core'
import { LocaleType, Univer } from '@univerjs/core'

const config: IUniverConfig = {
  locale: LocaleType.ZH_TW,
  darkMode: false,
}
const univer = new Univer(config)
```

參考：[`IUniverConfig`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/core.md#iuniverconfig)

#### @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(UniverDocsUIPlugin, {
  menu: {
    'doc.command.set-inline-format-bold': {
      hidden: true,
    },
    'doc.command.set-inline-format-italic': {
      hidden: true,
      disabled: true,
    },
  },
})
```

這裡的 `'doc.command.set-inline-format-bold'` 和 `'doc.command.set-inline-format-italic'` 是命令的名稱，表示對應的菜單項。

參考：[@univerjs/docs-ui](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/docs-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)

## 預設模式

### 安裝

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

### 使用

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

const { univer, univerAPI } = createUniver({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(UniverPresetDocsCoreZhTW),
  },
  presets: [UniverDocsCorePreset()],
})

univerAPI.createDocument({})
```

### 預設與配置

#### @univerjs/presets

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

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

```typescript
interface ICreateUniverParameter {
  // 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-docs-core

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

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

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

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

```typescript
UniverDocsCorePreset({
  menu: {
    'doc.command.set-inline-format-bold': {
      hidden: true,
    },
    'doc.command.set-inline-format-italic': {
      hidden: true,
      disabled: true,
    },
  },
})
```

這裡的 `'doc.command.set-inline-format-bold'` 和 `'doc.command.set-inline-format-italic'` 是命令的名稱，表示對應的菜單項。

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

## 檢視控制

檢視工具列包含頁面設定、縮放和全螢幕入口。縮放選擇器與底部縮放列顯示相同的文件檢視比例；調整比例不會修改文字格式。

## 選單順序與網格佈局

先使用 Docs 選單 ID 定義共用的 [`MenuConfig`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/ui.md#menuconfig)，再依接入模式套用設定：

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

const menu: MenuConfig = {
  'ribbon.start.format': { order: -1 },
  'doc.command.set-inline-format-bold': {
    order: 0,
    gridLayout: { row: 2, column: 2 },
  },
  'doc.command.set-inline-format-italic': {
    gridLayout: { row: 2, column: 1 },
  },
}
```

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

#### 外掛模式

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

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

#### 預設模式

```typescript
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import { createUniver } from '@univerjs/presets'

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

初始化後，使用 [`updateMenuConfig()`](https://docs.univer.ai/zh-TW/reference/facade/univer.md#updatemenuconfig) 更新既有實例：

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

univerAPI.updateMenuConfig(menu)
```

`order` 依數值由小到大排列同層節點；`gridLayout` 僅用於網格 Ribbon，座標在各自的兩列群組內從 1 開始。執行時更新會保留未指定的屬性並立即更新 UI。外掛模式下，將 `menu` 傳給 `UniverUIPlugin`，並先匯入 `@univerjs/ui/facade` 再呼叫 Facade。網格欄位與自訂按鈕範例請見[選單佈局指南](https://docs.univer.ai/zh-TW/guides/sheets/features/core.md#menu-order-and-grid-layout)。

## 貼上選項

Docs 支援保留來源格式、符合目的地格式及僅保留文字。符合目的地格式會採用目標文字與段落樣式，並保留粗體、斜體等支援的強調格式。僅保留文字會移除圖片與超連結，表格轉為定位字元分隔文字。貼上後可切換最近一次貼上的方式；瀏覽器禁止讀取剪貼簿時，請使用快捷鍵或系統貼上。

桌面版 Ribbon 的**貼上**下拉選單位於復原、重做旁，編輯圖形文字時會隱藏。桌面版和行動版快顯選單中的**選擇性貼上**均位於格式群組。

## 頁首與頁尾欄位

在傳統文件中編輯頁首或頁尾時，會出現用於插入、導覽、首頁／奇偶頁選項及位置設定的情境式 Ribbon。可插入目前頁碼、總頁數及本地化日期與時間。頁碼欄位依各個呈現頁面顯示對應值。插入日期／時間時，勾選自動更新會儲存為欄位，取消勾選則插入固定文字。日期／時間欄位會在開啟文件或執行「更新欄位」時重新整理，不會像時鐘持續更新。現代文件不使用分頁頁首與頁尾。

## 文件大綱

左側大綱用於跳轉至標題，不會在內文中插入目錄。省略 `toc` 時，現代文件預設開啟，傳統文件預設關閉；明確設定 `true` 或 `false` 可覆寫預設值。空間不足或表格與大綱重疊時，面板會收起，空間恢復後重新展開。

將此選項合併到現有初始化設定中，請勿重複註冊同一外掛。

#### 外掛模式

```ts
import { UniverDocsUIPlugin } from '@univerjs/docs-ui'

univer.registerPlugin(UniverDocsUIPlugin, { toc: true })
```

#### 預設模式

```ts
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import { createUniver } from '@univerjs/presets'

const { univerAPI } = createUniver({
  presets: [UniverDocsCorePreset({ container: 'app', toc: true })],
})
```

## 標題摺疊

現代文件（`documentStyle.documentFlavor: DocumentFlavor.MODERN`）會在具有章節內容的一級至五級標題旁顯示三角按鈕。摺疊後保留標題，隱藏其後直到下一個同層級或更高層級標題之前的內容，包括子標題、表格和圖片。每個表格儲存格和現代文件分欄都有獨立的標題階層。

標題摺疊不受 `toc` 控制。傳統文件和嵌入式文字編輯器不顯示摺疊控制項。展開父標題時，子標題會保留各自的摺疊狀態。



`IParagraph.headingCollapsed` 隨 Univer 快照儲存，僅 `true` 表示摺疊。內文仍在快照中，摺疊支援復原、重做及協同，並與其他編輯者共用。隱藏內容中的選取範圍會移到可見標題。此約定不保證 Office 匯入匯出保留摺疊狀態。

以程式碼修改時，使用文件 ID 和快照中穩定的 `paragraphId` 執行已註冊的命令。設定 `collapsed: false` 可展開。

```ts
import { SetHeadingCollapsedCommand } from '@univerjs/docs'

const changed = await univerAPI.executeCommand(SetHeadingCollapsedCommand.id, {
  unitId: documentId,
  paragraphId: headingParagraphId,
  collapsed: true,
})
```

狀態未變或目標無效時，命令傳回 `false`，例如傳統文件、被祖先標題隱藏的標題、摺疊空章節或無編輯權限。詳見[命令契約](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/docs.md#heading-collapse)。