Word.TableRow class
Represents a row in a Word document.
- Extends
Remarks
Properties
| cell |
Gets the number of cells in the row. |
| cells | Gets cells. Read-only. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| endnotes | Gets the collection of endnotes in the table row. |
| fields | Gets the collection of field objects in the table row. |
| font | Gets the font. Use this to get and set font name, size, color, and other properties. |
| footnotes | Gets the collection of footnotes in the table row. |
| horizontal |
Specifies the horizontal alignment of every cell in the row. The value can be 'Left', 'Centered', 'Right', or 'Justified'. |
| is |
Checks whether the row is a header row. To set the number of header rows, use |
| parent |
Gets parent table. |
| preferred |
Specifies the preferred height of the row in points. |
| row |
Gets the index of the row in its parent table. |
| shading |
Specifies the shading color. Color is specified in "#RRGGBB" format or by using the color name. |
| values | Specifies the text values in the row, as a 2D JavaScript array. |
| vertical |
Specifies the vertical alignment of the cells in the row. The value can be 'Top', 'Center', or 'Bottom'. |
Methods
| clear() | Clears the contents of the row. |
| delete() | Deletes the entire row. |
| get |
Gets the border style of the cells in the row. |
| get |
Gets the border style of the cells in the row. |
| get |
Gets cell padding in points. |
| get |
Gets cell padding in points. |
| get |
Gets the next row. Throws an |
| get |
Gets the next row. If this row is the last one, then this method will return an object with its |
| insert |
Inserts a content control on the row. |
| insert |
Inserts rows using this row as a template. If values are specified, inserts the values into the new rows. |
| 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 |
| merge() | Merges the row into one cell. |
| search(search |
Performs a search with the specified SearchOptions on the scope of the row. The search results are a collection of range objects. |
| select(selection |
Selects the row and navigates the Word UI to it. |
| select(selection |
Selects the row and navigates the Word UI to it. |
| set(properties, options) | Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type. |
| set(properties) | Sets multiple properties on the object at the same time, based on an existing loaded object. |
| set |
Sets cell padding in points. |
| set |
Sets cell padding in points. |
| toJSON() | Overrides the JavaScript |
| track() | Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across |
| untrack() | Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call |
Property Details
cellCount
Gets the number of cells in the row.
readonly cellCount: number;Property Value
number
Remarks
cells
Gets cells. Read-only.
readonly cells: Word.TableCellCollection;Property Value
Remarks
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
endnotes
Gets the collection of endnotes in the table row.
readonly endnotes: Word.NoteItemCollection;Property Value
Remarks
fields
Gets the collection of field objects in the table row.
readonly fields: Word.FieldCollection;Property Value
Remarks
font
Gets the font. Use this to get and set font name, size, color, and other properties.
readonly font: Word.Font;Property Value
Remarks
footnotes
Gets the collection of footnotes in the table row.
readonly footnotes: Word.NoteItemCollection;Property Value
Remarks
horizontalAlignment
Specifies the horizontal alignment of every cell in the row. The value can be 'Left', 'Centered', 'Right', or 'Justified'.
horizontalAlignment: Word.Alignment | "Mixed" | "Unknown" | "Left" | "Centered" | "Right" | "Justified";Property Value
Word.Alignment | "Mixed" | "Unknown" | "Left" | "Centered" | "Right" | "Justified"
Remarks
isHeader
Checks whether the row is a header row. To set the number of header rows, use headerRowCount on the Table object.
readonly isHeader: boolean;Property Value
boolean
Remarks
parentTable
Gets parent table.
readonly parentTable: Word.Table;Property Value
Remarks
preferredHeight
Specifies the preferred height of the row in points.
preferredHeight: number;Property Value
number
Remarks
rowIndex
Gets the index of the row in its parent table.
readonly rowIndex: number;Property Value
number
Remarks
shadingColor
Specifies the shading color. Color is specified in "#RRGGBB" format or by using the color name.
shadingColor: string;Property Value
string
Remarks
values
Specifies the text values in the row, as a 2D JavaScript array.
values: string[][];Property Value
string[][]
Remarks
verticalAlignment
Specifies the vertical alignment of the cells in the row. The value can be 'Top', 'Center', or 'Bottom'.
verticalAlignment: Word.VerticalAlignment | "Mixed" | "Top" | "Center" | "Bottom";Property Value
Word.VerticalAlignment | "Mixed" | "Top" | "Center" | "Bottom"
Remarks
Method Details
clear()
delete()
getBorder(borderLocation)
Gets the border style of the cells in the row.
getBorder(borderLocation: Word.BorderLocation): Word.TableBorder;Parameters
- borderLocation
- Word.BorderLocation
Required. The border location.
Returns
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-formatting.yaml
// Gets border details about the first row of the first table in the document.
await Word.run(async (context) => {
const firstTable = context.document.body.tables.getFirst();
const firstTableRow = firstTable.rows.getFirst();
const borderLocation = Word.BorderLocation.bottom;
const border = firstTableRow.getBorder(borderLocation);
border.load(["type", "color", "width"]);
await context.sync();
console.log(`Details about the ${borderLocation} border of the first table's first row:`);
console.log(`- Color: ${border.color}`);
console.log(`- Type: ${border.type}`);
console.log(`- Width: ${border.width} points`);
});
getBorder(borderLocationString)
Gets the border style of the cells in the row.
getBorder(borderLocationString: "Top" | "Left" | "Bottom" | "Right" | "InsideHorizontal" | "InsideVertical" | "Inside" | "Outside" | "All"): Word.TableBorder;Parameters
- borderLocationString
-
"Top" | "Left" | "Bottom" | "Right" | "InsideHorizontal" | "InsideVertical" | "Inside" | "Outside" | "All"
Required. The border location.
Returns
Remarks
getCellPadding(cellPaddingLocation)
Gets cell padding in points.
getCellPadding(cellPaddingLocation: Word.CellPaddingLocation): OfficeExtension.ClientResult<number>;Parameters
- cellPaddingLocation
- Word.CellPaddingLocation
Required. The cell padding location must be 'Top', 'Left', 'Bottom', or 'Right'.
Returns
OfficeExtension.ClientResult<number>
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-formatting.yaml
// Gets cell padding details about the first row of the first table in the document.
await Word.run(async (context) => {
const firstTable = context.document.body.tables.getFirst();
const firstTableRow = firstTable.rows.getFirst();
const cellPaddingLocation = Word.CellPaddingLocation.bottom;
const cellPadding = firstTableRow.getCellPadding(cellPaddingLocation);
await context.sync();
console.log(
`Cell padding details about the ${cellPaddingLocation} border of the first table's first row: ${cellPadding.value} points`
);
});
getCellPadding(cellPaddingLocationString)
Gets cell padding in points.
getCellPadding(cellPaddingLocationString: "Top" | "Left" | "Bottom" | "Right"): OfficeExtension.ClientResult<number>;Parameters
- cellPaddingLocationString
-
"Top" | "Left" | "Bottom" | "Right"
Required. The cell padding location must be 'Top', 'Left', 'Bottom', or 'Right'.
Returns
OfficeExtension.ClientResult<number>
Remarks
getNext()
Gets the next row. Throws an ItemNotFound error if this row is the last one.
getNext(): Word.TableRow;Returns
Remarks
getNextOrNullObject()
Gets the next row. If this row is the last one, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getNextOrNullObject(): Word.TableRow;Returns
Remarks
insertContentControl()
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Inserts a content control on the row.
insertContentControl(): Word.ContentControl;Returns
Remarks
insertRows(insertLocation, rowCount, values)
Inserts rows using this row as a template. If values are specified, inserts the values into the new rows.
insertRows(insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After", rowCount: number, values?: string[][]): Word.TableRowCollection;Parameters
Required. Where the new rows should be inserted, relative to the current row. It must be 'Before' or 'After'.
- rowCount
-
number
Required. Number of rows to add
- values
-
string[][]
Optional. Strings to insert in the new rows, specified as a 2D array. The number of cells in each row must not exceed the number of cells in the existing row.
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?: Word.Interfaces.TableRowLoadOptions): Word.TableRow;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[]): Word.TableRow;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;
}): Word.TableRow;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
merge()
Merges the row into one cell.
merge(): Word.TableCell;Returns
Remarks
search(searchText, searchOptions)
Performs a search with the specified SearchOptions on the scope of the row. The search results are a collection of range objects.
search(searchText: string, searchOptions?: Word.SearchOptions | {
ignorePunct?: boolean;
ignoreSpace?: boolean;
matchCase?: boolean;
matchPrefix?: boolean;
matchSuffix?: boolean;
matchWholeWord?: boolean;
matchWildcards?: boolean;
}): Word.RangeCollection;Parameters
- searchText
-
string
Required. The search text.
- searchOptions
-
Word.SearchOptions | { ignorePunct?: boolean; ignoreSpace?: boolean; matchCase?: boolean; matchPrefix?: boolean; matchSuffix?: boolean; matchWholeWord?: boolean; matchWildcards?: boolean; }
Optional. Options for the search.
Returns
Remarks
select(selectionMode)
Selects the row and navigates the Word UI to it.
select(selectionMode?: Word.SelectionMode): void;Parameters
- selectionMode
- Word.SelectionMode
Optional. The selection mode must be 'Select', 'Start', or 'End'. 'Select' is the default.
Returns
void
Remarks
select(selectionModeString)
Selects the row and navigates the Word UI to it.
select(selectionModeString?: "Select" | "Start" | "End"): void;Parameters
- selectionModeString
-
"Select" | "Start" | "End"
Optional. The selection mode must be 'Select', 'Start', or 'End'. 'Select' is the default.
Returns
void
Remarks
set(properties, options)
Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties: Interfaces.TableRowUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Word.Interfaces.TableRowUpdateData
A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.
- options
- OfficeExtension.UpdateOptions
Provides an option to suppress errors if the properties object tries to set any read-only properties.
Returns
void
set(properties)
Sets multiple properties on the object at the same time, based on an existing loaded object.
set(properties: Word.TableRow): void;Parameters
- properties
- Word.TableRow
Returns
void
setCellPadding(cellPaddingLocation, cellPadding)
Sets cell padding in points.
setCellPadding(cellPaddingLocation: Word.CellPaddingLocation, cellPadding: number): void;Parameters
- cellPaddingLocation
- Word.CellPaddingLocation
Required. The cell padding location must be 'Top', 'Left', 'Bottom', or 'Right'.
- cellPadding
-
number
Required. The cell padding.
Returns
void
Remarks
setCellPadding(cellPaddingLocationString, cellPadding)
Sets cell padding in points.
setCellPadding(cellPaddingLocationString: "Top" | "Left" | "Bottom" | "Right", cellPadding: number): void;Parameters
- cellPaddingLocationString
-
"Top" | "Left" | "Bottom" | "Right"
Required. The cell padding location must be 'Top', 'Left', 'Bottom', or 'Right'.
- cellPadding
-
number
Required. The cell padding.
Returns
void
Remarks
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 Word.TableRow object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.TableRowData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Word.Interfaces.TableRowData;Returns
track()
Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.
track(): Word.TableRow;Returns
untrack()
Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.
untrack(): Word.TableRow;Returns
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for