Chart Object (JavaScript API for Excel)

Represents a chart object in a workbook.

Properties

Property Type Description Req. Set
height double Represents the height, in points, of the chart object. 1.1
id string Gets a chart based on its position in the collection. Read-only. 1.2
left double The distance, in points, from the left side of the chart to the worksheet origin. 1.1
name string Represents the name of a chart object. 1.1
top double Represents the distance, in points, from the top edge of the object to the top of row 1 (on a worksheet) or the top of the chart area (on a chart). 1.1
width double Represents the width, in points, of the chart object. 1.1

See property access examples.

Relationships

Relationship Type Description Req. Set
axes ChartAxes Represents chart axes. Read-only. 1.1
dataLabels ChartDataLabels Represents the datalabels on the chart. Read-only. 1.1
format ChartAreaFormat Encapsulates the format properties for the chart area. Read-only. 1.1
legend ChartLegend Represents the legend for the chart. Read-only. 1.1
series ChartSeriesCollection Represents either a single series or collection of series in the chart. Read-only. 1.1
title ChartTitle Represents the title of the specified chart, including the text, visibility, position and formating of the title. Read-only. 1.1
worksheet Worksheet The worksheet containing the current chart. Read-only. 1.2

Methods

Method Return Type Description Req. Set
delete() void Deletes the chart object. 1.1
getImage(height: number, width: number, fittingMode: string) System.IO.Stream Renders the chart as a base64-encoded image by scaling the chart to fit the specified dimensions. 1.2
setData(sourceData: object, seriesBy: string) void Resets the source data for the chart. 1.1
setPosition(startCell: object, endCell: object) void Positions the chart relative to cells on the worksheet. 1.1

Method Details

delete()

Deletes the chart object.

Syntax

chartObject.delete();

Parameters

None

Returns

void

Examples

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.delete();
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

getImage(height: number, width: number, fittingMode: string)

Renders the chart as a base64-encoded image by scaling the chart to fit the specified dimensions.

Syntax

chartObject.getImage(height, width, fittingMode);

Parameters

Parameter Type Description
height number Optional. (Optional) The desired height of the resulting image.
width number Optional. (Optional) The desired width of the resulting image.
fittingMode string Optional. (Optional) The method used to scale the chart to the specified to the specified dimensions (if both height and width are set)." Possible values are: Fit, FitAndCenter, Fill

Returns

System.IO.Stream

Examples

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    var image = chart.getImage();
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

setData(sourceData: object, seriesBy: string)

Resets the source data for the chart.

Syntax

chartObject.setData(sourceData, seriesBy);

Parameters

Parameter Type Description
sourceData object The Range object corresponding to the source data.
seriesBy string Optional. Specifies the way columns or rows are used as data series on the chart. Can be one of the following: Auto (default), Rows, Columns. Possible values are: Auto, Columns, Rows

Returns

void

Examples

Set the sourceData to be "A1:B4" and seriesBy to be "Columns"

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    var sourceData = "A1:B4";
    chart.setData(sourceData, "Columns");
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

setPosition(startCell: object, endCell: object)

Positions the chart relative to cells on the worksheet.

Syntax

chartObject.setPosition(startCell, endCell);

Parameters

Parameter Type Description
startCell object The start cell. This is where the chart will be moved to. The start cell is the top-left or top-right cell, depending on the user's right-to-left display settings.
endCell object Optional. (Optional) The end cell. If specified, the chart's width and height will be set to fully cover up this cell/range.

Returns

void

Examples

Excel.run(function (ctx) { 
    var sheetName = "Charts";
    var rangeSelection = "A1:B4";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeSelection);
    var sourceData = sheetName + "!" + "A1:B4";
    var chart = ctx.workbook.worksheets.getItem(sheetName).charts.add("pie", range, "auto");
    chart.width = 500;
    chart.height = 300;
    chart.setPosition("C2", null);
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Property access examples

Get a chart named "Chart1"

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.load('name');
    return ctx.sync().then(function() {
            console.log(chart.name);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Update a chart including renaming, positioning and resizing.

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.name="New Name";
    chart.top = 100;
    chart.left = 100;
    chart.height = 200;
    chart.width = 200;
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Rename the chart to new name, resize the chart to 200 points in both height and weight. Move Chart1 to 100 points to the top and left. 

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
    chart.name="New Name";    
    chart.top = 100;
    chart.left = 100;
    chart.height =200;
    chart.width =200;
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

results matching ""

    No results matching ""