RangeFormat Object (JavaScript API for Excel)
A format object encapsulating the range's font, fill, borders, alignment, and other properties.
Properties
| Property | Type | Description | Req. Set |
|---|---|---|---|
| columnWidth | double | Gets or sets the width of all colums within the range. If the column widths are not uniform, null will be returned. | 1.2 |
| horizontalAlignment | string | Represents the horizontal alignment for the specified object. Possible values are: General, Left, Center, Right, Fill, Justify, CenterAcrossSelection, Distributed. | 1.1 |
| rowHeight | double | Gets or sets the height of all rows in the range. If the row heights are not uniform null will be returned. | 1.2 |
| verticalAlignment | string | Represents the vertical alignment for the specified object. Possible values are: Top, Center, Bottom, Justify, Distributed. | 1.1 |
| wrapText | bool | Indicates if Excel wraps the text in the object. A null value indicates that the entire range doesn't have uniform wrap setting | 1.1 |
See property access examples.
Relationships
| Relationship | Type | Description | Req. Set |
|---|---|---|---|
| borders | RangeBorderCollection | Collection of border objects that apply to the overall range. Read-only. | 1.1 |
| fill | RangeFill | Returns the fill object defined on the overall range. Read-only. | 1.1 |
| font | RangeFont | Returns the font object defined on the overall range. Read-only. | 1.1 |
| protection | FormatProtection | Returns the format protection object for a range. Read-only. | 1.2 |
Methods
| Method | Return Type | Description | Req. Set |
|---|---|---|---|
| autofitColumns() | void | Changes the width of the columns of the current range to achieve the best fit, based on the current data in the columns. | 1.2 |
| autofitRows() | void | Changes the height of the rows of the current range to achieve the best fit, based on the current data in the columns. | 1.2 |
Method Details
autofitColumns()
Changes the width of the columns of the current range to achieve the best fit, based on the current data in the columns.
Syntax
rangeFormatObject.autofitColumns();
Parameters
None
Returns
void
autofitRows()
Changes the height of the rows of the current range to achieve the best fit, based on the current data in the columns.
Syntax
rangeFormatObject.autofitRows();
Parameters
None
Returns
void
Property access examples
Below example selects all of the Range's format properties.
Excel.run(function (ctx) {
var sheetName = "Sheet1";
var rangeAddress = "F:G";
var worksheet = ctx.workbook.worksheets.getItem(sheetName);
var range = worksheet.getRange(rangeAddress);
range.load(["format/*", "format/fill", "format/borders", "format/font"]);
return ctx.sync().then(function() {
console.log(range.format.wrapText);
console.log(range.format.fill.color);
console.log(range.format.font.name);
});
}).catch(function(error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});
The example below sets font name, fill color and wraps text.
Excel.run(function (ctx) {
var sheetName = "Sheet1";
var rangeAddress = "F:G";
var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
range.format.wrapText = true;
range.format.font.name = 'Times New Roman';
range.format.fill.color = '0000FF';
return ctx.sync();
}).catch(function(error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});
The example below adds grid border around the range.
Excel.run(function (ctx) {
var sheetName = "Sheet1";
var rangeAddress = "F:G";
var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
range.format.borders.getItem('InsideHorizontal').style = 'Continuous';
range.format.borders.getItem('InsideVertical').style = 'Continuous';
range.format.borders.getItem('EdgeBottom').style = 'Continuous';
range.format.borders.getItem('EdgeLeft').style = 'Continuous';
range.format.borders.getItem('EdgeRight').style = 'Continuous';
range.format.borders.getItem('EdgeTop').style = 'Continuous';
return ctx.sync();
}).catch(function(error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});