# 列印

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

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

列印功能允許使用者將表格內容列印為紙質文件或匯出為 PDF 格式，便於離線檢視和分享。

> Interactive example: [Open the playground](/playground/sheets/print)

## 外掛模式

### 安裝

#### npm

```bash
npm install @univerjs-pro/sheets-print
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-print
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-print
```

#### bun

```bash
bun add @univerjs-pro/sheets-print
```

### 使用

```typescript
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print' // [!code ++]
import SheetsPrintPluginZhTW from '@univerjs-pro/sheets-print/locale/zh-TW' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import '@univerjs-pro/sheets-print/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      SheetsPrintPluginZhTW, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsPrintPlugin) // [!code ++]
```

如果你擁有 Univer 的商業許可證，請參考[在客戶端使用許可證](https://docs.univer.ai/zh-TW/server/license.md#in-plugin-mode)進行配置。

### 外掛與配置

```typescript
interface IUniverSheetsPrintConfig {
  /**
   * 是否強制列印時顯示水印
   * @default false
   */
  enforceWatermark?: boolean
}
```

## 行動裝置支援

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

| 套件                           | 桌面版註冊                     | 行動版註冊                             |
| ---------------------------- | ------------------------- | --------------------------------- |
| `@univerjs-pro/sheets-print` | `UniverSheetsPrintPlugin` | `UniverSheetsPrintMobileUIPlugin` |

## 預設模式

列印功能被包含在 `@univerjs/preset-sheets-advanced` 預設中。

### 安裝

> [!NOTE]
> @univerjs/preset-sheets-advanced 的 `UniverSheetsAdvancedPreset` 預設在執行時依賴 `UniverSheetsDrawingPreset`
> 預設，請先安裝 @univerjs/preset-sheets-drawing。

#### npm

```bash
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使用

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      UniverPresetSheetsCoreZhTW,
      UniverPresetSheetsDrawingZhTW, // [!code ++]
      UniverPresetSheetsAdvancedZhTW, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

如果你擁有 Univer 的商業許可證，請參考[在客戶端使用許可證](https://docs.univer.ai/zh-TW/server/license.md#in-preset-mode)進行配置。

### 預設與配置

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  print?: Partial<IUniverSheetsPrintConfig>
}

interface IUniverSheetsPrintConfig {
  /**
   * 是否強制列印時顯示水印
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Facade API

### 引入

```typescript
import '@univerjs-pro/sheets-print/facade'
```

### 開啟列印配置對話方塊

使用 `FWorkbook.openPrintDialog` 可以開啟列印配置對話方塊。

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

fWorkbook.openPrintDialog()
```

### 關閉列印配置對話方塊

使用 `FWorkbook.closePrintDialog` 方法可以關閉列印配置對話方塊。

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

// 3 秒後關閉列印配置對話方塊
setTimeout(() => {
  fWorkbook.closePrintDialog()
}, 3000)
```

### 更新列印佈局配置

使用 [`FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig)`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#updateprintconfig) 方法更新列印佈局配置。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const subUnitId = fWorksheet.getSheetId()

// 更新列印佈局配置
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet, // 列印當前工作表
  subUnitIds: [subUnitId],
  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 紙張大小
  scale: univerAPI.Enum.PrintScale.FitPage, // 使內容適應頁面
  freeze: [univerAPI.Enum.PrintFreeze.Row], // 凍結行標題
  margin: univerAPI.Enum.PrintPaperMargin.Normal, // 正常邊距
  // ... 其他設定
})

// 開始列印
fWorkbook.print()
```

完整設定型別與參數請參閱 [`FWorkbook.updatePrintConfig()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#updateprintconfig).

### 更新列印渲染配置

使用 [`FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig)`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#updateprintrenderconfig) 方法更新列印渲染配置。

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

// 更新預設列印佈局配置
fWorkbook.updatePrintConfig({})

// 更新列印渲染配置
fWorkbook.updatePrintRenderConfig({
gridlines: true, // 顯示網格線
hAlign: univerAPI.Enum.PrintAlign.Middle, // 水平居中對齊
vAlign: univerAPI.Enum.PrintAlign.Middle, // 垂直居中對齊
headerFooter: [ // 要包含的頁首和頁尾元素陣列，這裡是頁碼和工作表名稱
  univerAPI.Enum.PrintHeaderFooter.PageSize,
  univerAPI.Enum.PrintHeaderFooter.WorksheetTitle,
],
// ... 其他設定
})

// 開始列印
fWorkbook.print()
```

完整設定型別與參數請參閱 [`FWorkbook.updatePrintRenderConfig()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#updateprintrenderconfig).

### 調起列印

使用 `FWorkbook.print` 方法可以直接調起列印。

```typescript
// 使用預設配置可以傳入空物件
workbook.updatePrintConfig({
// ... 列印佈局配置
})
workbook.updatePrintRenderConfig({
// ... 列印渲染配置
})
workbook.print()
```

### 儲存截圖至剪貼簿

使用 `FWorkbook.saveScreenshotToClipboard` 方法可以儲存列印資料圖片到剪下板。

該 API 僅在擁有 [許可證](https://docs.univer.ai/zh-TW/server/license.md) 的情況下可用，未持有許可證時將受到使用限制，儲存操作將返回 `false`。

我們使用 Clipboard API 儲存圖片到剪貼簿，在非安全網路環境或某些不支援的瀏覽器可能會儲存失敗。儲存成功會返回 `true`。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const result = await fWorkbook.saveScreenshotToClipboard()
```

### 獲取選區截圖

使用 `FRange.getScreenshot` 方法可以獲取選區列印資料圖片。

該 API 僅在持有 [許可證](https://docs.univer.ai/zh-TW/server/license.md) 時可用，未持證使用者將受到使用限制，儲存失敗時返回 `false`，成功時返回圖片的 base64 字串。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D10')
fRange.getScreenshot()
fRange.getScreenshot({ includeHeaders: true }) // 包含行列標題
```

### 事件監聽

完整事件型別定義，請檢視 [Events](https://docs.univer.ai/zh-TW/reference/facade/events.md)。

`univerAPI.Event.BeforeSheetPrintOpen` 事件在開啟列印配置對話方塊之前觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => {
  const { workbook, worksheet } = params

  // 取消開啟列印配置對話方塊操作
  params.cancel = true
})

// 移除事件監聽器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintOpen` 事件在開啟列印配置對話方塊之後觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => {
  const { workbook, worksheet } = params
})

// 移除事件監聽器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetPrintConfirm` 事件在確認列印之前觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => {
  const { renderConfig, layoutConfig } = params

  // 取消列印確認操作
  params.cancel = true
})

// 移除事件監聽器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintConfirmed` 事件在確認列印之後觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => {
  const { renderConfig, layoutConfig } = params
})

// 移除事件監聽器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetPrintCanceled` 事件在取消列印之前觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params

  // 取消列印取消操作
  params.cancel = true
})

// 移除事件監聽器，使用 `disposable.dispose()`
```

`univerAPI.Event.SheetPrintCanceled` 事件在取消列印之後觸發。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params
})

// 移除事件監聽器，使用 `disposable.dispose()`
```