# 文字 API

> BoundedTextbox 配置项、VerticalText 配置项、按字形测量的文字类、移动端输入适配器，以及保留样式的文字命令。

Source: https://fabricjs-document-engine.jscrate.dev/zh/docs/api/text-api
Last updated: 2026-10-02

`fabricjs-document-engine/text` 入口包含文字类和辅助函数。各指南说明了什么时候用哪一个：[文本框宽度](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/textbox-width)、[竖排文字](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/vertical-text)、[阿拉伯文和从右到左文字](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/rtl-text)、[手机上的文字输入](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/mobile-text-input)和[用代码修改文字样式](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/text-styles)。

```ts
import {
  BoundedTextbox,
  ShapedIText,
  ShapedTextbox,
  VerticalText,
  attachMobileTextInput,
  textObjects,
} from "fabricjs-document-engine/text";
```

## 注册这些类

```ts
const engine = createDocumentEngine({ canvas, customObjects: textObjects });
```

`textObjects` 包含 `BoundedTextbox`、`ShapedIText`、`ShapedTextbox` 和 `VerticalText`，使用它们的文档才能保存和加载。没有引擎时，请在 `loadFromJSON` 之前调用 `registerTextObjects()`。

```ts
function registerTextObjects(): void
```

Registers `BoundedTextbox`, `ShapedIText`, `ShapedTextbox` and `VerticalText` with Fabric. Engines use `customObjects: textObjects` instead.

## BoundedTextbox 配置项

`BoundedTextbox` 接受所有 Textbox 配置项，另外还有这些 BoundedTextbox 配置项：

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `breakWords` (required) | `BreakWords` | `"anywhere"` | Break a word wider than the box between letters. `never` acts like a Textbox. |
| `maxHeight` (required) | `number \| undefined` | `none` | The tallest the box may be. |
| `overflow` (required) | `TextOverflow` | `"visible"` | `clip` cuts at `maxHeight`; `ellipsis` hides lines past it and ends the last one with "…". |
| `fit` (required) | `TextFit` | `"none"` | `shrink` lowers the font size, in half points, until the text fits `maxHeight`. The saved size does not change. |
| `minFontSize` (required) | `number` | `6` | The smallest size `shrink` goes to. |
| `shaping` (required) | `boolean` | `false` | Measure letters as the browser joins them, for Arabic and ligatures. |

`getBaseFontSize()` 返回 `fit: "shrink"` 之前你设定的字号，`fitScale` 是实际绘制的比例。

## VerticalText

`VerticalText` 接受所有 IText 配置项，另外还有：

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `textOrientation` (required) | `TextOrientation` | `"mixed"` | `mixed` turns Latin text 90°; `upright` stands every character up. |
| `combineUpright` (required) | `CombineUpright` | `"none"` | `digits2` sets one or two digits side by side in one square. |

```ts
function orientationOf(grapheme: string): Orientation
```

How a character stands in vertical text, after Unicode UAX #50.

## ShapedIText 和 ShapedTextbox

`ShapedIText` 和 `ShapedTextbox` 的配置项和 IText、Textbox 相同，只改变字母的测量方式。

## attachMobileTextInput

```ts
function attachMobileTextInput(canvas: Canvas, options?: MobileTextInputOptions): MobileTextInput
```

Makes typing with phone keyboards, autocorrect and IME land in the right place on every text object of a canvas.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `inputMode` | `string` | `"text"` | Which keyboard to show. |
| `enterKeyHint` | `string` | `"enter"` | The label of the Enter key. |
| `autocapitalize` | `string` | `"sentences"` | Capital letters at the start of sentences. |
| `autocorrect` | `boolean` | `true` | Let the keyboard correct words; the adapter applies corrections in the right place. |
| `spellcheck` | `boolean` | `false` | Spell checking in the textarea. |

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `detach` (required) | `(): void` | — | Puts Fabric's own text input back. |

## createTextCommands

这些函数来自主入口 `fabricjs-document-engine`。

```ts
function createTextCommands(engine: DocumentEngine): TextCommands
```

Text edits that keep each letter's style in place, one undo step each.

```ts
function replaceTextRange(target: EditableTextObject, start: number, end: number, insert: string, style?: InsertedStyle): void
```

Replaces graphemes `start` to `end` and moves every style with its letters. Keeps the cursor and the hidden textarea in step, and fires `text:changed`.

```ts
function setTextRangeStyle(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void
```

Merges a style into graphemes `start` to `end`.

```ts
function shiftStyleRuns(runs: readonly StyleRun[], start: number, end: number, insertedLength: number, style?: InsertedStyle): StyleRun[]
```

Moves style runs for one edit. Pure, O(runs).

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `insertText` (required) | `(target: EditableTextObject, index: number, text: string, style?: InsertedStyle): void` | — | Inserts text at a grapheme index. The new text takes the style of the letter before it unless `style` is given. |
| `deleteText` (required) | `(target: EditableTextObject, start: number, end: number): void` | — | Deletes graphemes `start` to `end`. |
| `replaceText` (required) | `(target: EditableTextObject, start: number, end: number, text: string, style?: InsertedStyle): void` | — | Replaces graphemes `start` to `end` with new text. |
| `setTextStyle` (required) | `(target: EditableTextObject, start: number, end: number, style: TextStyleDeclaration): void` | — | Merges a style into graphemes `start` to `end`. |

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` (required) | `number` | — | First grapheme of the run. |
| `end` (required) | `number` | — | One past the last grapheme. |
| `style` (required) | `TextStyleDeclaration` | — | The Fabric style declaration. |

所有 BoundedTextbox 配置项和其他内容在包里都有类型，编辑器会在你输入时显示它们。