Excel.Chart class
表示工作簿中的 chart 对象。 若要了解有关图表对象模型的详细信息,请参阅使用 Excel JavaScript API 处理图表。
注解
使用方
属性
| axes | 表示图表坐标轴。 |
| category |
指定图表类别标签级别枚举常量,引用源类别标签的级别。 |
| chart |
指定图表的类型。 有关详细信息,请参阅 |
| context | 与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。 |
| data |
表示图表上的数据标签。 |
| display |
指定在图表上绘制空白单元格的方式。 |
| format | 封装图表区域的格式属性。 |
| height | 指定图表对象的高度(以磅为单位)。 |
| id | 图表的唯一 ID。 |
| left | 从图表左侧到工作表原点的距离,以磅为单位。 |
| legend | 表示图表的图例。 |
| name | 指定图表对象的名称。 |
| pivot |
封装数据透视图的选项。 |
| plot |
表示图表的绘图区域。 |
| plot |
指定列或行在图表上用作数据系列的方式。 |
| plot |
如果仅绘制可见单元格,则为 True。 如果绘制可见单元格和隐藏单元格,则为 False。 |
| series | 表示单个系列或图表中的系列集合。 |
| series |
指定图表系列名称级别枚举常量,引用源系列名称的级别。 |
| show |
指定是否在数据透视图上显示所有字段按钮。 |
| show |
指定当值大于值轴上的最大值时是否显示数据标签。 如果值轴小于数据点的大小,则可以使用此属性设置是否显示数据标签。 该属性只适用于二维图表。 |
| style | 指定图表的图表样式。 |
| title | 表示指定图表的标题,包括标题的文本、可见性、位置和格式。 |
| top | 指定从对象的顶部边缘到工作表) 上 (第 1 行顶部或图表) 上 (图表区域顶部的距离(以磅为单位)。 |
| width | 指定图表对象的宽度(以磅为单位)。 |
| worksheet | 包含当前 chart 的 worksheet 对象。 |
方法
| activate() | 在 Excel UI 中激活图表。 |
| delete() | 删除 chart 对象。 |
| get |
获取整个图表的数据源。 如果数据区域为空,此方法将返回 |
| get |
获取整个图表的数据源。 如果数据区域为空,则此方法将返回其 |
| get |
获取图表上的数据表。 如果图表不允许数据表,它将引发异常。 |
| get |
获取图表上的数据表。 如果图表不允许使用数据表,则此方法将返回其 |
| get |
通过缩放图表以适应指定的维度,将图表呈现为 Base64 编码的图像。 纵横比作为调整大小的一部分保留。 |
| get |
通过缩放图表以适应指定的维度,将图表呈现为 Base64 编码的图像。 纵横比作为调整大小的一部分保留。 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| set(properties, options) | 同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。 |
| set(properties) | 基于现有加载的对象,同时在对象上设置多个属性。 |
| set |
重置图表的源数据。 |
| set |
重置图表的源数据。 |
| set |
相对于工作表上的单元格放置图表。 |
| toJSON() | 覆盖 JavaScript |
事件
| on |
在图表激活时发生。 |
| on |
在图表停用时出现。 |
属性详细信息
axes
categoryLabelLevel
chartType
指定图表的类型。 有关详细信息,请参阅 Excel.ChartType。
chartType: Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel";
属性值
Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel"
注解
context
dataLabels
表示图表上的数据标签。
readonly dataLabels: Excel.ChartDataLabels;
属性值
注解
displayBlanksAs
指定在图表上绘制空白单元格的方式。
displayBlanksAs: Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted";
属性值
Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted"
注解
format
封装图表区域的格式属性。
readonly format: Excel.ChartAreaFormat;
属性值
注解
height
id
left
legend
表示图表的图例。
readonly legend: Excel.ChartLegend;
属性值
注解
示例
// Set to show legend of Chart1 and make it on top of the chart.
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.legend.visible = true;
chart.legend.position = "Top";
chart.legend.overlay = false;
await context.sync()
console.log("Legend Shown ");
});
name
指定图表对象的名称。
name: string;
属性值
string
注解
示例
// 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.
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.name = "New Name";
chart.top = 100;
chart.left = 100;
chart.height = 200;
chart.width = 200;
await context.sync();
});
pivotOptions
封装数据透视图的选项。
readonly pivotOptions: Excel.ChartPivotOptions;
属性值
注解
plotArea
plotBy
指定列或行在图表上用作数据系列的方式。
plotBy: Excel.ChartPlotBy | "Rows" | "Columns";
属性值
Excel.ChartPlotBy | "Rows" | "Columns"
注解
plotVisibleOnly
如果仅绘制可见单元格,则为 True。 如果绘制可见单元格和隐藏单元格,则为 False。
plotVisibleOnly: boolean;
属性值
boolean
注解
series
表示单个系列或图表中的系列集合。
readonly series: Excel.ChartSeriesCollection;
属性值
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const chart: Excel.Chart = sheet.charts.getItemAt(0);
let rangeSelection = sheet.getRange("C2:C7");
let xRangeSelection = sheet.getRange("A1:A7");
// Add a series.
const newSeries: Excel.ChartSeries = chart.series.add("Qtr2");
newSeries.setValues(rangeSelection);
newSeries.setXAxisValues(xRangeSelection);
await context.sync();
});
seriesNameLevel
showAllFieldButtons
showDataLabelsOverMaximum
指定当值大于值轴上的最大值时是否显示数据标签。 如果值轴小于数据点的大小,则可以使用此属性设置是否显示数据标签。 该属性只适用于二维图表。
showDataLabelsOverMaximum: boolean;
属性值
boolean
注解
style
title
表示指定图表的标题,包括标题的文本、可见性、位置和格式。
readonly title: Excel.ChartTitle;
属性值
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-title-format.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const title = sheet.charts.getItemAt(0).title;
title.textOrientation = -45;
await context.sync();
});
top
width
worksheet
包含当前 chart 的 worksheet 对象。
readonly worksheet: Excel.Worksheet;
属性值
注解
方法详细信息
activate()
delete()
删除 chart 对象。
delete(): void;
返回
void
注解
示例
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.delete();
await context.sync();
});
getDataRange()
注意
此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
获取整个图表的数据源。 如果数据区域为空,此方法将返回 EmptyChartSeries 错误。
getDataRange(): OfficeExtension.ClientResult<string>;
返回
OfficeExtension.ClientResult<string>
注解
getDataRangeOrNullObject()
注意
此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
获取整个图表的数据源。 如果数据区域为空,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
getDataRangeOrNullObject(): OfficeExtension.ClientResult<string>;
返回
OfficeExtension.ClientResult<string>
注解
getDataTable()
获取图表上的数据表。 如果图表不允许数据表,它将引发异常。
getDataTable(): Excel.ChartDataTable;
返回
注解
getDataTableOrNullObject()
获取图表上的数据表。 如果图表不允许使用数据表,则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息,请参阅 *OrNullObject 方法和属性。
getDataTableOrNullObject(): Excel.ChartDataTable;
返回
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-data-table.yaml
// This function adds a data table to a chart that already exists on the worksheet.
await Excel.run(async (context) => {
// Retrieve the chart named "SalesChart" from the "Sample" worksheet.
const chart = context.workbook.worksheets.getItem("Sample").charts.getItem("SalesChart");
// Get the data table object for the chart and set it to visible.
const chartDataTable = chart.getDataTableOrNullObject();
chartDataTable.load("visible");
chartDataTable.visible = true;
await context.sync();
});
getImage(width, height, fittingMode)
通过缩放图表以适应指定的维度,将图表呈现为 Base64 编码的图像。 纵横比作为调整大小的一部分保留。
getImage(width?: number, height?: number, fittingMode?: Excel.ImageFittingMode): OfficeExtension.ClientResult<string>;
参数
- width
-
number
可选。 生成的图像的所需宽度。
- height
-
number
可选。 生成的图像的所需高度。
- fittingMode
- Excel.ImageFittingMode
可选。 用于将图表缩放到指定维度的方法 (高度和宽度都设置为) 。
返回
OfficeExtension.ClientResult<string>
注解
示例
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
const image = chart.getImage();
await context.sync();
});
getImage(width, height, fittingMode)
通过缩放图表以适应指定的维度,将图表呈现为 Base64 编码的图像。 纵横比作为调整大小的一部分保留。
getImage(width?: number, height?: number, fittingMode?: "Fit" | "FitAndCenter" | "Fill"): OfficeExtension.ClientResult<string>;
参数
- width
-
number
可选。 生成的图像的所需宽度。
- height
-
number
可选。 生成的图像的所需高度。
- fittingMode
-
"Fit" | "FitAndCenter" | "Fill"
可选。 用于将图表缩放到指定维度的方法 (高度和宽度都设置为) 。
返回
OfficeExtension.ClientResult<string>
注解
load(options)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(options?: Excel.Interfaces.ChartLoadOptions): Excel.Chart;
参数
为要加载的对象属性提供选项。
返回
load(propertyNames)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNames?: string | string[]): Excel.Chart;
参数
- propertyNames
-
string | string[]
指定要加载的属性的逗号分隔的字符串或字符串数组。
返回
示例
// Get a chart named "Chart1".
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.load('name');
await context.sync();
console.log(chart.name);
});
load(propertyNamesAndPaths)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.Chart;
参数
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串,以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。
返回
set(properties, options)
同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象,也可以传递另一个相同类型的 API 对象。
set(properties: Interfaces.ChartUpdateData, options?: OfficeExtension.UpdateOptions): void;
参数
- properties
- Excel.Interfaces.ChartUpdateData
一个 JavaScript 对象,其属性与调用该方法的对象的属性同构结构。
- options
- OfficeExtension.UpdateOptions
提供一个选项,用于在 properties 对象尝试设置任何只读属性时禁止错误。
返回
void
set(properties)
setData(sourceData, seriesBy)
重置图表的源数据。
setData(sourceData: Range, seriesBy?: Excel.ChartSeriesBy): void;
参数
- sourceData
- Excel.Range
与源数据对应的范围对象。
- seriesBy
- Excel.ChartSeriesBy
指定列或行在图表上用作数据系列的方式。 可以是下列项之一:自动 (默认) 、行和列。 有关详细信息,请参阅 Excel.ChartSeriesBy。
返回
void
注解
示例
// Set the sourceData to be the range at "A1:B4" and seriesBy to be "Columns".
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sheet1");
const chart = sheet.charts.getItem("Chart1");
const sourceData = sheet.getRange("A1:B4");
chart.setData(sourceData, "Columns");
await context.sync();
});
setData(sourceData, seriesBy)
重置图表的源数据。
setData(sourceData: Range, seriesBy?: "Auto" | "Columns" | "Rows"): void;
参数
- sourceData
- Excel.Range
与源数据对应的范围对象。
- seriesBy
-
"Auto" | "Columns" | "Rows"
指定列或行在图表上用作数据系列的方式。 可以是下列项之一:自动 (默认) 、行和列。 有关详细信息,请参阅 Excel.ChartSeriesBy。
返回
void
注解
setPosition(startCell, endCell)
相对于工作表上的单元格放置图表。
setPosition(startCell: Range | string, endCell?: Range | string): void;
参数
- startCell
-
Excel.Range | string
起始单元格。 这是图表将移动到的位置。 起始单元格为左上角或右上角的单元格,具体取决于用户的从右到左显示设置。
- endCell
-
Excel.Range | string
可选。 结束单元格。 如果已指定,图表的宽度和高度将设置为完全覆盖此单元格/区域。
返回
void
注解
示例
await Excel.run(async (context) => {
const sheetName = "Charts";
const rangeSelection = "A1:B4";
const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeSelection);
const sourceData = sheetName + "!" + "A1:B4";
const chart = context.workbook.worksheets.getItem(sheetName).charts.add("pie", range, "auto");
chart.width = 500;
chart.height = 300;
chart.setPosition("C2", null);
await context.sync();
});
toJSON()
覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Excel.Chart 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Excel.Interfaces.ChartData) ,其中包含从原始对象加载的任何子属性的浅层副本。
toJSON(): Excel.Interfaces.ChartData;
返回
事件详细信息
onActivated
在图表激活时发生。
readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;
事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml
await Excel.run(async (context) => {
const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");
// Register the onActivated and onDeactivated event handlers.
pieChart.onActivated.add(chartActivated);
pieChart.onDeactivated.add(chartDeactivated);
await context.sync();
console.log("Added handlers for Chart onActivated and onDeactivated events.");
});
...
async function chartActivated(event) {
await Excel.run(async (context) => {
// Retrieve the worksheet.
const sheet = context.workbook.worksheets.getActiveWorksheet();
// Retrieve the activated chart by ID and load the name of the chart.
const activatedChart = sheet.charts.getItem(event.chartId);
activatedChart.load(["name"]);
await context.sync();
// Print out the activated chart's data.
console.log(`A chart was activated. ID: ${event.chartId}. Chart name: ${activatedChart.name}.`);
});
}
onDeactivated
在图表停用时出现。
readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;
事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml
await Excel.run(async (context) => {
const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");
// Register the onActivated and onDeactivated event handlers.
pieChart.onActivated.add(chartActivated);
pieChart.onDeactivated.add(chartDeactivated);
await context.sync();
console.log("Added handlers for Chart onActivated and onDeactivated events.");
});
...
async function chartDeactivated(event) {
await Excel.run(async (context) => {
// Callback function for when the chart is deactivated.
console.log("The pie chart is NOT active.");
});
}