Excel.ChartAxis class
Represents a single axis in a chart.
- Extends
Remarks
Properties
| axis |
Specifies the group for the specified axis. See |
| base |
Specifies the base unit for the specified category axis. |
| category |
Specifies the category axis type. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| custom |
Specifies the custom axis display unit value. To set this property, please use the |
| display |
Represents the axis display unit. See |
| format | Represents the formatting of a chart object, which includes line and font formatting. |
| height | Specifies the height, in points, of the chart axis. Returns |
| left | Specifies the distance, in points, from the left edge of the axis to the left of chart area. Returns |
| log |
Specifies the base of the logarithm when using logarithmic scales. |
| major |
Returns an object that represents the major gridlines for the specified axis. |
| major |
Specifies the type of major tick mark for the specified axis. See |
| major |
Specifies the major unit scale value for the category axis when the |
| major |
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. |
| 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. |
| 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. |
| minor |
Returns an object that represents the minor gridlines for the specified axis. |
| minor |
Specifies the type of minor tick mark for the specified axis. See |
| minor |
Specifies the minor unit scale value for the category axis when the |
| minor |
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. |
| reverse |
Specifies if Excel plots data points from last to first. |
| scale |
Specifies the value axis scale type. See |
| show |
Specifies if the axis display unit label is visible. |
| tick |
Specifies the position of tick-mark labels on the specified axis. See |
| tick |
Specifies 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. |
| tick |
Specifies the number of categories or series between tick marks. |
| title | Represents the axis title. |
| top | Specifies the distance, in points, from the top edge of the axis to the top of chart area. Returns |
| type | Specifies the axis type. See |
| visible | Specifies if the axis is visible. |
| width | Specifies the width, in points, of the chart axis. Returns |
Methods
| 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 all the category names for the specified axis. |
| set |
Sets the axis display unit to a custom value. |
| toJSON() | Overrides the JavaScript |
Property Details
axisGroup
Specifies the group for the specified axis. See Excel.ChartAxisGroup for details.
readonly axisGroup: Excel.ChartAxisGroup | "Primary" | "Secondary";Property Value
Excel.ChartAxisGroup | "Primary" | "Secondary"
Remarks
baseTimeUnit
Specifies the base unit for the specified category axis.
baseTimeUnit: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"
Remarks
categoryType
Specifies the category axis type.
categoryType: Excel.ChartAxisCategoryType | "Automatic" | "TextAxis" | "DateAxis";Property Value
Excel.ChartAxisCategoryType | "Automatic" | "TextAxis" | "DateAxis"
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
customDisplayUnit
Specifies the custom axis display unit value. To set this property, please use the SetCustomDisplayUnit(double) method.
readonly customDisplayUnit: number;Property Value
number
Remarks
displayUnit
Represents the axis display unit. See Excel.ChartAxisDisplayUnit for details.
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"
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-axis.yaml
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();
console.log("The vertical axis display unit is: " + valueAxis.displayUnit);
});
format
Represents the formatting of a chart object, which includes line and font formatting.
readonly format: Excel.ChartAxisFormat;Property Value
Remarks
height
Specifies the height, in points, of the chart axis. Returns null if the axis is not visible.
readonly height: number;Property Value
number
Remarks
left
Specifies the distance, in points, from the left edge of the axis to the left of chart area. Returns null if the axis is not visible.
readonly left: number;Property Value
number
Remarks
logBase
Specifies the base of the logarithm when using logarithmic scales.
logBase: number;Property Value
number
Remarks
majorGridlines
Returns an object that represents the major gridlines for the specified axis.
readonly majorGridlines: Excel.ChartGridlines;Property Value
Remarks
majorTickMark
Specifies the type of major tick mark for the specified axis. See Excel.ChartAxisTickMark for details.
majorTickMark: Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside";Property Value
Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside"
Remarks
majorTimeUnitScale
Specifies the major unit scale value for the category axis when the categoryType property is set to dateAxis.
majorTimeUnitScale: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"
Remarks
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.
majorUnit: any;Property Value
any
Remarks
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.
maximum: any;Property Value
any
Remarks
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.
minimum: any;Property Value
any
Remarks
minorGridlines
Returns an object that represents the minor gridlines for the specified axis.
readonly minorGridlines: Excel.ChartGridlines;Property Value
Remarks
minorTickMark
Specifies the type of minor tick mark for the specified axis. See Excel.ChartAxisTickMark for details.
minorTickMark: Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside";Property Value
Excel.ChartAxisTickMark | "None" | "Cross" | "Inside" | "Outside"
Remarks
minorTimeUnitScale
Specifies the minor unit scale value for the category axis when the categoryType property is set to dateAxis.
minorTimeUnitScale: Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years";Property Value
Excel.ChartAxisTimeUnit | "Days" | "Months" | "Years"
Remarks
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.
minorUnit: any;Property Value
any
Remarks
reversePlotOrder
Specifies if Excel plots data points from last to first.
reversePlotOrder: boolean;Property Value
boolean
Remarks
scaleType
Specifies the value axis scale type. See Excel.ChartAxisScaleType for details.
scaleType: Excel.ChartAxisScaleType | "Linear" | "Logarithmic";Property Value
Excel.ChartAxisScaleType | "Linear" | "Logarithmic"
Remarks
showDisplayUnitLabel
Specifies if the axis display unit label is visible.
showDisplayUnitLabel: boolean;Property Value
boolean
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-axis.yaml
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
Specifies the position of tick-mark labels on the specified axis. See Excel.ChartAxisTickLabelPosition for details.
tickLabelPosition: Excel.ChartAxisTickLabelPosition | "NextToAxis" | "High" | "Low" | "None";Property Value
Excel.ChartAxisTickLabelPosition | "NextToAxis" | "High" | "Low" | "None"
Remarks
tickLabelSpacing
Specifies 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.
tickLabelSpacing: any;Property Value
any
Remarks
tickMarkSpacing
Specifies the number of categories or series between tick marks.
tickMarkSpacing: number;Property Value
number
Remarks
title
Represents the axis title.
readonly title: Excel.ChartAxisTitle;Property Value
Remarks
top
Specifies the distance, in points, from the top edge of the axis to the top of chart area. Returns null if the axis is not visible.
readonly top: number;Property Value
number
Remarks
type
Specifies the axis type. See Excel.ChartAxisType for details.
readonly type: Excel.ChartAxisType | "Invalid" | "Category" | "Value" | "Series";Property Value
Excel.ChartAxisType | "Invalid" | "Category" | "Value" | "Series"
Remarks
visible
Specifies if the axis is visible.
visible: boolean;Property Value
boolean
Remarks
width
Specifies the width, in points, of the chart axis. Returns null if the axis is not visible.
readonly width: number;Property Value
number
Remarks
Method Details
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?: Excel.Interfaces.ChartAxisLoadOptions): Excel.ChartAxis;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[]): Excel.ChartAxis;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
Examples
// Get the maximum of Chart Axis from Chart1.
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
const axis = chart.axes.valueAxis;
axis.load('maximum');
await context.sync();
console.log(axis.maximum);
});
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;
}): Excel.ChartAxis;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.ChartAxisUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Excel.Interfaces.ChartAxisUpdateData
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: Excel.ChartAxis): void;Parameters
- properties
- Excel.ChartAxis
Returns
void
setCategoryNames(sourceData)
Sets all the category names for the specified axis.
setCategoryNames(sourceData: Range): void;Parameters
- sourceData
- Excel.Range
The Range object corresponding to the source data.
Returns
void
Remarks
setCustomDisplayUnit(value)
Sets the axis display unit to a custom value.
setCustomDisplayUnit(value: number): void;Parameters
- value
-
number
Custom value of the display unit.
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 Excel.ChartAxis object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ChartAxisData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Excel.Interfaces.ChartAxisData;Returns
Office Add-ins