Rich Text Usage Guide

Univer provides powerful rich text features that can be used in various scenarios, including cell content, comments, and hyperlinks. This guide will introduce how to use the rich text functionality.

Facade API

Facade API provides a series of methods to create rich text related objects:

// Create rich text
const richText = univerAPI.newRichText()
const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello Univer\r\n' } })

// Create paragraph style
const paragraphStyle = univerAPI.newParagraphStyle()
const paragraphStyleValue = univerAPI.newParagraphStyleValue()

// Create text style
const textStyle = univerAPI.newTextStyle()
const textStyleValue = univerAPI.newTextStyleValue()

// Create text decoration
const decoration = univerAPI.newTextDecoration()

Each creation method has corresponding Builder and Value versions:

Builder versions (like newRichText) are used for creating and modifying styles
Value versions (like newRichTextValue) are used for creating read-only style objects

Basic Concepts

The rich text system mainly consists of two core components:

TextStyle (Text Style): Controls the appearance of text, such as font, size, color, etc.
ParagraphStyle (Paragraph Style): Controls paragraph-level formatting, such as alignment, indentation, line spacing, etc.

Text Style Settings

Creating Text Styles

// Create a basic text style
const textStyle = univerAPI.newTextStyle()
  .setFontFamily('Arial')
  .setFontSize(12)
  .setItalic(true)
  .setBold(true)
  .build()

// Create a text style with colors
const coloredStyle = univerAPI.newTextStyle()
  .setColor({ rgb: '#FF0000' }) // Set red text
  .setBackground({ rgb: '#FFFF00' }) // Set yellow background
  .build()

Text Decorations

// Add underline
const underlineStyle = univerAPI.newTextStyle()
  .setUnderline(
    univerAPI.newTextDecoration()
      .setShow(true)
      .setColor({ rgb: '#0000FF' })
      .setLineType(univerAPI.Enum.TextDecoration.SINGLE),
  )
  .build()

// Add strikethrough
const strikethroughStyle = univerAPI.newTextStyle()
  .setStrikethrough(
    univerAPI.newTextDecoration()
      .setShow(true),
  )
  .build()

Paragraph Style Settings

Creating Paragraph Styles

// Create a basic paragraph style
const paragraphStyle = univerAPI.newParagraphStyle()
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER) // Center alignment
  .setLineSpacing(1.5) // 1.5 line spacing
  .build()

// Set paragraph indentation
const indentedStyle = univerAPI.newParagraphStyle()
  .setIndentFirstLine({ value: 2, unit: 'cm' }) // First line indent 2cm
  .setIndentStart({ value: 1, unit: 'cm' }) // Left indent 1cm
  .build()

Use Cases

1. Cell Rich Text

There are two ways to set rich text for cells: setRichTextValueForCell and setRichTextValues.

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getValue(true))

// Set A1 cell value to rich text
const richText = univerAPI.newRichText()
  .insertText('Hello World')
  .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
  .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } })
fRange.setRichTextValueForCell(richText)
console.log(fRange.getValue(true).toPlainText()) // Hello World

// Set A1:B2 cell value to rich text
fRange.setRichTextValues([
  [richText, richText],
  [null, null],
])
console.log(fRange.getValue(true).toPlainText()) // Hello World

2. Comment Rich Text

// Add formatted comments
const range = univerAPI.getActiveWorkbook()
  .getActiveSheet()
  .getActiveRange()

// Create comment content
const comment = univerAPI.newTheadComment()
  .setContent(
    univerAPI.newRichText()
      .insertText('Please check the data in this cell'),
  )

// Add comment asynchronously
const success = await range.addCommentAsync(comment)
if (success) {
  console.log('Comment added successfully')
}

3. Hyperlink Rich Text

// Create rich text with hyperlink
const range = univerAPI.getActiveWorkbook()
  .getActiveSheet()
  .getActiveRange()

// Create hyperlink using newRichText().insertLink
const richText = univerAPI.newRichText()
  .insertLink('Visit Univer', 'https://univer.ai')

// Set to cell
range.setRichTextValueForCell(richText)

On this page