# 核心功能

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

```json
{
  "preset": [],
  "plugins": [
    {
      "client": "@univerjs-pro/pdfs",
      "facade": "@univerjs-pro/pdfs/facade"
    },
    {
      "client": "@univerjs-pro/pdfs-ui",
      "locale": "@univerjs-pro/pdfs-ui/locale/zh-TW",
      "style": "@univerjs-pro/pdfs-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Univer PDFs 核心功能包括正式的 PDF Unit、持久化編輯層和瀏覽器工作台。匯入的 PDF 內容會保留為來源基準，已接受的修改則儲存在 Unit 快照中，並算繪為目前文件。

## 功能

* **PDF Unit 模型**：在 `IPdfUnitData` 中儲存來源文件、頁面結構、資源和持久化編輯意圖。
* **頁面與元素操作**：支援頁面導覽和插入，以及可編輯的文字、清單、表格、影像、分隔線和註解。
* **瀏覽器工作台**：提供 PDF 頁面算繪、縮圖、選取、編輯控制項、剪貼簿行為和檢查器介面。
* **命令管線**：透過持久化命令和變更批次套用已接受的修改，使儲存、復原和重做共用同一模型。
* **Facade API**：透過 PDF、頁面、元素和原生文字物件建立、尋找、編輯和儲存 PDF Unit。

## 外掛程式模式

### 安裝

#### npm

```bash
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### pnpm

```bash
pnpm add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```bash
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### bun

```bash
bun add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

### 使用

```ts
import { UniverLicensePlugin } from '@univerjs-pro/license'
import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'
import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'
import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
import DesignEnUS from '@univerjs/design/locale/en-US'
import { UniverUIPlugin } from '@univerjs/ui'
import UIEnUS from '@univerjs/ui/locale/en-US'
import '@univerjs-pro/pdfs/facade'
import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs-pro/pdfs-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(DesignEnUS, UIEnUS, PdfsUIEnUS),
  },
})

univer.registerPlugin(UniverUIPlugin, { container: 'app' })
univer.registerPlugin(UniverLicensePlugin, {
  license: process.env.CLIENT_LICENSE_TEXT,
})
univer.registerPlugin(UniverPdfsPlugin)
univer.registerPlugin(UniverPdfsUIPlugin)

const univerAPI = FUniver.newAPI(univer)
const pdf = univerAPI.createPdf({ name: 'Untitled PDF' })
```

`UniverPdfsPlugin` 負責 PDF Unit 和持久化命令，`UniverPdfsUIPlugin` 負責瀏覽器檢視器及其編輯控制項。僅需檢視介面時，請用 `{ editor: { enabled: false } }` 註冊 `UniverPdfsUIPlugin`。採用協作的應用程式可以另外安裝 `@univerjs-pro/pdfs-editor`，並同時註冊它所依賴的協作外掛程式。

## 預設模式

Univer PDFs 目前沒有提供預設套件。請使用外掛程式模式建立 PDF 應用程式。

## 編輯與檢視控制

開始工具列提供複製、剪下、貼上、工具模式和註解工具。插入工具列提供頁面、文字方塊、段落、清單、表格、圖片和分隔線。檢視工具列提供縮放、全螢幕、註解顯示與隱藏及連續捲動。選取文字或表格後會顯示對應的情境控制項，包括屬性面板與表格樣式。這些工具列控制項需要保留 `UniverPdfsUIPlugin` 預設的 `editor.enabled: true`。

## 選單順序與網格佈局

在既有的 `UniverUIPlugin` 註冊設定中設定 `menu` 和 `ribbonType`。它們屬於共用 UI 設定，不應傳給 `UniverPdfsUIPlugin`。以下使用 PDFs 的實際選單項目 ID：

### 初始化設定

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

const menu: MenuConfig = {
  'ribbon.view': { order: -1 },
  'ribbon.start.layout': { order: -1 },
  'pdf.menu.tool.highlight': {
    order: 1,
    gridLayout: { row: 2, column: 1 },
  },
  'pdf.menu.tool.ink': {
    order: 0,
    gridLayout: { row: 1, column: 1 },
  },
}

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

`order` 依數值由小到大排列同層級頁籤、群組或選單項目，不會將項目移到其他群組。選單項目 ID 可從其 `data-u-command` 屬性取得，不應直接假設它與命令 ID 相同。

### 執行階段更新

先匯入 `@univerjs/ui/facade`，再透過 `FUniver.newAPI(univer)` 建立 `univerAPI`。[`updateMenuConfig()`](https://docs.univer.ai/zh-TW/reference/facade/univer.md#updatemenuconfig) 會合併修改、保留未指定的欄位並重新整理選單，設定也會套用到之後註冊的選單。

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

univerAPI.updateMenuConfig({
  'pdf.menu.tool.highlight': { gridLayout: { row: 2, column: 1, showLabel: true, width: 96 } },
})
```

`gridLayout` 僅控制網格 Ribbon。每個群組固定兩列，`row` 和 `column` 從 1 開始。明確座標優先決定位置，因此交換已佔用的儲存格時應同時修改兩個選單項目，不能只調整 `order`。未指定的選用欄位沿用既有設定或 Schema。跨列、跨欄、標籤、寬度和圖示尺寸請見 [`IRibbonGridLayout`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/ui.md#iribbongridlayout)。

請保持 `UniverPdfsUIPlugin` 的編輯功能開啟：`editor.enabled: false` 會略過該產品 Ribbon 的註冊。選單覆寫設定不會建立尚未註冊的按鈕。

自訂按鈕和子選單入口也能透過 [`createMenu()`、`createSubmenu()`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs/ui.md#ifacademenuitem) 設定 `order` 與 `gridLayout`，再呼叫 `appendTo()` 註冊。彈出選單內部不使用 Ribbon 的網格佈局。