Class RichTextValueBuilder

  • RichTextValueBuilder is used to create Rich Text values.

  • The builder includes methods to set text, apply text styles, and set link URLs.

  • Styles and link URLs can be applied to the entire value or specific substrings using offsets.

  • The build() method finalizes the creation of the RichTextValue.
RichTextValueBuilder

A builder for Rich Text values.

Methods

MethodReturn typeBrief description
build()RichTextValueCreates a Rich Text value from this builder.
setLinkUrl(startOffset, endOffset, linkUrl)RichTextValueBuilderSets the link URL for the given substring of this value, or clears it if linkUrl is null.
setLinkUrl(linkUrl)RichTextValueBuilderSets the link URL for the entire value, or clears it if linkUrl is null.
setText(text)RichTextValueBuilderSets the text for this value and clears any existing text style.
setTextStyle(startOffset, endOffset, textStyle)RichTextValueBuilderApplies a text style to the given substring of this value.
setTextStyle(textStyle)RichTextValueBuilderApplies a text style to the entire value.

Detailed documentation

build()

Creates a Rich Text value from this builder.

Return

RichTextValue — A Rich Text value created from this builder.

setLinkUrl(startOffset, endOffset, linkUrl)

Sets the link URL for the given substring of this value, or clears it if linkUrl is null. 

// Creates a Rich Text value for the text "foo no baz" with "foo" pointing to
// "https://bar.foo" and "baz" to "https://abc.xyz".
// "foo" is underlined with the default link color, whereas "baz" has its text
// style overridden by a call to `setTextStyle`, and is therefore black and bold
// with no underlining.
const boldStyle = SpreadsheetApp.newTextStyle()
                      .setUnderline(false)
                      .setBold(true)
                      .setForegroundColor('#000000')
                      .build();
const value = SpreadsheetApp.newRichTextValue()
                  .setText('foo no baz')
                  .setLinkUrl(0, 3, 'https://bar.foo')
                  .setLinkUrl(7, 10, 'https://abc.xyz')
                  .setTextStyle(7, 10, boldStyle)
                  .build();

Parameters

NameTypeDescription
startOffsetIntegerThe start offset for the substring, inclusive.
endOffsetIntegerThe end offset for the substring, exclusive.
linkUrlStringThe link URL being set.

Return

RichTextValueBuilder — This builder, for chaining.

setLinkUrl(linkUrl)

Sets the link URL for the entire value, or clears it if linkUrl is null. 

// Creates a Rich Text value for the text "Foo" which points to
// "https://bar.foo".
const value = SpreadsheetApp.newRichTextValue()
                  .setText('Foo')
                  .setLinkUrl('https://bar.foo')
                  .build();

Parameters

NameTypeDescription
linkUrlStringThe link URL being set.

Return

RichTextValueBuilder — This builder, for chaining.

setText(text)

Sets the text for this value and clears any existing text style. When creating a new Rich Text value, this should be called before setTextStyle(startOffset, endOffset, textStyle).

Parameters

NameTypeDescription
textStringThe text for this value.

Return

RichTextValueBuilder — This builder, for chaining.

setTextStyle(startOffset, endOffset, textStyle)

Applies a text style to the given substring of this value. Offsets are 0 based and are relative to the cell’s text value. Does nothing if textStyle is null. 

// Creates a Rich Text value for the text "HelloWorld", with "Hello" bolded, and
// "World" italicized.
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
const value = SpreadsheetApp.newRichTextValue()
                  .setText('HelloWorld')
                  .setTextStyle(0, 5, bold)
                  .setTextStyle(5, 10, italic)
                  .build();

Parameters

NameTypeDescription
startOffsetIntegerThe start offset for the substring, inclusive.
endOffsetIntegerThe end offset for the substring, exclusive.
textStyleTextStyleThe text style being set.

Return

RichTextValueBuilder — This builder, for chaining.

setTextStyle(textStyle)

Applies a text style to the entire value. Previously set text styles are only affected if they are directly overwritten by values within textStyle. Does nothing if textStyle is null. 

// Creates a Rich Text value for the text "HelloWorld" with "Hello" bolded and
// italicized, and "World" only italicized.
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
const value = SpreadsheetApp.newRichTextValue()
                  .setText('HelloWorld')
                  .setTextStyle(0, 5, bold)
                  .setTextStyle(italic)
                  .build();

Parameters

NameTypeDescription
textStyleTextStyleThe text style being set.

Return

RichTextValueBuilder — This builder, for chaining.