---
title: "缩放"
description: "学习如何在 Tiptap Pages 编辑器中放大和缩小内容，使内容变大或变小，就像在 Google Docs 或 Microsoft Word 中一样。"
canonical_url: "https://tiptap.zhcndoc.com/pages/core-concepts/zoom"
---

# 缩放

学习如何在 Tiptap Pages 编辑器中放大和缩小内容，使内容变大或变小，就像在 Google Docs 或 Microsoft Word 中一样。

Zoom 让你的用户可以在不改变实际文档的情况下**放大**或**缩小**编辑器内容。这就像在手机上捏合缩放，或者在 Google Docs 中使用缩放滑块一样。

- **放大** 以近距离查看细节（非常适合精确格式调整）
- **缩小** 以一次查看更多文档内容（非常适合整体浏览）
- 文档本身不会改变；缩放纯粹是视觉效果

> **Interactive demo:** [PagesZoom](https://embed-pro.tiptap.dev/preview/Extensions/PagesZoom)

## 快速开始

在配置扩展时设置初始缩放级别：

```js
import { Pages } from '@tiptap-pro/extension-pages'

Pages.configure({
  zoom: 0.75, // 75%，使所有内容更小
})
```

随时通过命令更改缩放级别：

```js
// 放大到 150%
editor.commands.setZoom(1.5)

// 缩小到 50%
editor.commands.setZoom(0.5)

// 回到正常（100%）
editor.commands.setZoom(1)
```

仅此而已。两行代码，你就拥有缩放功能。

## 缩放范围

缩放接受 **0.25**（25%）到 **4**（400%）之间的任意值。超出此范围的值会自动被限制。

| 值      | 缩放级别 | 使用场景             |
| ------ | ---- | ---------------- |
| `0.25` | 25%  | 最大缩小：查看整个文档布局    |
| `0.5`  | 50%  | 概览模式，适合长文档       |
| `0.75` | 75%  | 稍小一些，可在屏幕上显示更多内容 |
| `1`    | 100% | 默认，正常大小          |
| `1.25` | 125% | 稍大一些，更易阅读        |
| `1.5`  | 150% | 舒适的阅读缩放          |
| `2`    | 200% | 较大，适合无障碍阅读       |
| `4`    | 400% | 最大放大：像素级细节       |

```js
// 这些都有效
editor.commands.setZoom(0.25)  // 最小值
editor.commands.setZoom(1.5)   // 150%
editor.commands.setZoom(4)     // 最大值

// 这些会自动被限制
editor.commands.setZoom(0.1)   // 变为 0.25
editor.commands.setZoom(10)    // 变为 4
```

## 读取当前缩放级别

你可以随时从存储中读取当前缩放级别：

```js
// 直接读取当前缩放级别
const zoom = editor.storage.pages.zoom
console.log(`当前缩放: ${zoom * 100}%`) // 例如 "当前缩放: 125%"

// 或者使用 getter 函数
const zoom = editor.storage.pages.getZoom?.()
```

## 响应缩放变化

使用 `onZoomChange` 回调函数，以便在缩放级别变化时保持界面同步。这对于构建缩放控件（如下拉菜单或滑块）非常有用。

```js
Pages.configure({
  zoom: 1,
  onZoomChange: (zoom) => {
    // 更新你的 UI，例如下拉菜单或标签
    console.log(`缩放已更改为 ${zoom * 100}%`)
  },
})
```

### 带有缩放下拉菜单的 React 示例

```jsx
import { Pages } from '@tiptap-pro/extension-pages'
import { useState } from 'react'

function MyEditor() {
  const [zoom, setZoom] = useState(1)

  const editor = useEditor({
    extensions: [
      Pages.configure({
        pageFormat: 'A4',
        onZoomChange: setZoom, // 保持下拉菜单同步
      }),
    ],
  })

  return (
    <>
      <select
        value={zoom}
        onChange={(e) => {
          const value = parseFloat(e.target.value)
          editor.commands.setZoom(value)
        }}
      >
        <option value={0.5}>50%</option>
        <option value={0.75}>75%</option>
        <option value={1}>100%</option>
        <option value={1.25}>125%</option>
        <option value={1.5}>150%</option>
        <option value={2}>200%</option>
      </select>
      <EditorContent editor={editor} />
    </>
  )
}
```

## 配置参考

### 选项

| 选项             | 类型                       | 默认值         | 描述                          |
| -------------- | ------------------------ | ----------- | --------------------------- |
| `zoom`         | `number`                 | `1`         | 初始缩放级别。限制在 `[0.25, 4]` 范围内。 |
| `onZoomChange` | `(zoom: number) => void` | `undefined` | 通过 `setZoom` 更改缩放时触发的回调函数。  |

### 命令

| 命令        | 参数             | 描述                            |
| --------- | -------------- | ----------------------------- |
| `setZoom` | `zoom: number` | 设置缩放级别。值会限制在 `[0.25, 4]` 范围内。 |

### 存储

| 属性        | 类型             | 描述        |
| --------- | -------------- | --------- |
| `zoom`    | `number`       | 当前缩放级别。   |
| `getZoom` | `() => number` | 返回当前缩放级别。 |

## 注意事项

- **缩放仅影响视觉显示。** 它不会改变文档结构、内容或格式。导出为 DOCX 或打印时，输出始终为 100%。
- **页眉和页脚会随缩放变化。** 它们会与页面其余部分一起缩放。如果你打开页眉或页脚编辑器，覆盖层会匹配当前缩放级别，即使你在编辑时更改缩放也一样。
- **分页保持准确。** 页面分隔、页数以及所有分页计算在任何缩放级别下都保持正确。缩放不会增加或删除页面。