Excel.ChartAxis class

Represents a single axis in a chart.

[ API set: ExcelApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

axisGroup

Represents the group for the specified axis. See Excel.ChartAxisGroup for details. Read-only.

[ API set: ExcelApi 1.7 ]

baseTimeUnit

Returns or sets the base unit for the specified category axis.

[ API set: ExcelApi 1.7 ]

categoryType

Returns or sets the category axis type.

[ API set: ExcelApi 1.7 ]

customDisplayUnit

Represents the custom axis display unit value. Read-only. To set this property, please use the SetCustomDisplayUnit(double) method.

[ API set: ExcelApi 1.7 ]

displayUnit

Represents the axis display unit. See Excel.ChartAxisDisplayUnit for details.

[ API set: ExcelApi 1.7 ]

format

Represents the formatting of a chart object, which includes line and font formatting. Read-only.

[ API set: ExcelApi 1.1 ]

height

Represents the height, in points, of the chart axis. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

left

Represents the distance, in points, from the left edge of the axis to the left of chart area. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

logBase

Represents the base of the logarithm when using logarithmic scales.

[ API set: ExcelApi 1.7 ]

majorGridlines

Returns a Gridlines object that represents the major gridlines for the specified axis. Read-only.

[ API set: ExcelApi 1.1 ]

majorTickMark

Represents the type of major tick mark for the specified axis. See Excel.ChartAxisTickMark for details.

[ API set: ExcelApi 1.7 ]

majorTimeUnitScale

Returns or sets the major unit scale value for the category axis when the CategoryType property is set to TimeScale.

[ API set: ExcelApi 1.7 ]

majorUnit

Represents the interval between two major tick marks. Can be set to a numeric value or an empty string. The returned value is always a number.

[ API set: ExcelApi 1.1 ]

maximum

Represents the maximum value on the value axis. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

minimum

Represents the minimum value on the value axis. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

minorGridlines

Returns a Gridlines object that represents the minor gridlines for the specified axis. Read-only.

[ API set: ExcelApi 1.1 ]

minorTickMark

Represents the type of minor tick mark for the specified axis. See Excel.ChartAxisTickMark for details.

[ API set: ExcelApi 1.7 ]

minorTimeUnitScale

Returns or sets the minor unit scale value for the category axis when the CategoryType property is set to TimeScale.

[ API set: ExcelApi 1.7 ]

minorUnit

Represents the interval between two minor tick marks. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

reversePlotOrder

Represents whether Microsoft Excel plots data points from last to first.

[ API set: ExcelApi 1.7 ]

scaleType

Represents the value axis scale type. See Excel.ChartAxisScaleType for details.

[ API set: ExcelApi 1.7 ]

showDisplayUnitLabel

Represents whether the axis display unit label is visible.

[ API set: ExcelApi 1.7 ]

tickLabelPosition

Represents the position of tick-mark labels on the specified axis. See Excel.ChartAxisTickLabelPosition for details.

[ API set: ExcelApi 1.7 ]

tickLabelSpacing

Represents the number of categories or series between tick-mark labels. Can be a value from 1 through 31999 or an empty string for automatic setting. The returned value is always a number.

[ API set: ExcelApi 1.7 ]

tickMarkSpacing

Represents the number of categories or series between tick marks.

[ API set: ExcelApi 1.7 ]

title

Represents the axis title. Read-only.

[ API set: ExcelApi 1.1 ]

top

Represents the distance, in points, from the top edge of the axis to the top of chart area. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

type

Represents the axis type. See Excel.ChartAxisType for details.

[ API set: ExcelApi 1.7 ]

visible

A boolean value represents the visibility of the axis.

[ API set: ExcelApi 1.7 ]

width

Represents the width, in points, of the chart axis. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

Methods

load(option)

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

setCategoryNames(sourceData)

Sets all the category names for the specified axis.

[ API set: ExcelApi 1.7 ]

setCustomDisplayUnit(value)

Sets the axis display unit to a custom value.

[ API set: ExcelApi 1.7 ]

toJSON()

Property Details

axisGroup

Represents the group for the specified axis. See Excel.ChartAxisGroup for details. Read-only.

[ API set: ExcelApi 1.7 ]

readonly axisGroup: Excel.ChartAxisGroup | "Primary" | "Secondary";
Property Value
Excel.ChartAxisGroup | "Primary" | "Secondary"

baseTimeUnit

Returns or sets the base unit for the specified category axis.

[ API set: ExcelApi 1.7 ]

baseTimeUnit: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";
Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"

categoryType

Returns or sets the category axis type.

[ API set: ExcelApi 1.7 ]

categoryType: Excel.ChartAxisCategoryType | "Automatic" | "TextAxis" | "DateAxis";
Property Value
Excel.ChartAxisCategoryType | "Automatic" | "TextAxis" | "DateAxis"

customDisplayUnit

Represents the custom axis display unit value. Read-only. To set this property, please use the SetCustomDisplayUnit(double) method.

[ API set: ExcelApi 1.7 ]

readonly customDisplayUnit: number;
Property Value
number

displayUnit

Represents the axis display unit. See Excel.ChartAxisDisplayUnit for details.

[ API set: ExcelApi 1.7 ]

displayUnit: Excel.ChartAxisDisplayUnit | "None" | "Hundreds" | "Thousands" | "TenThousands" | "HundredThousands" | "Millions" | "TenMillions" | "HundredMillions" | "Billions" | "Trillions" | "Custom";
Property Value
Excel.ChartAxisDisplayUnit | "None" | "Hundreds" | "Thousands" | "TenThousands" | "HundredThousands" | "Millions" | "TenMillions" | "HundredMillions" | "Billions" | "Trillions" | "Custom"

Examples

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    let chart = sheet.charts.getItemAt(0);
    let categoryAxis = chart.axes.categoryAxis;
    let valueAxis = chart.axes.valueAxis;

    // Load to get display unit.
    valueAxis.load("displayUnit");

    await context.sync();

    OfficeHelpers.UI.notify("The vertical axis display unit is: " +  valueAxis.displayUnit);
});

format

Represents the formatting of a chart object, which includes line and font formatting. Read-only.

[ API set: ExcelApi 1.1 ]

readonly format: Excel.ChartAxisFormat;
Property Value

height

Represents the height, in points, of the chart axis. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

readonly height: number;
Property Value
number

left

Represents the distance, in points, from the left edge of the axis to the left of chart area. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

readonly left: number;
Property Value
number

logBase

Represents the base of the logarithm when using logarithmic scales.

[ API set: ExcelApi 1.7 ]

logBase: number;
Property Value
number

majorGridlines

Returns a Gridlines object that represents the major gridlines for the specified axis. Read-only.

[ API set: ExcelApi 1.1 ]

readonly majorGridlines: Excel.ChartGridlines;
Property Value

majorTickMark

Represents the type of major tick mark for the specified axis. See Excel.ChartAxisTickMark for details.

[ API set: ExcelApi 1.7 ]

majorTickMark: Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside";
Property Value
Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside"

majorTimeUnitScale

Returns or sets the major unit scale value for the category axis when the CategoryType property is set to TimeScale.

[ API set: ExcelApi 1.7 ]

majorTimeUnitScale: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";
Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"

majorUnit

Represents the interval between two major tick marks. Can be set to a numeric value or an empty string. The returned value is always a number.

[ API set: ExcelApi 1.1 ]

majorUnit: any;
Property Value
any

maximum

Represents the maximum value on the value axis. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

maximum: any;
Property Value
any

minimum

Represents the minimum value on the value axis. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

minimum: any;
Property Value
any

minorGridlines

Returns a Gridlines object that represents the minor gridlines for the specified axis. Read-only.

[ API set: ExcelApi 1.1 ]

readonly minorGridlines: Excel.ChartGridlines;
Property Value

minorTickMark

Represents the type of minor tick mark for the specified axis. See Excel.ChartAxisTickMark for details.

[ API set: ExcelApi 1.7 ]

minorTickMark: Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside";
Property Value
Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside"

minorTimeUnitScale

Returns or sets the minor unit scale value for the category axis when the CategoryType property is set to TimeScale.

[ API set: ExcelApi 1.7 ]

minorTimeUnitScale: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";
Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"

minorUnit

Represents the interval between two minor tick marks. Can be set to a numeric value or an empty string (for automatic axis values). The returned value is always a number.

[ API set: ExcelApi 1.1 ]

minorUnit: any;
Property Value
any

reversePlotOrder

Represents whether Microsoft Excel plots data points from last to first.

[ API set: ExcelApi 1.7 ]

reversePlotOrder: boolean;
Property Value
boolean

scaleType

Represents the value axis scale type. See Excel.ChartAxisScaleType for details.

[ API set: ExcelApi 1.7 ]

scaleType: Excel.ChartAxisScaleType | "Linear" | "Logarithmic";
Property Value
Excel.ChartAxisScaleType | "Linear" | "Logarithmic"

showDisplayUnitLabel

Represents whether the axis display unit label is visible.

[ API set: ExcelApi 1.7 ]

showDisplayUnitLabel: boolean;
Property Value
boolean

Examples

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    let chart = sheet.charts.getItemAt(0);
    let axis = chart.axes.valueAxis;

    // Remove display unit.
    axis.showDisplayUnitLabel = false;

    await context.sync();
});

tickLabelPosition

Represents the position of tick-mark labels on the specified axis. See Excel.ChartAxisTickLabelPosition for details.

[ API set: ExcelApi 1.7 ]

tickLabelPosition: Excel.ChartAxisTickLabelPosition | "NextToAxis" | "High" | "Low" | "None";
Property Value
Excel.ChartAxisTickLabelPosition | "NextToAxis" | "High" | "Low" | "None"

tickLabelSpacing

Represents the number of categories or series between tick-mark labels. Can be a value from 1 through 31999 or an empty string for automatic setting. The returned value is always a number.

[ API set: ExcelApi 1.7 ]

tickLabelSpacing: any;
Property Value
any

tickMarkSpacing

Represents the number of categories or series between tick marks.

[ API set: ExcelApi 1.7 ]

tickMarkSpacing: number;
Property Value
number

title

Represents the axis title. Read-only.

[ API set: ExcelApi 1.1 ]

readonly title: Excel.ChartAxisTitle;
Property Value

top

Represents the distance, in points, from the top edge of the axis to the top of chart area. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

readonly top: number;
Property Value
number

type

Represents the axis type. See Excel.ChartAxisType for details.

[ API set: ExcelApi 1.7 ]

readonly type: Excel.ChartAxisType | "Invalid" | "Category" | "Value" | "Series";
Property Value
Excel.ChartAxisType | "Invalid" | "Category" | "Value" | "Series"

visible

A boolean value represents the visibility of the axis.

[ API set: ExcelApi 1.7 ]

visible: boolean;
Property Value
boolean

width

Represents the width, in points, of the chart axis. Null if the axis is not visible. Read-only.

[ API set: ExcelApi 1.7 ]

readonly width: number;
Property Value
number

Method Details

load(option)

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

load(option?: string | string[]): Excel.ChartAxis;
Parameters
option
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns
Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): Excel.ChartAxis - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.ChartAxis - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

Examples

// Get the maximum of Chart Axis from Chart1
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    var axis = chart.axes.valueAxis;
    axis.load('maximum');
    return ctx.sync().then(function() {
            console.log(axis.maximum);
    });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});
// Set the maximum, minimum, majorunit, minorunit of valueaxis. 
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.axes.valueAxis.maximum = 5;
    chart.axes.valueAxis.minimum = 0;
    chart.axes.valueAxis.majorUnit = 1;
    chart.axes.valueAxis.minorUnit = 0.2;
    return ctx.sync().then(function() {
            console.log("Axis Settings Changed");
    });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

setCategoryNames(sourceData)

Sets all the category names for the specified axis.

[ API set: ExcelApi 1.7 ]

setCategoryNames(sourceData: Range): void;
Parameters
sourceData
Range

The Range object corresponding to the source data.

Returns
void

setCustomDisplayUnit(value)

Sets the axis display unit to a custom value.

[ API set: ExcelApi 1.7 ]

setCustomDisplayUnit(value: number): void;
Parameters
value
number

Custom value of the display unit.

Returns
void

toJSON()

toJSON(): Excel.Interfaces.ChartAxisData;
Returns