# FShapeText

- Human documentation: [https://docs.univer.ai/reference/facade/shape-text](https://docs.univer.ai/reference/facade/shape-text)

- Agent Markdown: [https://docs.univer.ai/reference/facade/shape-text.md](https://docs.univer.ai/reference/facade/shape-text.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/shape-text.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/shape-text.mdx)

---

A live text facade for a Shape in any supported host.

Sheet, Doc, Slide, and Board Shapes share this rich-text effect path. Glow and outer shadow support here does not
imply that a host's standalone document text UI exposes the same authoring controls.

## Access

Access through:

* [`FShape.getText()`](https://docs.univer.ai/reference/facade/shape.md#gettext)

## Example

Sheet

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fShape = fWorksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Rect })
const fShapeText = fShape?.getText()
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument.getParagraphs()[0]
const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  placement: {
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
    },
  },
})
const fShapeText = fShape?.getText()
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const fShape = fSlide.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Rect })
const fShapeText = fShape?.getText()
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const fShape = fBoard.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Rect })
const fShapeText = fShape?.getText()
```

```ts
fShapeText
  ?.setText('Quarterly review')
  .setColor('#2563eb')
  .setFontSize(18)
  .setBold(true)
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER)
  .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)
  .setTextBoxOptions({ padding: { left: 12, right: 12, top: 8, bottom: 8 } })
```

## Setup

Register [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/engine-shape/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-shape`

### `FShapeText.getPlainText`

Returns the Shape text as plain text.

```typescript
getPlainText(): string | null
```

**Returns**

The plain text, or `null` when the Shape has no text.

**Examples**

```ts
console.log(fShapeText.getPlainText())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.getRichText`

Returns the Shape text as a detached rich-text value.

To edit existing Shape text, call `copy()` on the returned value, change the builder, and pass it to
`setRichText()` to persist the result.

```typescript
getRichText(): RichTextValue | null
```

**Returns**

A rich-text value, or `null` when the Shape has no text.

**Examples**

```ts
const richText = fShapeText.getRichText()?.copy()
const [link] = richText?.getLinks() ?? []
if (richText && link) {
  richText.updateLink(link.rangeId, 'https://univer.ai/docs')
  fShapeText.setRichText(richText)
}
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.getTextBoxOptions`

Returns the resolved Shape text-box layout options.

```typescript
getTextBoxOptions(): IResolvedShapeTextBoxOptions | null
```

**Returns**

The resolved text-box options, or `null` when the Shape has no text.

**Examples**

```ts
console.log(fShapeText.getTextBoxOptions())
```

**Types:** [`IResolvedShapeTextBoxOptions`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setBold`

Sets whether the complete Shape text is bold.

```typescript
setBold(bold: boolean): this
```

**Parameters**

* `bold` — Required. Whether bold formatting is enabled.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setBold(true)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setColor`

Replaces the complete Shape text fill with a solid color.

```typescript
setColor(color: string, opacity?: number): this
```

**Parameters**

* `color` — Required. The CSS text color.
* `opacity` — Optional. Optional opacity in the range from 0 to 1.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setColor('#2563eb', 0.8)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setFontFamily`

Sets the font family of the complete Shape text.

```typescript
setFontFamily(fontFamily: string): this
```

**Parameters**

* `fontFamily` — Required. The font family name.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setFontFamily('Inter')
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setFontSize`

Sets the font size of the complete Shape text.

```typescript
setFontSize(fontSize: number): this
```

**Parameters**

* `fontSize` — Required. The font size in points.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setFontSize(18)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setGradientFill`

Replaces the complete Shape text fill with a gradient.

```typescript
setGradientFill(gradientType: ShapeGradientTypeEnum, stops: IShapeGradientStop[], angle?: number): this
```

**Parameters**

* `gradientType` — Required. The gradient geometry.
* `stops` — Required. At least two gradient color stops.
* `angle` — Optional. Optional gradient angle in degrees.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setGradientFill(
  univerAPI.Enum.ShapeGradientTypeEnum.Linear,
  [
    { position: 0, color: '#2563eb' },
    { position: 1, color: '#a855f7' },
  ],
  45,
)
```

**Types:** [`ShapeGradientTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts) · [`IShapeGradientStop`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setHorizontalAlign`

Sets the horizontal alignment of the Shape text.

```typescript
setHorizontalAlign(align: HorizontalAlign): this
```

**Parameters**

* `align` — Required. The horizontal alignment.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER)
```

**Types:** [`HorizontalAlign`](https://docs.univer.ai/reference/enums/horizontal-align.md)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setImageFill`

Replaces the complete Shape text fill with an image.

```typescript
setImageFill(source: string, sourceType?: ImageSourceTypeEnum, options?: IShapeTextImageFillOptions): this
```

**Parameters**

* `source` — Required. The URL, UUID, or base64 image source.
* `sourceType` — Optional. Default: `ImageSourceTypeEnum.URL`. The image source type. Defaults to URL.
* `options` — Optional. Default: `{}`. Optional picture opacity, mode, scale, and offset.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setImageFill(
  'https://github.com/dream-num.png',
  univerAPI.Enum.ShapeImageSourceTypeEnum.URL,
  { opacity: 0.9, mode: univerAPI.Enum.ShapeImageFillModeEnum.Stretch },
)
```

**Types:** [`ImageSourceTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts) · [`IShapeTextImageFillOptions`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setItalic`

Sets whether the complete Shape text is italic.

```typescript
setItalic(italic: boolean): this
```

**Parameters**

* `italic` — Required. Whether italic formatting is enabled.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setItalic(true)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setNoneFill`

Removes the visible fill from the complete Shape text.

```typescript
setNoneFill(): this
```

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setNoneFill()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setRichText`

Replaces the Shape text with a rich-text value.

```typescript
setRichText(value: RichTextValue): this
```

**Parameters**

* `value` — Required.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
const richText = univerAPI
  .newRichText()
  .text('Read ')
  .link('Univer documentation', 'https://docs.univer.ai')
  .text(' for details.')
fShapeText.setRichText(richText)
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setStrikethrough`

Sets whether the complete Shape text has a strikethrough.

```typescript
setStrikethrough(strikethrough: boolean): this
```

**Parameters**

* `strikethrough` — Required. Whether strikethrough formatting is enabled.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setStrikethrough(true)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setText`

Replaces the Shape text with plain text.

```typescript
setText(text: string): this
```

**Parameters**

* `text` — Required. The plain text to set.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setText('Quarterly review')
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setTextBoxOptions`

Updates the Shape text-box layout options.

```typescript
setTextBoxOptions(options: IShapeTextBoxOptions): this
```

**Parameters**

* `options` — Required. The text-box layout options to apply.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setTextBoxOptions({
  textDirection: univerAPI.Enum.ShapeTextDirection.Horz,
  autoFitType: univerAPI.Enum.ShapeTextAutoFitType.NoAutoFit,
  textWrap: univerAPI.Enum.ShapeTextWrapType.Square,
  padding: { left: 12, right: 12, top: 8, bottom: 8 },
})
```

**Types:** [`IShapeTextBoxOptions`](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setTextStyle`

Merges a text style into the complete Shape text.

```typescript
setTextStyle(style: ITextStyle): this
```

**Parameters**

* `style` — Required. The Univer document text style to apply.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setTextStyle({
  ff: 'Inter',
  fs: 18,
  glow: { color: '#f97316', radius: 6 },
  outerShadow: {
    color: '#000000',
    opacity: 0.35,
    blurRadius: 4,
    distance: 3,
    direction: 45,
  },
})
```

**Types:** [`ITextStyle`](https://docs.univer.ai/reference/types/text-style.md)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setUnderline`

Sets whether the complete Shape text is underlined.

```typescript
setUnderline(underline: boolean): this
```

**Parameters**

* `underline` — Required. Whether underline formatting is enabled.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setUnderline(true)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)

### `FShapeText.setVerticalAlign`

Sets the vertical alignment of the Shape text.

```typescript
setVerticalAlign(align: VerticalAlign): this
```

**Parameters**

* `align` — Required. The vertical alignment.

**Returns**

This Shape text facade for chaining.

**Examples**

```ts
fShapeText.setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)
```

**Types:** [`VerticalAlign`](https://docs.univer.ai/reference/enums/vertical-align.md)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape@1.0.0-rc.0/lib/types/facade/f-shape-text.d.ts)