Skip to main content

getStyledTextSegments

Get text segments along with the desired text properties (font size, text case, etc...)

Supported On:

Signature

getStyledTextSegments<StyledTextSegmentFields extends (keyof Omit< StyledTextSegment, 'characters' | 'start' | 'end' >)[]>(fields: StyledTextSegmentFields, start?: number, end?: number): Array<Pick<StyledTextSegment, StyledTextSegmentFields[number] | 'characters' | 'start' | 'end'>>

Parameters

fields

An array of text properties. Any text property that can apply to specific character ranges is supported:

  • fontSize
  • fontName
  • fontWeight
  • textDecoration
  • textCase
  • lineHeight
  • letterSpacing
  • fills
  • textStyleId
  • fillStyleId
  • listOptions
  • indentation
  • hyperlink

start

An optional start index for the characters to retrieve

end

An optional end index (required if start is provided)

Remarks

This function provides an easy and performant way to get multiple text properties which may have mixed values, along with which characters these values apply to. It will return an array of StyledTextSegments containing the desired fields, along with the characters and their start and end index.

To illustrate the behavior of this function, here are a few examples:

Node containing "hello world":

textNode.getStyledTextSegments(['fontName'])

// Output: contains 2 segments because the text is no longer bolded after "hello"
[
  {
    characters: "hello",
    start: 0,
    end: 5,
    fontName: { family: 'Inter', style: 'Bold' },
  },
  {
    characters: " world",
    start: 5,
    end: 11,
    fontName: { family: 'Inter', style: 'Regular' },
  }
]

Node containing:

  • Item 1
    • Item 1.1
textNode.getStyledTextSegments(['fontName', 'indentation'])

// Output: contains 3 segments because the font / indentation changes
// before and after the second "Item"
[
  {
    characters: 'Item 1\n',
    start: 0,
    end: 7,
    fontName: { family: 'Inter', style: 'Regular' },
    indentation: 1
  },
  {
    characters: 'Item',
    start: 7,
    end: 11,
    fontName: { family: 'Inter', style: 'Bold' },
    indentation: 2
  },
  {
    characters: ' 1.1',
    start: 11,
    end: 15,
    fontName: { family: 'Inter', style: 'Regular' },
    indentation: 2
  }
]

Node containing "馃榿 馃槶 馃槄馃槀馃槼馃槑":

textNode.getStyledTextSegments(['letterSpacing'])

// Output: many emoji have length 2 in Javascript
[
  {
    characters: '馃榿馃槶',
    start: 0,
    end: 4,
    letterSpacing: { unit: 'PERCENT', value: 50 }
  },
  {
    characters: '馃槄馃槀馃槼馃槑',
    start: 4,
    end: 12,
    letterSpacing: { unit: 'PERCENT', value: 0 }
  }
]

textNode.getStyledTextSegments(['letterSpacing'], 1, 3)

// Output: if the requested range starts or ends in the middle
// of surrogate pairs, those pairs will be trimmed and you will
// see raw Unicode code points
[
  {
    characters: '\uDE01\uD83D',
    start: 1,
    end: 3,
    letterSpacing: { unit: 'PERCENT', value: 50 }
  }
]

textNode.getStyledTextSegments(['letterSpacing'], 3, 5)

// Output: similar to above, but Unicode code points span
// a change in letter spacing
[
  {
    characters: '\uDE2D',
    start: 3,
    end: 4,
    letterSpacing: { unit: 'PERCENT', value: 50 }
  },
  {
    characters: '\uD83D',
    start: 4,
    end: 5,
    letterSpacing: { unit: 'PERCENT', value: 0 }
  }
]

See insertCharacters for more information on surrogate pairs.

On this page