Rich Text Guide

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

API Creation Methods

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


// Create rich text
const richText = univerApi.newRichText();
const richTextValue = univerApi.newRichTextValue(data);
 
// 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 consists of two core components:

TextStyle: Controls text appearance, such as font, size, color, etc.
ParagraphStyle: 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(TextDecoration.SINGLE)
            .build()
    )
    .build();
 
// Add strikethrough
const strikethroughStyle = univerApi.newTextStyle()
    .setStrikethrough(
        univerApi.newTextDecoration()
            .setShow(true)
            .build()
    )
    .build();

Paragraph Style Settings

Creating Paragraph Styles


// Create basic paragraph style
const paragraphStyle = univerApi.newParagraphStyle()
    .setHorizontalAlign(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:


// Method 1: Using setRichText
function applyCellRichText(univerApi: any) {
    const textStyle = univerApi.newTextStyle()
        .setFontFamily('Arial')
        .setBold(true)
        .setColor({ rgb: '#FF0000' })
        .build();
        
    const range = univerApi.getActiveSheet().getRange('A1');
    range.setRichText([{
        text: 'Hello',
        style: textStyle
    }, {
        text: ' World',
        style: univerApi.newTextStyle()
            .setItalic(true)
            .setColor({ rgb: '#0000FF' })
            .build()
    }]);
}
 
// Method 2: Using setRichTextValueForCell (Recommended)
function setRichTextValue(univerApi: any) {
    const range = univerApi.getActiveWorkbook()
        .getActiveSheet()
        .getActiveRange();
    
    // Create rich text and insert text
    const richText = univerApi.newRichText()
        .insertText('Hello World');
    
    // Set rich text value
    range.setRichTextValueForCell(richText);
}

2. Comment Rich Text


// Add formatted comments
async function addFormattedComment(univerApi: any) {
    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
function createHyperlink(univerApi: any) {
    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);
}