ExcelScript.TextRange interface

Package:

ExcelScript

Contains the text that is attached to a shape, in addition to properties and methods for manipulating the text.

Remarks

Examples

/**
 * This script adds text to a shape.
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a hexagon shape in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const hexagon = sheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the text of the shape.
  const hexText: ExcelScript.TextRange = hexagon.getTextFrame().getTextRange();
  hexText.setText("Forest");
}

Methods

getFont()	Returns a ShapeFont object that represents the font attributes for the text range.
getSubstring(start, length)	Returns a TextRange object for the substring in the given range.
getText()	Represents the plain text content of the text range.
setText(text)	Represents the plain text content of the text range.

Method Details

getFont()

Returns a ShapeFont object that represents the font attributes for the text range.

getFont(): ShapeFont;

Returns

ExcelScript.ShapeFont

Examples

/**
 * This sample sets the font of a shape to be bold. 
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first shape in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const shape = sheet.getShapes()[0];

  // Get the text font from the shape.
  const text: ExcelScript.TextRange = shape.getTextFrame().getTextRange();
  const shapeTextFont: ExcelScript.ShapeFont = text.getFont();

  // Set the font to be bold.
  shapeTextFont.setBold(true);
}

getSubstring(start, length)

Returns a TextRange object for the substring in the given range.

getSubstring(start: number, length?: number): TextRange;

Parameters

start

number

The zero-based index of the first character to get from the text range.

length

number

Optional. The number of characters to be returned in the new text range. If length is omitted, all the characters from start to the end of the text range's last paragraph will be returned.

Returns

ExcelScript.TextRange

getText()

Represents the plain text content of the text range.

getText(): string;

Returns

string

Examples

/**
 * This script writes all the text from the workbook's geometric shapes in a new worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a new worksheet.
  const shapeTextSheet = workbook.addWorksheet("ShapeText");
  let shapeTextValues: string[][] = [];

  // Get the text from every geometric shape in every worksheet.
  workbook.getWorksheets().forEach((sheet) => {
    sheet.getShapes().forEach((shape) => {
      if (shape.getType() === ExcelScript.ShapeType.geometricShape)
      shapeTextValues.push([
        sheet.getName(),
        shape.getGeometricShapeType().toString(),
        shape.getTextFrame().getTextRange().getText()]);
    });
  });

  // Add the text to the new worksheet.
  const range = shapeTextSheet.getRangeByIndexes(
    0,
    0, 
    shapeTextValues.length, 
    shapeTextValues[0].length);
  range.setValues(shapeTextValues);
}

setText(text)

Represents the plain text content of the text range.

setText(text: string): void;

Parameters

text

string

Returns

void