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));
        }
});
quot;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));
        }
});