Excel.ChartCollection class
工作表中的所有 chart 对象的集合。
- 扩展
注解
属性
| context | 与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。 |
| count | 返回工作表中的图表数。 |
| items | 获取此集合中已加载的子项。 |
方法
| add(type, source |
创建新图表。 |
| add(type |
创建新图表。 |
| get |
返回工作表中的图表数。 |
| get |
使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。 |
| get |
根据其在集合中的位置获取图表。 |
| get |
使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。 如果图表不存在，则此方法返回一个 对象，其 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| toJSON() | 重写 JavaScript |
事件
| on |
在激活图表时发生。 |
| on |
在将新图表添加到工作表时发生。 |
| on |
停用图表时发生。 |
| on |
删除图表时发生。 |
属性详细信息
context
count
items
方法详细信息
add(type, sourceData, seriesBy)
创建新图表。
add(type: Excel.ChartType, sourceData: Range, seriesBy?: Excel.ChartSeriesBy): Excel.Chart;参数
- type
- Excel.ChartType
表示图表的类型。 有关详细信息，请参阅 Excel.ChartType。
- sourceData
- Excel.Range
对应于 Range 源数据的对象。
- seriesBy
- Excel.ChartSeriesBy
可选。 指定列或行在图表上用作数据系列的方式。 有关详细信息，请参阅 Excel.ChartSeriesBy。
返回
注解
示例
// Add a chart of chartType "ColumnClustered" on worksheet "Charts"
// with sourceData from range "A1:B4" and seriesBy set to "auto".
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sheet1");
const rangeSelection = "A1:B4";
const range = sheet.getRange(rangeSelection);
const chart = sheet.charts.add(
Excel.ChartType.columnClustered,
range,
Excel.ChartSeriesBy.auto);
await context.sync();
console.log("New Chart Added");
});
add(typeString, sourceData, seriesByString)
创建新图表。
add(typeString: "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", sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): Excel.Chart;参数
- typeString
-
"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。
- sourceData
- Excel.Range
对应于 Range 源数据的对象。
- seriesByString
-
"Auto" | "Columns" | "Rows"
可选。 指定列或行在图表上用作数据系列的方式。 有关详细信息，请参阅 Excel.ChartSeriesBy。
返回
注解
getCount()
返回工作表中的图表数。
getCount(): OfficeExtension.ClientResult<number>;返回
OfficeExtension.ClientResult<number>
注解
getItem(name)
使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。
getItem(name: string): Excel.Chart;参数
- name
-
string
要检索的图表的名称。
返回
注解
示例
// Get the number of charts.
await Excel.run(async (context) => {
const charts = context.workbook.worksheets.getItem("Sheet1").charts;
charts.load('count');
await context.sync();
console.log("charts: Count= " + charts.count);
});
getItemAt(index)
根据其在集合中的位置获取图表。
getItemAt(index: number): Excel.Chart;参数
- index
-
number
要检索的对象的索引值。 从零开始编制索引。
返回
注解
示例
await Excel.run(async (context) => {
const lastPosition = context.workbook.worksheets.getItem("Sheet1").charts.count - 1;
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItemAt(lastPosition);
await context.sync();
console.log(chart.name);
});
getItemOrNullObject(name)
使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。 如果图表不存在，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getItemOrNullObject(name: string): Excel.Chart;参数
- name
-
string
要检索的图表的名称。
返回
注解
load(options)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(options?: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.ChartCollection;参数
提供要加载对象的属性的选项。
返回
load(propertyNames)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNames?: string | string[]): Excel.ChartCollection;参数
- propertyNames
-
string | string[]
逗号分隔的字符串或指定要加载的属性的字符串数组。
返回
示例
await Excel.run(async (context) => {
const charts = context.workbook.worksheets.getItem("Sheet1").charts;
charts.load('items');
await context.sync();
for (let i = 0; i < charts.items.length; i++) {
console.log(charts.items[i].name);
}
});
load(propertyNamesAndPaths)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.ChartCollection;参数
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。
返回
toJSON()
重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。
JSON.stringify
(，反过来，调用toJSON传递给它的 对象的 方法。) 虽然原始Excel.ChartCollection对象是 API 对象，toJSON但该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.ChartCollectionData) ，其中包含一个“items”数组，其中包含集合项中任何已加载属性的浅表副本。
toJSON(): Excel.Interfaces.ChartCollectionData;返回
事件详细信息
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}.`);
});
}
onAdded
在将新图表添加到工作表时发生。
readonly onAdded: OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>;事件类型
注解
示例
await Excel.run(async (context) => {
context.workbook.worksheets.getActiveWorksheet()
.charts.onAdded.add(function (event) {
return Excel.run(async (context) => {
console.log("A chart has been added with ID: " + event.chartId);
await context.sync();
});
});
await context.sync();
});
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.");
});
}
onDeleted
删除图表时发生。
readonly onDeleted: OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>;事件类型
注解
示例
await Excel.run(async (context) => {
context.workbook.worksheets.getActiveWorksheet()
.charts.onDeleted.add(function (event) {
return Excel.run(async (context) => {
console.log("The chart with this ID was deleted: " + event.chartId);
await context.sync();
});
});
await context.sync();
});