---
title: "白板实用程序"
description: "Tiptap Whiteboard 扩展的实用函数和常量，用于舞台和相机、内容、状态、形状、事务、白板文件和图像。"
canonical_url: "https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/utilities"
---

# 白板实用程序

Tiptap Whiteboard 扩展的实用函数和常量，用于舞台和相机、内容、状态、形状、事务、白板文件和图像。

从 `@tiptap-pro/extension-whiteboard` 导入这些函数和常量。

- 白板上的位置和尺寸以板为单位，舞台上的位置以屏幕像素为单位。
- `insertShapesInFront`、`removeShapes`、`restackShapes` 和 `keepShapeHeights` 适用于构建自己的交易的代码，例如 AI 工具。

`Attribute`、`Attributes`、`Editor`、`JSONContent`、`NodeViewRenderer` 和 `NodeWithPos` 来自 `@tiptap/core`。 `Node` 来自 `@tiptap/pm/model`，`EditorState` 和 `Transaction` 来自 `@tiptap/pm/state`，`EditorView` 来自 `@tiptap/pm/view`。

## `attachStage`

允许用户在 `stage` 中使用 `editor` 的板：平移和缩放、缩放快捷键、使用形状工具和选择框进行绘图。按住 Space、中间按钮或手动工具的平移胜过绘图和选择。在触摸屏上，当选择工具处于活动状态时，一根手指在空白板上进行平移，两根手指进行平移和缩放。使用白板的[`images`](https://tiptap.zhcndoc.com/editor/whiteboard/guides/images.md)，用户放置的图像文件会落在放置的位置，并将图像文件粘贴到舞台中央。

```js
import { attachStage } from '@tiptap-pro/extension-whiteboard'

const detach = attachStage({ stage, editor, updateCamera: setCamera })
```

### 参数 (`StageOptions`)

- `stage` (`HTMLElement`)：白板周围的元素，获取其指针和滚轮事件。
- `editor` (`Editor`)：白板的​​编辑器。
- `updateCamera` (`UpdateCamera`)：当用户平移、缩放或使用缩放快捷方式时移动摄像机。
- `fitInsets?` (`() => number | Insets`)：返回 Shift + 1 适合视图的形状周围保持自由的空间，例如白板下方。默认值：每个边缘 64 个屏幕像素。

### 返回 (`() => void`)

再次分离所有内容的函数。

该阶段需要 `position: relative`、`overflow: clip` 和 `touch-action: none`。视口是容纳编辑器的元素，位于其左上角，包含 `position: absolute`、`top: 0`、`left: 0` 和 `transform-origin: 0 0`。用[`toCssTransform(camera)`](#tocsstransform)移动它，并将其上的`--zoom`设置为变焦。

## `toCssTransform`

返回显示带有摄像头的白板的 CSS 转换。变换移动的视口需要 `transform-origin: 0 0`。

```js
import { toCssTransform } from '@tiptap-pro/extension-whiteboard'

toCssTransform({ x: 100, y: 50, zoom: 2 }) // 'translate(100px, 50px) scale(2)'
```

### 参数

- `camera` (`Camera`)：白板的摄像头。

### 返回 (`string`)

视口 `transform` 的值。

## `zoomAtStageCenter`

更改舞台中间周围的缩放，使板保持在那里。

```js
import { zoomAtStageCenter } from '@tiptap-pro/extension-whiteboard'

resetZoomButton.addEventListener('click', () => {
  zoomAtStageCenter({ stage, updateCamera: setCamera, nextZoom: () => 1 })
})
```

### 参数 (`ZoomAtStageCenterOptions`)

- `stage` (`HTMLElement`)：白板周围的元件。
- `updateCamera` (`UpdateCamera`)：移动摄像机。
- `nextZoom` (`(zoom: number) => number`)：返回当前缩放的新缩放。

## `stepZoom`

返回某个方向的下一个缩放步骤，例如应用程序的缩放按钮。步骤之间的缩放将转到该方向的下一步。步长从 10% 到 400%。

```js
import { stepZoom } from '@tiptap-pro/extension-whiteboard'

stepZoom({ zoom: 1, direction: 1 }) // 1.25
stepZoom({ zoom: 0.8, direction: -1 }) // 0.75
```

### 参数 (`StepZoomOptions`)

- `zoom` (`number`)：现在的缩放，其中 1 表示 100%。
- `direction` (`1 | -1`)：`1` 放大，`-1` 缩小。

### 返回 (`number`)

下一个缩放。

## `zoomToFitShapes`

移动并缩放相机，使每个形状都位于舞台中。它永远不会放大超过 100%，或缩小超过 [`minZoom`](#minzoom)，并且在空白板上不执行任何操作。

```js
import { zoomToFitShapes } from '@tiptap-pro/extension-whiteboard'

zoomToFitShapes({ stage, editor, updateCamera: setCamera })
```

### 参数 (`ZoomToFitShapesOptions`)

- `stage` (`HTMLElement`)：白板周围的元件。
- `editor` (`Editor`)：白板的​​编辑器。
- `updateCamera` (`UpdateCamera`)：移动摄像机。
- `insets?` (`number | Insets`)：边缘处保持自由的空间，以屏幕像素为单位，每个边缘相同或每个边缘一个，就像将形状排除在浮动控件下一样。默认值：`64`。

## `scrollShapesIntoView`

尽可能少地移动相机，以便具有给定 id 的形状位于舞台中。仅当它们不适合时它才会缩小，并且当它们都不在白板上时它不执行任何操作。

```js
import { scrollShapesIntoView } from '@tiptap-pro/extension-whiteboard'

scrollShapesIntoView({ stage, editor, ids: ['note-1'], updateCamera: setCamera })
```

### 参数 (`ScrollShapesIntoViewOptions`)

- `stage` (`HTMLElement`)：白板周围的元件。
- `editor` (`Editor`)：白板的​​编辑器。
- `ids` (`readonly string[]`)：要显示的形状的 ID。
- `updateCamera` (`UpdateCamera`)：移动摄像机。
- `insets?` (`number | Insets`)：边缘处保持空闲的空间，以屏幕像素为单位，每个边缘相同或每个边缘一个。默认值：`64`。

## `fitCameraToRect`

返回一个相机位置，使矩形区域显示在舞台中央并与 `insets` 保持间距。函数会缩小视图以容纳该区域，但缩放不会超过 `largestZoom`，并且会限制在 [`minZoom`](#minzoom) 和 [`maxZoom`](#maxzoom) 范围内。因此，如果该区域需要低于 `minZoom` 的缩放比例才能完整显示，就无法完全适配。

```js
import { fitCameraToRect } from '@tiptap-pro/extension-whiteboard'

const rect = { x: 0, y: 0, width: 1200, height: 800 }
const camera = fitCameraToRect({ rect, viewport: { width: 1000, height: 800 } })
```

### 参数 (`FitCameraToRectOptions`)

- `rect` (`Rect`)：要显示的白板部分，以白板为单位。
- `viewport` (`Size`)：舞台的大小（以屏幕像素为单位）。
- `insets?` (`number | Insets`)：边缘处保持空闲的空间，以屏幕像素为单位，每个边缘相同或每个边缘一个。默认值：`64`。
- `largestZoom?` (`number`)：可以放大的距离。默认值：`1`，即 100%。

### 返回 (`Camera`)

显示零件的摄像机。

## `visibleBoardRect`

返回舞台显示的白板部分。

```js
import { visibleBoardRect } from '@tiptap-pro/extension-whiteboard'

const seen = visibleBoardRect({ camera, viewport: { width: 1000, height: 800 } })
```

### 参数（`VisibleBoardRectOptions`）

- `camera`（`Camera`）：白板的摄像头。
- `viewport` (`Size`)：舞台的大小（以屏幕像素为单位）。

### 返回 (`Rect`)

白板的部分（以板为单位）。

## `clientToBoard`

使用白板显示的相机将窗口坐标中的点转换为白板单位。

```js
import { clientToBoard } from '@tiptap-pro/extension-whiteboard'

stage.addEventListener('pointermove', (event) => {
  const point = clientToBoard({ editor, point: { x: event.clientX, y: event.clientY } })

  if (point) {
    console.log(`The pointer is at ${point.x}, ${point.y} on the board`)
  }
})
```

### 参数 (`ClientToBoardOptions`)

- `editor` (`Editor`)：白板的​​编辑器。
- `point` (`Point`)：窗口坐标中的点，如指针事件的 `clientX` 和 `clientY`。

### 返回 (`Point | null`)

白板单位中的点，或当白板不在页面上时的 `null`，就像在安装 `useEditor` 的编辑器之前或在编辑器被销毁后一样。

## `minZoom`

最小缩放，10%。相机助手永远不会进一步缩小。

值：`0.1`。

## `maxZoom`

最大缩放，400%。相机助手永远不会进一步放大。

值：`4`。

## `boardContent`

针对编辑器的内容，使用给定形状构建板文档的 JSON。

```js
import { boardContent, stickyNoteContent } from '@tiptap-pro/extension-whiteboard'

editor.commands.setContent(boardContent([stickyNoteContent({ id: 'note', x: 0, y: 0 })]))
```

### 参数

- `shapes` (`JSONContent[]`)：形状的 JSON，如 [`stickyNoteContent()`](#stickynotecontent)。

### 返回 (`JSONContent`)

文档的 JSON。

## `stickyNoteContent`

使用一段文本构建便笺的 JSON，用于显示白板的内容。它采用[`textShapeContent()`](#textshapecontent) 选项，不带`type` 和`kind`。

```js
import { stickyNoteContent } from '@tiptap-pro/extension-whiteboard'

const note = stickyNoteContent({ id: 'note', x: 0, y: 0, text: 'Hello' })
```

### 参数 (`StickyNoteContentOptions`)

- `id` (`string`)：票据的 id，在白板上唯一。
- `x`、`y` (`number`)：注释所在位置（以板为单位）。
- `width?`、`height?` (`number`)：纸币的大小，以纸币为单位。默认值：[`stickyNoteSize`](#stickynotesize)。
- `zIndex?` (`string`)：堆叠顺序，作为分数索引。较高的形状在前面。
- `color?` (`ShapeColor`)：票据的颜色，如 `blue`。请参阅[`shapeColors`](#shapecolors)。
- `fontSize?` (`ShapeStyleValue<'fontSize'>`)：文本的大小，如 `s`、`m`、`l` 或 `xl`。
- `textAlign?` (`ShapeStyleValue<'textAlign'>`)：文本如何对齐：`start`、`center` 或 `end`。
- `font?` (`ShapeStyleValue<'font'>`)：文本的字体，如 `sans`、`serif` 或 `mono`。
- `text?` (`string`)：注释文本，在一个段落中。

### 返回 (`JSONContent`)

注释的 JSON。

## `textShapeContent`

为白板的内容构建带有文本的形状的 JSON。

```js
import { boardContent, textShapeContent } from '@tiptap-pro/extension-whiteboard'

const shape = textShapeContent({ type: 'geo', id: 'box', x: 0, y: 0, text: 'Hi' })

editor.commands.setContent(boardContent([shape]))
```

### 参数 (`TextShapeContentOptions`)

- `type` (`string`)：形状的节点类型，如 `stickyNote`、`geo` 或 `freeText`。
- `id` (`string`)：形状的id，在白板上唯一。
- `x`、`y` (`number`)：形状所在的位置（以板为单位）。
- `width?`、`height?` (`number`)：形状的大小，以板为单位。
- `zIndex?` (`string`)：堆叠顺序，作为小数索引。较高的形状在前面。
- `color?` (`ShapeColor`)：形状的颜色，如 `blue`。请参阅[`shapeColors`](#shapecolors)。
- `fontSize?` (`ShapeStyleValue<'fontSize'>`)：文本的大小，如 `s`、`m`、`l` 或 `xl`。
- `textAlign?` (`ShapeStyleValue<'textAlign'>`)：文本如何对齐：`start`、`center` 或 `end`。
- `font?` (`ShapeStyleValue<'font'>`)：文本的字体，如 `sans`、`serif` 或 `mono`。
- `kind?`（`GeoKind`）：几何形状的一种，名称来自[`geoKinds`](#geokinds)。
- `text?` (`string`)：形状的文本，在一个段落中。

### 返回 (`JSONContent`)

形状的 JSON。

## `freehandFromPoints`

将以板为单位绘制的线条转换为笔线的几何形状。该框为笔划宽度留出了空间，并且点是相对于其角的。

```js
import { freehandFromPoints } from '@tiptap-pro/extension-whiteboard'

const line = freehandFromPoints({
  points: [
    { x: 0, y: 0 },
    { x: 100, y: 40 },
  ],
  strokeWidth: 3,
})
const content = { type: 'freehand', attrs: { id: 'line', ...line, strokeWidth: 3 } }
```

### 参数 (`FreehandFromPointsOptions`)

- `points` (`readonly Point[]`)：线路的点，以板为单位。它至少需要一个。
- `strokeWidth` (`number`)：线的宽度，以板为单位。

### 返回 (`FreehandShape`)

笔线的框和点。

## `createShapeId`

返回新的随机版本 4 UUID，作为形状的 id。也可以在没有 `crypto.randomUUID` 的安全来源下工作。

```js
import { createShapeId, stickyNoteContent } from '@tiptap-pro/extension-whiteboard'

const note = stickyNoteContent({ id: createShapeId(), x: 0, y: 0 })
```

### 参数

无。

### 返回 (`string`)

新 ID。

## `getSelectedShapeIds`

返回所选形状的 ID。

```js
import { getSelectedShapeIds } from '@tiptap-pro/extension-whiteboard'

editor.commands.bringToFront(getSelectedShapeIds(editor.state))
```

### 参数

- `state` (`EditorState`)：白板编辑器的状态，如 `editor.state`。

### 返回 (`readonly string[]`)

id，按照选择形状的顺序排列。

## `isBoardEditable`

用于判断用户是否可以编辑白板。调用 `editor.setEditable(false)` 会关闭白板编辑。请使用它代替 `editor.isEditable`，因为白板获得键盘焦点时 `editor.isEditable` 会返回 `false`。参见[自定义形状](https://tiptap.zhcndoc.com/editor/whiteboard/guides/custom-shapes.md#read-only-boards)。

```js
import { isBoardEditable } from '@tiptap-pro/extension-whiteboard'

// Commands also change a read-only board, so check before a button in your shape runs one
if (isBoardEditable(editor)) {
  editor.commands.updateShape({ id, attributes: { votes: votes + 1 } })
}
```

### 参数

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`boolean`)

用户是否可以更换板卡。

## `isEditingText`

告知形状的文本是否已编辑，以便在其中键入按键。否则，按键将作用于白板和选定的形状。编辑文档框架的文档时，它是`false`，请参见[`getEditedDocEditor()`](#getediteddoceditor)。

```js
import { isEditingText } from '@tiptap-pro/extension-whiteboard'

isEditingText(editor.state) // false while keys act on the board
```

### 参数

- `state` (`EditorState`)：白板编辑器的状态，如 `editor.state`。

### 返回 (`boolean`)

形状的文本是否已编辑。

## `getEditedShapeId`

返回已编辑文本的形状的 ID。对于文档框架的文档，请参阅[`getEditedDocEditor()`](#getediteddoceditor)。

```js
import { getEditedShapeId } from '@tiptap-pro/extension-whiteboard'

getEditedShapeId(editor.state) // 'note' while its text is edited
```

### 参数

- `state` (`EditorState`)：白板编辑器的状态，如 `editor.state`。

### 返回 (`string | null`)

按键作用于白板或编辑文档框架的文档时的 id 或 `null`。

## `getActiveTool`

返回白板上压力机使用的工具。

```js
import { getActiveTool } from '@tiptap-pro/extension-whiteboard'

getActiveTool(editor.state) // 'select'
```

### 参数

- `state` (`EditorState`)：白板编辑器的状态，如 `editor.state`。

### 返回 (`Tool`)

工具 `select`，除非 [`setTool`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/commands.md#settool) 选择另一工具。

## `getNextShapeStyles`

返回新形状的样式。未设置的样式保留每种形状的默认样式。

```js
import { getNextShapeStyles } from '@tiptap-pro/extension-whiteboard'

getNextShapeStyles(editor.state).color // undefined until `setShapeStyle` chooses one
```

### 参数

- `state` (`EditorState`)：白板编辑器的状态，如 `editor.state`。

### 返回 (`Partial<ShapeStyles>`)

[`setShapeStyle`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/commands.md#setshapestyle) 选择的样式。

## `getToolShapeType`

返回工具添加的形状的节点类型。

```js
import { getToolShapeType } from '@tiptap-pro/extension-whiteboard'

getToolShapeType('note') // 'stickyNote'
getToolShapeType('hand') // null
```

### 参数

- `tool` (`Tool`)：该工具，如 `note` 或 `hand`。

### 返回 (`string | null`)

节点类型，或 `null`（对于不添加任何节点的工具）。

## `isTypingTarget`

指示是否在目标类型文本上按下按键：在字段中，还是在可编辑内容（例如形状的已编辑文本或文档框架的编辑器）中。

```js
import { isTypingTarget } from '@tiptap-pro/extension-whiteboard'

// In a keydown listener for the app's own shortcuts
if (event.key === '?' && !isTypingTarget(event.target)) showShortcuts()
```

### 参数

- `target` (`EventTarget | null`)：键盘事件的目标，如 `event.target`。

### 返回 (`boolean`)

是否在目标类型文本上按下了按键。

## `focusBoard`

对于链外的代码（如工具栏按钮的单击处理程序），立即聚焦板或编辑文本时的文本。与 ProseMirror 的 `focus` 不同，它在文本只读时也可以工作。在链中，使用[`focusBoard()`命令](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/commands.md#focusboard)，该命令在链的交易之后聚焦。

```js
import { focusBoard } from '@tiptap-pro/extension-whiteboard'

// In the click handler of a toolbar button
focusBoard(editor.view)
```

### 参数

- `view` (`EditorView`)：白板编辑器的视图，如 `editor.view`。

## `findShapes`

查找具有给定 ID 的形状。

```js
import { findShapes } from '@tiptap-pro/extension-whiteboard'

const [note] = findShapes({ doc: editor.state.doc, ids: ['note-1'] })
```

### 参数 (`FindShapesOptions`)

- `doc` (`Node`)：白板的文档，如 `editor.state.doc`。
- `ids` (`readonly string[]`)：形状的 id。

### 返回 (`NodeWithPos[]`)

按文档顺序排列的形状及其位置。未知的 ID 会被跳过。

## `hasBoxGeometry`

判断形状是否具有来自 `x`、`y`、`width` 和 `height` 的方框。箭头则不然。

```js
import { findShapes, hasBoxGeometry } from '@tiptap-pro/extension-whiteboard'

const shapes = findShapes({ doc: editor.state.doc, ids })
const boxes = shapes.filter(({ node }) => hasBoxGeometry(node))
```

### 参数

- `shape` (`Node`)：形状的节点。

### 返回 (`boolean`)

形状是否有方框。

## `docIdOf`

从文档框架的节点或节点的 JSON 返回文档框架显示的文档的 ID。没有框架的框架使用它们的形状 ID，因此它们仍然可以获得自己的文档。

```js
import { docIdOf, findShapes } from '@tiptap-pro/extension-whiteboard'

const [frame] = findShapes({ doc: editor.state.doc, ids: ['frame'] })
const docId = frame && docIdOf(frame.node)
```

### 参数

- `frame` (`Node | JSONContent`)：框架的节点或其 JSON。

### 返回 (`string`)

文档的 ID。

## `shapeAttributes`

返回每个形状所需的属性，对于[自定义形状](https://tiptap.zhcndoc.com/editor/whiteboard/guides/custom-shapes.md)：其 id、位置、大小、z-index 和框架。他们将数字保留为 HTML 中的数字，当用户复制并粘贴形状时也是如此。

```js
import { shapeAttributes } from '@tiptap-pro/extension-whiteboard'

// In the node of the shape
addAttributes: () => ({
  ...shapeAttributes({ width: 320, height: 200 }),
  title: { default: '' },
}),
```

### 参数

- `size?` (`Size`)：新形状的尺寸（以板为单位）。默认值：200 x 200。

### 返回 (`Attributes`)

形状节点的 `addAttributes` 的属性。

## `dataAttribute`

返回 HTML 保留为数据属性的 [自定义形状](https://tiptap.zhcndoc.com/editor/whiteboard/guides/custom-shapes.md) 的属性，因此当用户复制和粘贴形状时它会保留。缺失值或无法解析的值将回退到默认值。

```js
import { dataAttribute, shapeAttributes } from '@tiptap-pro/extension-whiteboard'

// In the node of the shape
addAttributes: () => ({
  ...shapeAttributes(),
  votes: dataAttribute({ name: 'votes', default: 0 }),
}),
```

### 参数 (`DataAttributeOptions`)

- `name` (`string`)：属性的名称，如 `votes`。 HTML 将其保留为 `data-votes`，将 `chartData` 保留为 `data-chart-data`。
- `default` (`string | number | boolean | null | readonly unknown[] | Record<string, unknown>`)：新形状的值。它的类型决定 HTML 如何保留值：字符串、数字、布尔值或 `null`、对象和数组的 JSON。

### 返回 (`Attribute`)

形状节点的 `addAttributes` 的属性。

## `shapeNodeView`

将组件的节点视图（例如应用程序的 React 组件）转换为不带文本的 [自定义形状](https://tiptap.zhcndoc.com/editor/whiteboard/guides/custom-shapes.md)。板像它自己的形状一样放置、选择、移动形状并调整其大小，节点视图绘制组件。按下组件中的链接、按钮、字段和可编辑内容即可转到它们，按下 `data-shape-interactive` 的元素内部也是如此。它们也在只读白板上执行此操作，因此组件在更改板之前会检查 [`isBoardEditable()`](#isboardeditable)。

```js
import { ReactNodeViewRenderer } from '@tiptap/react'
import { shapeNodeView } from '@tiptap-pro/extension-whiteboard'

// In the node of the shape
addNodeView: () => shapeNodeView({ dataType: 'poll', view: ReactNodeViewRenderer(PollView) }),
```

### 参数 (`ShapeNodeViewOptions`)

- `dataType` (`string`)：形状元素的 `data-type`，类似于节点的 `renderHTML` 所设置的值。
- `view` (`NodeViewRenderer`)：形状中零部件的节点视图，如 `@tiptap/react` 中的 `ReactNodeViewRenderer(Component)`。它的元素填充了形状。

### 返回 (`NodeViewRenderer`)

形状的节点视图，针对其节点的 `addNodeView`。

## `insertShapesInFront`

按照 `shapes` 的顺序从后到前将形状添加到所有其他形状的前面，除非它们的 z 索引以其他方式排序。当形状没有 id 或白板或其他形状具有 id 时，抛出 `RangeError`。

```js
import {
  createShapeId,
  insertShapesInFront,
  stickyNoteContent,
} from '@tiptap-pro/extension-whiteboard'

const { tr, schema } = editor.state
const note = stickyNoteContent({ id: createShapeId(), x: 0, y: 0, text: 'Idea' })

insertShapesInFront({ tr, shapes: [schema.nodeFromJSON(note)] })
editor.view.dispatch(tr)
```

### 参数 (`InsertShapesInFrontOptions`)

- `tr` (`Transaction`)：添加形状的事务，如 `editor.state.tr`。
- `shapes` (`readonly Node[]`)：要添加的形状的节点。

### 返回 (`number | null`)

第一个形状的位置，如果没有添加，则为 `null`。

它将把交易发送给您。使用 `UndoRedo`，它使事务成为自己的撤消步骤。通过协作，Yjs 将快速发生的变化整合为一个步骤。

## `removeShapes`

删除具有给定 id 的形状以及其中框架中的形状。连接已删除形状的箭头会保留下来，并在它们接触的地方有一个自由端。

```js
import { removeShapes } from '@tiptap-pro/extension-whiteboard'

const { tr } = editor.state
removeShapes({ tr, ids: ['note-1'] })
editor.view.dispatch(tr)
```

### 参数 (`RemoveShapesOptions`)

- `tr` (`Transaction`)：删除其中形状的事务，如 `editor.state.tr`。
- `ids` (`readonly string[]`)：形状的 id。

### 返回 (`boolean`)

白板上是否有任何形状。

它将把交易发送给您。使用 `UndoRedo`，它使事务成为自己的撤消步骤。通过协作，Yjs 将快速发生的变化整合为一个步骤。

## `restackShapes`

将具有给定 ID 的形状移动到所有其他形状的前面或后面，并保持它们之间的顺序。只有移动的形状才会获得新的 z 索引，除非丢失或无效的形状没有空间。

```js
import { restackShapes } from '@tiptap-pro/extension-whiteboard'

const { tr } = editor.state
restackShapes({ tr, ids: ['note-1'], place: 'back' })
editor.view.dispatch(tr)
```

### 参数 (`RestackShapesOptions`)

- `tr` (`Transaction`)：移动形状的事务，如 `editor.state.tr`。
- `ids` (`readonly string[]`)：形状的 id。
- `place` (`StackPlace`)：形状所在的位置：`front`，位于所有其他形状的前面，或 `back`，位于它们的后面。

### 返回 (`boolean`)

白板上是否有任何形状。

它将把交易发送给您。使用 `UndoRedo`，它使事务成为自己的撤消步骤。通过协作，Yjs 将快速发生的变化整合为一个步骤。

## `keepShapeHeights`

保留事务赋予其形状的高度，以供稍后到达的内容使用，例如 AI 在添加框架后写入的文档框架的文档。如果没有它，该白板会使自由文本和文档框架与其内容一样高。

```js
import { keepShapeHeights } from '@tiptap-pro/extension-whiteboard'

const { tr } = editor.state
// … add a doc frame whose document arrives later
editor.view.dispatch(keepShapeHeights(tr))
```

### 参数

- `tr` (`Transaction`)：事务，与 `editor.state.tr` 类似。

### 返回 (`Transaction`)

相同的事务。

它仅标记事务并且不执行撤消步骤。

## `getDocEditors`

返回白板上文档框架显示的文档的编辑者。

```js
import { getDocEditors } from '@tiptap-pro/extension-whiteboard'

const documents = getDocEditors(editor).map((docEditor) => docEditor.getJSON())
```

### 参数

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`Editor[]`)

文档的编辑者，一旦白板的编辑器被销毁，则没有。

## `getEditedDocEditor`

返回文档框架编辑的文档的编辑器。

```js
import { getEditedDocEditor } from '@tiptap-pro/extension-whiteboard'

// A bold button that works in documents too
const textEditor = getEditedDocEditor(editor) ?? editor
textEditor.commands.toggleBold()
```

### 参数

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`Editor | null`)

文档的编辑者，或 `null`（当未编辑任何内容时，例如白板的编辑器被销毁时）。

## `addImageFiles`

上传带有白板的 [`images`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#boardimages) 的图像文件，然后在板历史记录的一个步骤中，在所有其他形状前面为每个形状添加一个图像形状，并选择它们。这些图像保持其比例，适合舞台的一半，并排站在 `point` 周围。 `images`不允许的文件以及上传失败的文件转到其`onError`。在只读白板上不执行任何操作。请参阅[图像](https://tiptap.zhcndoc.com/editor/whiteboard/guides/images.md)。

```js
import { addImageFiles } from '@tiptap-pro/extension-whiteboard'

input.addEventListener('change', () => addImageFiles({ stage, editor, files: input.files ?? [] }))
```

### 参数 (`AddImageFilesOptions`)

- `stage` (`HTMLElement`)：白板周围的元件。
- `editor` (`Editor`)：白板的​​编辑器。
- `files` (`Iterable<File>`)：要添加的文件，如文件输入的文件。
- `point?` (`Point`)：图像的中间，以板为单位。默认：舞台中间。

### 返回 (`Promise<string[]>`)

添加的图像形状的 ID。如果没有 `images`，在只读白板上，或者在上传结束之前编辑器被销毁，则不会。

## `createRemoteCursors`

显示 `editor` 白板上其他用户的光标及其名称。每个光标位于用户指向的位置，在每次缩放时保持其大小，并在用户共享的点上平滑移动，但稍晚一些。用户拖动的形状会随着光标移动，但文档不会改变：其他用户的拖放会改变它。请参阅[显示其他人的光标](https://tiptap.zhcndoc.com/editor/whiteboard/guides/collaboration.md#show-the-cursors-of-others)。

```js
import { createRemoteCursors } from '@tiptap-pro/extension-whiteboard'

const cursors = createRemoteCursors(editor)
cursors.update([{ owner: clientId, point: { x: 120, y: 80 }, name: 'Ada', color: '#be185d' }])
```

### 参数

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`RemoteCursors`)

光标，具有两个功能：

- `update(cursors)` 显示这些光标]\(/editor/whiteboard/api-reference/types#remotecursor) 及其拖动的形状，并淡出其他光标。没有有效点的光标或没有形状 ID 和增量的拖动将被排除，因为其他用户可以共享任何内容。
- `destroy()` 立即删除每个光标，并在文档中显示拖动的形状。销毁编辑器也能做到这一点。

## `createRemoteMoves`

显示 `editor` 白板上其他用户的拖动情况。它们的形状和连接它们的箭头会移动，但文档不会改变：其他用户的拖放会改变它。

```js
import { createRemoteMoves } from '@tiptap-pro/extension-whiteboard'

const moves = createRemoteMoves(editor)
moves.show({ owner: clientId, ids: ['note'], delta: { x: 40, y: 0 } })
moves.end(clientId)
```

### 参数

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`RemoteMoves`)

移动，有两个功能：

- `show({ owner, ids, delta })` 显示 `owner` 的拖动形状，由 `delta` 移动。 `owner` 是拖动的对象，就像另一个用户的客户端 ID，`delta` 是拖动自开始以来使形状移动的距离（以板为单位）。
- `end(owner)` 结束 `owner` 的拖动。它的形状显示为文档中的形状。

## `exportBoard`

将板另存为白板文件：其 JSON 及其文档框架显示的文档。请参阅[导出和导入](https://tiptap.zhcndoc.com/editor/whiteboard/guides/export-and-import.md)。

```js
import { exportBoard } from '@tiptap-pro/extension-whiteboard'

const json = JSON.stringify(exportBoard({ editor }))
```

### 参数 (`ExportBoardOptions`)

- `editor` (`Editor`)：白板的​​编辑器。

### 返回 (`BoardFile`)

白板文件，用 `JSON.stringify` 写入。请参阅[`BoardFile`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#boardfile)。

## `importBoard`

从 `exportBoard` 打开白板文件，这是白板历史记录的一步。每个文档框架显示一个新文档，[`BoardDocs.load`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#boarddocs) 从文件中填充，因此其他板保留其文档。同时打开 Excalidraw 和 tldraw 保存的文件，请参阅[打开 Excalidraw 和 tldraw 文件](https://tiptap.zhcndoc.com/editor/whiteboard/guides/export-and-import.md#open-excalidraw-and-tldraw-files)。当 JSON 不是这些文件或较新版本写入时，抛出 [`BoardFileError`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#boardfileerror)。

```js
import { importBoard } from '@tiptap-pro/extension-whiteboard'

importBoard({ editor, file: JSON.parse(await file.text()) })
```

### 参数 (`ImportBoardOptions`)

- `editor` (`Editor`)：白板的​​编辑器。
- `file` (`unknown`)：白板文件的解析 JSON，如 `exportBoard` 返回它，或者 Excalidraw 或 tldraw 保存的文件的 JSON。
- `mode?` (`'replace' | 'insert'`): `replace` 显示文件的板而不是当前的板。 `insert` 将其形状的副本添加到当前形状的前面（就像粘贴一样），然后选择它们。默认值：`'replace'`。

### 返回 (`ImportBoardResult`)

添加的形状的 ID，以及编辑器无法显示的文件的形状。请参阅[`ImportBoardResult`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#importboardresult)。

## `exportBoardSvg`

将白板的形状绘制为 SVG 图像，如页面所示：使用应用程序的样式以及它们使用的字体和图像。选择项、句柄和插入符不会出现。文本是 `foreignObject` 中的 HTML，浏览器会显示，但某些矢量编辑器不会显示。

```js
import { exportBoardSvg } from '@tiptap-pro/extension-whiteboard'

const image = await exportBoardSvg({ editor, background: '#fff' })
```

### 参数 (`ExportBoardSvgOptions`)

- `editor` (`Editor`)：白板的​​编辑器。它的板必须在页面中，否则函数会抛出异常。
- `ids?` (`readonly string[]`)：要绘制的形状的 ID。它们之间的框架带来了它的形状。默认：所有形状。
- `padding?` (`number`)：形状周围的空间（以板为单位）。默认值：`16`。
- `background?` (`string`)：形状后面的 CSS 颜色。没有它，图像在那里是透明的。

### 返回 (`Promise<BoardSvg | null>`)

SVG 及其大小，或者当没有要绘制的形状时返回 `null`。请参阅[`BoardSvg`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/types.md#boardsvg)。

## `exportBoardImage`

将白板的形状绘制为 PNG 或 JPEG 图像，如 [`exportBoardSvg`](#exportboardsvg) 绘制它们。 JPEG 获得白色背景，除非 `background` 设置为 1。在 Safari 中，图像没有框阴影。

```js
import { exportBoardImage } from '@tiptap-pro/extension-whiteboard'

const png = await exportBoardImage({ editor, background: '#fff' })
```

### 参数 (`ExportBoardImageOptions`)

[`exportBoardSvg`](#exportboardsvg) 的选项，以及：

- `format?` (`'png' | 'jpeg'`)：文件类型。默认值：`'png'`。
- `pixelRatio?` (`number`)：每个板单元的像素。当画布不能那么大时，它会更低。默认值：`2`。
- `quality?` (`number`)：JPEG 的质量，从 0 到 1。

### 返回 (`Promise<Blob | null>`)

图像文件，或没有要绘制的形状时的 `null`。

## `geoKinds`

该种几何形状，其名称为`kind`。

值：`['rectangle', 'ellipse', 'diamond', 'triangle']`。

## `shapeColors`

形状的默认颜色，例如颜色菜单的样本颜色。形状存储名称，CSS 决定它的外观。使用 `WhiteboardKit` 的 `colors` 选项添加您自己的颜色，请参阅[Colors](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/styling.md#colors)。

值：`['black', 'gray', 'red', 'orange', 'yellow', 'green', 'blue', 'violet']`。

## `shapeStyles`

形状的样式及其默认值的名称。请参阅[形状和工具](https://tiptap.zhcndoc.com/editor/whiteboard/guides/shapes-and-tools.md#styles-for-new-shapes)。

值：`{ color: shapeColors, fontSize: ['s', 'm', 'l', 'xl'], textAlign: ['start', 'center', 'end'], font: ['sans', 'serif', 'mono'], arrowheads: ['none', 'end', 'both'], arrowheadKind: ['triangle', 'arrow', 'dot', 'diamond', 'bar'], arrowKind: ['straight', 'curved', 'elbow'], dash: ['solid', 'dashed', 'dotted'] }`。

## `stickyNoteSize`

未指定的便签大小（以板为单位）。

值：`{ width: 220, height: 160 }`。

## `toolKeys`

未编辑文本时选择每个工具的默认键，例如工具栏的工具提示。使用 [`WhiteboardKit`](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/extensions.md#whiteboardkit) 的 `toolKeys` 选项更改它们。

值：`{ select: 'v', hand: 'h', note: 'n', text: 't', doc: 'w', rectangle: 'r', ellipse: 'o', diamond: 'd', pen: 'p', arrow: 'a', frame: 'f', eraser: 'e' }`。

## `defaultFrameName`

不带帧的 [frame](https://tiptap.zhcndoc.com/editor/whiteboard/guides/frames.md) 显示的名称，如白板上帧的列表。

值：`'Frame'`。

## `boardStyles`

白板所需的 CSS。白板将其添加到页面本身，除非其编辑器具有 `injectCSS: false`。请参阅[样式](https://tiptap.zhcndoc.com/editor/whiteboard/api-reference/styling.md#the-boards-css)。

类型：`string`。