Excel.Chart class

参考

包:: excel

表示工作簿中的 chart 对象。若要了解有关图表对象模型的详细信息，请参阅使用 Excel JavaScript API 处理图表。

扩展: OfficeExtension.ClientObject

注解

属性

axes	表示图表坐标轴。
context	与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。
dataLabels	表示图表上的数据标签。
format	封装图表区域的格式属性。
height	指定图表对象的高度（以磅为单位）。
left	从图表左侧到工作表原点的距离，以磅为单位。
legend	表示图表的图例。
name	指定图表对象的名称。
series	表示单个系列或图表中的系列集合。
title	表示指定图表的标题，包括标题的文本、可见性、位置和格式。
top	指定从工作表) 或图表 () 上 (的图表区顶部到第 1 行的上边缘到第 1 行顶部的距离（以磅为单位）。
width	指定图表对象的宽度（以磅为单位）。
worksheet	包含当前 chart 的 worksheet 对象。

方法

delete()	删除 chart 对象。
getImage(width, height, fittingMode)	通过缩放图表以适应指定维度，将图表呈现为 Base64 编码的图像。纵横比将保留为调整大小的一部分。
getImage(width, height, fittingModeString)	通过缩放图表以适应指定维度，将图表呈现为 Base64 编码的图像。纵横比将保留为调整大小的一部分。
load(options)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNames)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNamesAndPaths)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
set(properties, options)	同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties)	基于现有的已加载对象，同时对对象设置多个属性。
setData(sourceData, seriesBy)	重置图表的源数据。
setData(sourceData, seriesByString)	重置图表的源数据。
setPosition(startCell, endCell)	相对于工作表上的单元格放置图表。
toJSON()	重写 JavaScript `toJSON()` 方法，以便在将 API 对象传递给 `JSON.stringify()`时提供更有用的输出。 `JSON.stringify` (，反过来又调用`toJSON`传递给它的对象的方法。) 而原始`Excel.Chart`对象是 API 对象，`toJSON`该方法返回一个纯 JavaScript 对象， (类型为 `Excel.Interfaces.ChartData`) ，其中包含原始对象中任何已加载子属性的浅表副本。

属性详细信息

axes

表示图表坐标轴。

readonly axes: Excel.ChartAxes;

属性值

Excel.ChartAxes

注解

[ API 集：ExcelApi 1.1 ]

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

dataLabels

表示图表上的数据标签。

readonly dataLabels: Excel.ChartDataLabels;

属性值

Excel.ChartDataLabels

注解

[ API 集：ExcelApi 1.1 ]

format

封装图表区域的格式属性。

readonly format: Excel.ChartAreaFormat;

属性值

Excel.ChartAreaFormat

注解

[ API 集：ExcelApi 1.1 ]

height

指定图表对象的高度（以磅为单位）。

height: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

left

从图表左侧到工作表原点的距离，以磅为单位。

left: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

legend

表示图表的图例。

readonly legend: Excel.ChartLegend;

属性值

Excel.ChartLegend

注解

[ API 集：ExcelApi 1.1 ]

示例

// 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

注解

[ API 集：ExcelApi 1.1 ]

示例

// 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(); 
});

series

表示单个系列或图表中的系列集合。

readonly series: Excel.ChartSeriesCollection;

属性值

Excel.ChartSeriesCollection

注解

[ API 集：ExcelApi 1.1 ]

title

表示指定图表的标题，包括标题的文本、可见性、位置和格式。

readonly title: Excel.ChartTitle;

属性值

Excel.ChartTitle

注解

[ API 集：ExcelApi 1.1 ]

top

指定从工作表) 或图表 () 上 (的图表区顶部到第 1 行的上边缘到第 1 行顶部的距离（以磅为单位）。

top: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

width

指定图表对象的宽度（以磅为单位）。

width: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

worksheet

包含当前 chart 的 worksheet 对象。

readonly worksheet: Excel.Worksheet;

属性值

Excel.Worksheet

注解

[ API 集：ExcelApi 1.2 ]

方法详细信息

delete()

删除 chart 对象。

delete(): void;

void

注解

[ API 集：ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.delete();
    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>

注解

[ API 集：ExcelApi 1.2 ]

示例

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, fittingModeString)

通过缩放图表以适应指定维度，将图表呈现为 Base64 编码的图像。纵横比将保留为调整大小的一部分。

getImage(width?: number, height?: number, fittingModeString?: "Fit" | "FitAndCenter" | "Fill"): OfficeExtension.ClientResult<string>;

参数

width: number

可选。生成的图像的所需宽度。

height: number

可选。生成的图像的所需高度。

fittingModeString: "Fit" | "FitAndCenter" | "Fill"

可选。如果高度和宽度都) ，则用于将图表缩放为指定维度的方法 (。

OfficeExtension.ClientResult<string>

注解

[ API 集：ExcelApi 1.2 ]

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.ChartLoadOptions): Excel.Chart;

参数

options: Excel.Interfaces.ChartLoadOptions

提供要加载对象的属性的选项。

Excel.Chart

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Excel.Chart;

参数

propertyNames: string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

Excel.Chart

示例

// 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 一个逗号分隔的字符串，指定要加载的导航属性。

Excel.Chart

set(properties, options)

同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。

set(properties: Interfaces.ChartUpdateData, options?: OfficeExtension.UpdateOptions): void;

参数

properties: Excel.Interfaces.ChartUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options: OfficeExtension.UpdateOptions

提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

void

set(properties)

基于现有的已加载对象，同时对对象设置多个属性。

set(properties: Excel.Chart): void;

参数

properties: Excel.Chart

void

setData(sourceData, seriesBy)

重置图表的源数据。

setData(sourceData: Range, seriesBy?: Excel.ChartSeriesBy): void;

参数

sourceData: Excel.Range

对应于源数据的范围对象。

seriesBy: Excel.ChartSeriesBy

指定列或行在图表上用作数据系列的方式。可以是以下选项之一：自动 (默认) 、行和列。有关详细信息，请参阅 Excel.ChartSeriesBy。

void

注解

[ API 集：ExcelApi 1.1 ]

示例

// 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, seriesByString)

重置图表的源数据。

setData(sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): void;

参数

sourceData: Excel.Range

对应于源数据的范围对象。

seriesByString: "Auto" | "Columns" | "Rows"

指定列或行在图表上用作数据系列的方式。可以是以下选项之一：自动 (默认) 、行和列。有关详细信息，请参阅 Excel.ChartSeriesBy。

void

注解

[ API 集：ExcelApi 1.1 ]

setPosition(startCell, endCell)

相对于工作表上的单元格放置图表。

setPosition(startCell: Range | string, endCell?: Range | string): void;

参数

startCell: Excel.Range | string

起始单元格。这是图表将移动到的位置。起始单元格为左上角或右上角的单元格，具体取决于用户的从右到左显示设置。

endCell: Excel.Range | string

可选。结束单元格。如果已指定，图表的宽度和高度将设置为完全覆盖此单元格/区域。

void

注解

[ API 集：ExcelApi 1.1 ]

示例

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;

Excel.Interfaces.ChartData