Word.TableRow class

Represents a row in a Word document.

Extends

Remarks

[ API set: WordApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-formatting.yaml

// Gets content alignment details about the first cell of the first table in the document.
await Word.run(async (context) => {
  const firstTable: Word.Table = context.document.body.tables.getFirst();
  const firstTableRow: Word.TableRow = firstTable.rows.getFirst();
  const firstCell: Word.TableCell = firstTableRow.cells.getFirst();
  firstCell.load(["horizontalAlignment", "verticalAlignment"]);
  await context.sync();

  console.log(`Details about the alignment of the first table's first cell:`, `- Horizontal alignment of the cell's content: ${firstCell.horizontalAlignment}`, `- Vertical alignment of the cell's content: ${firstCell.verticalAlignment}`);
});

Properties

cellCount

Gets the number of cells in the row.

cells

Gets cells.

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.

horizontalAlignment

Specifies the horizontal alignment of every cell in the row. The value can be 'Left', 'Centered', 'Right', or 'Justified'.

isHeader

Checks whether the row is a header row. To set the number of header rows, use headerRowCount on the Table object.

parentTable

Gets parent table.

preferredHeight

Specifies the preferred height of the row in points.

rowIndex

Gets the index of the row in its parent table.

shadingColor

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.

verticalAlignment

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.

getBorder(borderLocation)

Gets the border style of the cells in the row.

getBorder(borderLocationString)

Gets the border style of the cells in the row.

getCellPadding(cellPaddingLocation)

Gets cell padding in points.

getCellPadding(cellPaddingLocationString)

Gets cell padding in points.

getNext()

Gets the next row. Throws an ItemNotFound error if this row is the last one.

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.

insertRows(insertLocation, rowCount, values)

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 context.sync() before reading the properties.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

merge()

Merges the row into one cell.

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.

select(selectionMode)

Selects the row and navigates the Word UI to it.

select(selectionModeString)

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.

setCellPadding(cellPaddingLocation, cellPadding)

Sets cell padding in points.

setCellPadding(cellPaddingLocationString, cellPadding)

Sets cell padding in points.

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's 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.

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.

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.

Property Details

cellCount

Gets the number of cells in the row.

readonly cellCount: number;

Property Value

number

Remarks

[ API set: WordApi 1.3 ]

cells

Gets cells.

readonly cells: Word.TableCellCollection;

Property Value

Remarks

[ API set: WordApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-formatting.yaml

// Gets content alignment details about the first cell of the first table in the document.
await Word.run(async (context) => {
  const firstTable: Word.Table = context.document.body.tables.getFirst();
  const firstTableRow: Word.TableRow = firstTable.rows.getFirst();
  const firstCell: Word.TableCell = firstTableRow.cells.getFirst();
  firstCell.load(["horizontalAlignment", "verticalAlignment"]);
  await context.sync();

  console.log(`Details about the alignment of the first table's first cell:`, `- Horizontal alignment of the cell's content: ${firstCell.horizontalAlignment}`, `- Vertical alignment of the cell's content: ${firstCell.verticalAlignment}`);
});

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

[ API set: WordApi 1.5 ]

fields

Gets the collection of field objects in the table row.

readonly fields: Word.FieldCollection;

Property Value

Remarks

[ API set: WordApi 1.4 ]

font

Gets the font. Use this to get and set font name, size, color, and other properties.

readonly font: Word.Font;

Property Value

Remarks

[ API set: WordApi 1.3 ]

footnotes

Gets the collection of footnotes in the table row.

readonly footnotes: Word.NoteItemCollection;

Property Value

Remarks

[ API set: WordApi 1.5 ]

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

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

parentTable

Gets parent table.

readonly parentTable: Word.Table;

Property Value

Remarks

[ API set: WordApi 1.3 ]

preferredHeight

Specifies the preferred height of the row in points.

preferredHeight: number;

Property Value

number

Remarks

[ API set: WordApi 1.3 ]

rowIndex

Gets the index of the row in its parent table.

readonly rowIndex: number;

Property Value

number

Remarks

[ API set: WordApi 1.3 ]

shadingColor

Specifies the shading color. Color is specified in "#RRGGBB" format or by using the color name.

shadingColor: string;

Property Value

string

Remarks

[ API set: WordApi 1.3 ]

values

Specifies the text values in the row, as a 2D JavaScript array.

values: string[][];

Property Value

string[][]

Remarks

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

Method Details

clear()

Clears the contents of the row.

clear(): void;

Returns

void

Remarks

[ API set: WordApi 1.3 ]

delete()

Deletes the entire row.

delete(): void;

Returns

void

Remarks

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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: Word.Table = context.document.body.tables.getFirst();
  const firstTableRow: Word.TableRow = firstTable.rows.getFirst();
  const borderLocation = Word.BorderLocation.bottom;
  const border: Word.TableBorder = 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:`, `- Color: ${border.color}`, `- Type: ${border.type}`, `- 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

[ API set: WordApi 1.3 ]

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

Remarks

[ API set: WordApi 1.3 ]

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: Word.Table = context.document.body.tables.getFirst();
  const firstTableRow: Word.TableRow = 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

Remarks

[ API set: WordApi 1.3 ]

getNext()

Gets the next row. Throws an ItemNotFound error if this row is the last one.

getNext(): Word.TableRow;

Returns

Remarks

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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

insertLocation

before | after | "Before" | "After"

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

[ API set: WordApi 1.3 ]

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

options
Word.Interfaces.TableRowLoadOptions

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

[ API set: WordApi 1.4 ]

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

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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

[ API set: WordApi 1.3 ]

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's 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