PowerPoint.TextRange class
Contains the text that is attached to a shape, in addition to properties and methods for manipulating the text.
- Extends
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/text/get-set-textrange.yaml
// Sets the color of the selected text range to green.
await PowerPoint.run(async (context) => {
const textRange: PowerPoint.TextRange = context.presentation.getSelectedTextRange();
textRange.font.color = "green";
await context.sync();
});
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| font | Returns a |
| length | Gets or sets the length of the range that this |
| paragraph |
Represents the paragraph format of the text range. See PowerPoint.ParagraphFormat for details. |
| start | Gets or sets zero-based index, relative to the parent text frame, for the starting position of the range that this |
| text | Represents the plain text content of the text range. |
Methods
| get |
Returns the parent PowerPoint.TextFrame object that holds this |
| get |
Returns a |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| set |
Selects this |
| toJSON() | Overrides the JavaScript |
Property Details
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
font
Returns a ShapeFont object that represents the font attributes for the text range.
readonly font: PowerPoint.ShapeFont;Property Value
Remarks
[ API set: PowerPointApi 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/text/get-set-textrange.yaml
// Sets the color of the selected text range to green.
await PowerPoint.run(async (context) => {
const textRange: PowerPoint.TextRange = context.presentation.getSelectedTextRange();
textRange.font.color = "green";
await context.sync();
});
length
Gets or sets the length of the range that this TextRange represents. Throws an InvalidArgument exception when set with a negative value or if the value is greater than the length of the available text from the starting point.
length: number;Property Value
number
Remarks
paragraphFormat
Represents the paragraph format of the text range. See PowerPoint.ParagraphFormat for details.
readonly paragraphFormat: PowerPoint.ParagraphFormat;Property Value
Remarks
start
Gets or sets zero-based index, relative to the parent text frame, for the starting position of the range that this TextRange represents. Throws an InvalidArgument exception when set with a negative value or if the value is greater than the length of the text.
start: number;Property Value
number
Remarks
text
Represents the plain text content of the text range.
text: string;Property Value
string
Remarks
Method Details
getParentTextFrame()
Returns the parent PowerPoint.TextFrame object that holds this TextRange.
getParentTextFrame(): PowerPoint.TextFrame;Returns
Remarks
getSubstring(start, length)
Returns a TextRange object for the substring in the given range.
getSubstring(start: number, length?: number): PowerPoint.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
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: PowerPoint.Interfaces.TextRangeLoadOptions): PowerPoint.TextRange;Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): PowerPoint.TextRange;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): PowerPoint.TextRange;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
setSelected()
Selects this TextRange in the current view.
setSelected(): void;Returns
void
Remarks
[ API set: PowerPointApi 1.5 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/text/get-set-textrange.yaml
// Selects the first 10 characters of the selected shape.
await PowerPoint.run(async (context) => {
const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
const shapeCount = shapes.getCount();
await context.sync();
if (shapeCount.value !== 1) {
console.warn("You must select only one shape with text in it.");
return;
}
const shape: PowerPoint.Shape = shapes.getItemAt(0);
const textFrame: PowerPoint.TextFrame = shape.textFrame.load("textRange,hasText");
await context.sync();
if (textFrame.hasText != true) {
console.warn("You must select only one shape with text in it.");
return;
}
const textRange: PowerPoint.TextRange = textFrame.textRange;
textRange.load("text");
await context.sync();
if (textRange.text.length < 10) {
console.warn("You must select only one shape with at least 10 characters in it.");
return;
}
const textRange10 = textRange.getSubstring(0, 10);
textRange10.setSelected();
await context.sync();
});
...
// Sets the range selection to the range that was saved previously.
await PowerPoint.run(async (context) => {
const slide1: PowerPoint.Slide = context.presentation.slides.getItem(savedTextSlideSelection[0]);
const shape1: PowerPoint.Shape = slide1.shapes.getItem(savedTextShapeSelection[0]);
const textRange: PowerPoint.TextRange = shape1.textFrame.textRange.getSubstring(savedTextTextRangeStart, savedTextTextRangeLength);
textRange.setSelected();
await context.sync();
});
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original PowerPoint.TextRange object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.TextRangeData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): PowerPoint.Interfaces.TextRangeData;Returns
Office Add-ins