FShapeText

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()

Example

Sheet

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

Doc

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

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

Board

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

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 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.

@univerjs-pro/engine-shape

FShapeText.getPlainText

Returns the Shape text as plain text.

getPlainText(): string | null

Returns

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

Examples

console.log(fShapeText.getPlainText())

Package: @univerjs-pro/engine-shape · Type definitions

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.

getRichText(): RichTextValue | null

Returns

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

Examples

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

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.getTextBoxOptions

Returns the resolved Shape text-box layout options.

getTextBoxOptions(): IResolvedShapeTextBoxOptions | null

Returns

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

Examples

console.log(fShapeText.getTextBoxOptions())

Types: IResolvedShapeTextBoxOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setBold

Sets whether the complete Shape text is bold.

setBold(bold: boolean): this

Parameters

• bold — Required. Whether bold formatting is enabled.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setBold(true)

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setColor

Replaces the complete Shape text fill with a solid color.

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

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

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setFontFamily

Sets the font family of the complete Shape text.

setFontFamily(fontFamily: string): this

Parameters

• fontFamily — Required. The font family name.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setFontFamily('Inter')

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setFontSize

Sets the font size of the complete Shape text.

setFontSize(fontSize: number): this

Parameters

• fontSize — Required. The font size in points.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setFontSize(18)

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setGradientFill

Replaces the complete Shape text fill with a gradient.

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

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

Types: ShapeGradientTypeEnum · IShapeGradientStop

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setHorizontalAlign

Sets the horizontal alignment of the Shape text.

setHorizontalAlign(align: HorizontalAlign): this

Parameters

• align — Required. The horizontal alignment.

Returns

This Shape text facade for chaining.

Examples

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

Types: HorizontalAlign

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setImageFill

Replaces the complete Shape text fill with an image.

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

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

Types: ImageSourceTypeEnum · IShapeTextImageFillOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setItalic

Sets whether the complete Shape text is italic.

setItalic(italic: boolean): this

Parameters

• italic — Required. Whether italic formatting is enabled.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setItalic(true)

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setNoneFill

Removes the visible fill from the complete Shape text.

setNoneFill(): this

Returns

This Shape text facade for chaining.

Examples

fShapeText.setNoneFill()

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setRichText

Replaces the Shape text with a rich-text value.

setRichText(value: RichTextValue): this

Parameters

• value — Required.

Returns

This Shape text facade for chaining.

Examples

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

Types: RichTextValue

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setStrikethrough

Sets whether the complete Shape text has a strikethrough.

setStrikethrough(strikethrough: boolean): this

Parameters

• strikethrough — Required. Whether strikethrough formatting is enabled.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setStrikethrough(true)

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setText

Replaces the Shape text with plain text.

setText(text: string): this

Parameters

• text — Required. The plain text to set.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setText('Quarterly review')

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setTextBoxOptions

Updates the Shape text-box layout options.

setTextBoxOptions(options: IShapeTextBoxOptions): this

Parameters

• options — Required. The text-box layout options to apply.

Returns

This Shape text facade for chaining.

Examples

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

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setTextStyle

Merges a text style into the complete Shape text.

setTextStyle(style: ITextStyle): this

Parameters

• style — Required. The Univer document text style to apply.

Returns

This Shape text facade for chaining.

Examples

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

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setUnderline

Sets whether the complete Shape text is underlined.

setUnderline(underline: boolean): this

Parameters

• underline — Required. Whether underline formatting is enabled.

Returns

This Shape text facade for chaining.

Examples

fShapeText.setUnderline(true)

Package: @univerjs-pro/engine-shape · Type definitions

FShapeText.setVerticalAlign

Sets the vertical alignment of the Shape text.

setVerticalAlign(align: VerticalAlign): this

Parameters

• align — Required. The vertical alignment.

Returns

This Shape text facade for chaining.

Examples

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

Types: VerticalAlign

Package: @univerjs-pro/engine-shape · Type definitions