Word.TableCell class
Represents a table cell in a Word document.
- Extends
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/table-cell-access.yaml
// Gets the content of the first cell in the first table.
await Word.run(async (context) => {
const firstCell = context.document.body.tables.getFirst().getCell(0, 0).body;
firstCell.load("text");
await context.sync();
console.log("First cell's text is: " + firstCell.text);
});
Properties
| body | Gets the body object of the cell. |
| cell |
Gets the index of the cell in its row. |
| column |
Specifies the width of the cell's column in points. This is applicable to uniform tables. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| horizontal |
Specifies the horizontal alignment of the cell. The value can be 'Left', 'Centered', 'Right', or 'Justified'. |
| parent |
Gets the parent row of the cell. |
| parent |
Gets the parent table of the cell. |
| row |
Gets the index of the cell's row in the table. |
| shading |
Specifies the shading color of the cell. Color is specified in "#RRGGBB" format or by using the color name. |
| value | Specifies the text of the cell. |
| vertical |
Specifies the vertical alignment of the cell. The value can be 'Top', 'Center', or 'Bottom'. |
| width | Gets the width of the cell in points. |
Methods
| delete |
Deletes the column containing this cell. This is applicable to uniform tables. |
| delete |
Deletes the row containing this cell. |
| get |
Gets the border style for the specified border. |
| get |
Gets the border style for the specified border. |
| get |
Gets cell padding in points. |
| get |
Gets cell padding in points. |
| get |
Gets the next cell. Throws an |
| get |
Gets the next cell. If this cell is the last one, then this method will return an object with its |
| insert |
Adds columns to the left or right of the cell, using the cell's column as a template. This is applicable to uniform tables. The string values, if specified, are set in the newly inserted rows. |
| insert |
Inserts rows above or below the cell, using the cell's row as a template. The string values, if specified, are set in the newly inserted 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 |
| 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. |
| split(row |
Splits the cell into the specified number of rows and columns. |
| 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
body
Gets the body object of the cell.
readonly body: Word.Body;Property Value
Remarks
cellIndex
Gets the index of the cell in its row.
readonly cellIndex: number;Property Value
number
Remarks
columnWidth
Specifies the width of the cell's column in points. This is applicable to uniform tables.
columnWidth: number;Property Value
number
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
horizontalAlignment
Specifies the horizontal alignment of the cell. 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
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 = context.document.body.tables.getFirst();
const firstCell = firstTable.getCell(0, 0);
firstCell.load(["horizontalAlignment", "verticalAlignment"]);
await context.sync();
console.log(`Details about the alignment of the first table's first cell:`);
console.log(`- Horizontal alignment of the cell's content: ${firstCell.horizontalAlignment}`);
console.log(`- Vertical alignment of the cell's content: ${firstCell.verticalAlignment}`);
});
parentRow
Gets the parent row of the cell.
readonly parentRow: Word.TableRow;Property Value
Remarks
parentTable
Gets the parent table of the cell.
readonly parentTable: Word.Table;Property Value
Remarks
rowIndex
Gets the index of the cell's row in the table.
readonly rowIndex: number;Property Value
number
Remarks
shadingColor
Specifies the shading color of the cell. Color is specified in "#RRGGBB" format or by using the color name.
shadingColor: string;Property Value
string
Remarks
value
Specifies the text of the cell.
value: string;Property Value
string
Remarks
verticalAlignment
Specifies the vertical alignment of the cell. The value can be 'Top', 'Center', or 'Bottom'.
verticalAlignment: Word.VerticalAlignment | "Mixed" | "Top" | "Center" | "Bottom";Property Value
Word.VerticalAlignment | "Mixed" | "Top" | "Center" | "Bottom"
Remarks
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 = context.document.body.tables.getFirst();
const firstCell = firstTable.getCell(0, 0);
firstCell.load(["horizontalAlignment", "verticalAlignment"]);
await context.sync();
console.log(`Details about the alignment of the first table's first cell:`);
console.log(`- Horizontal alignment of the cell's content: ${firstCell.horizontalAlignment}`);
console.log(`- Vertical alignment of the cell's content: ${firstCell.verticalAlignment}`);
});
width
Gets the width of the cell in points.
readonly width: number;Property Value
number
Remarks
Method Details
deleteColumn()
Deletes the column containing this cell. This is applicable to uniform tables.
deleteColumn(): void;Returns
void
Remarks
deleteRow()
Deletes the row containing this cell.
deleteRow(): void;Returns
void
Remarks
getBorder(borderLocation)
Gets the border style for the specified border.
getBorder(borderLocation: Word.BorderLocation): Word.TableBorder;Parameters
- borderLocation
- Word.BorderLocation
Required. The border location.
Returns
Remarks
getBorder(borderLocationString)
Gets the border style for the specified border.
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
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 of the first table in the document.
await Word.run(async (context) => {
const firstTable = context.document.body.tables.getFirst();
const firstCell = firstTable.getCell(0, 0);
const borderLocation = "Left";
const border = firstCell.getBorder(borderLocation);
border.load(["type", "color", "width"]);
await context.sync();
console.log(`Details about the ${borderLocation} border of the first table's first cell:`);
console.log(`- Color: ${border.color}`);
console.log(`- Type: ${border.type}`);
console.log(`- Width: ${border.width} points`);
});
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
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
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 cell of the first table in the document.
await Word.run(async (context) => {
const firstTable = context.document.body.tables.getFirst();
const firstCell = firstTable.getCell(0, 0);
const cellPaddingLocation = "Left";
const cellPadding = firstCell.getCellPadding(cellPaddingLocation);
await context.sync();
console.log(
`Cell padding details about the ${cellPaddingLocation} border of the first table's first cell: ${cellPadding.value} points`
);
});
getNext()
Gets the next cell. Throws an ItemNotFound error if this cell is the last one.
getNext(): Word.TableCell;Returns
Remarks
getNextOrNullObject()
Gets the next cell. If this cell 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.TableCell;Returns
Remarks
insertColumns(insertLocation, columnCount, values)
Adds columns to the left or right of the cell, using the cell's column as a template. This is applicable to uniform tables. The string values, if specified, are set in the newly inserted rows.
insertColumns(insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After", columnCount: number, values?: string[][]): void;Parameters
- columnCount
-
number
Required. Number of columns to add.
- values
-
string[][]
Optional 2D array. Cells are filled if the corresponding strings are specified in the array.
Returns
void
Remarks
insertRows(insertLocation, rowCount, values)
Inserts rows above or below the cell, using the cell's row as a template. The string values, if specified, are set in the newly inserted rows.
insertRows(insertLocation: Word.InsertLocation.before | Word.InsertLocation.after | "Before" | "After", rowCount: number, values?: string[][]): Word.TableRowCollection;Parameters
- rowCount
-
number
Required. Number of rows to add.
- values
-
string[][]
Optional 2D array. Cells are filled if the corresponding strings are specified in the array.
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.TableCellLoadOptions): Word.TableCell;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.TableCell;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.TableCell;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
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.TableCellUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Word.Interfaces.TableCellUpdateData
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.TableCell): void;Parameters
- properties
- Word.TableCell
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
split(rowCount, columnCount)
Splits the cell into the specified number of rows and columns.
split(rowCount: number, columnCount: number): void;Parameters
- rowCount
-
number
Required. The number of rows to split into. Must be a divisor of the number of underlying rows.
- columnCount
-
number
Required. The number of columns to split into.
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.TableCell object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.TableCellData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Word.Interfaces.TableCellData;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.TableCell;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.TableCell;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