ExcelScript.Chart interface

参考

包:: ExcelScript

表示工作簿中的 chart 对象。

方法

activate()	在 Excel UI 中激活图表。
addChartSeries(name, index)	向集合添加新系列。在根据图表类型) (设置其值、x 轴值或气泡大小之前，新添加的序列才可见。
delete()	删除 chart 对象。
getAxes()	表示图表坐标轴。
getCategoryLabelLevel()	指定图表类别标签级别枚举常量，引用源类别标签的级别。
getChartType()	指定图表的类型。有关详细信息，请参阅 `ExcelScript.ChartType`。
getDataLabels()	表示图表上的数据标签。
getDataTable()	获取图表上的数据表。如果图表不允许使用数据表，则此方法返回 `undefined`。
getDisplayBlanksAs()	指定在图表上绘制空白单元格的方式。
getFormat()	封装图表区域的格式属性。
getHeight()	指定图表对象的高度（以磅为单位）。
getId()	图表的唯一 ID。
getImage(width, height, fittingMode)	通过缩放图表以适应指定的尺寸，将图表呈现为 base64 编码的图像。纵横比将保留为调整大小的一部分。
getLeft()	从图表左侧到工作表原点的距离，以磅为单位。
getLegend()	表示图表的图例。
getName()	指定图表对象的名称。
getPivotOptions()	封装数据透视图的选项。
getPlotArea()	表示图表的绘图区。
getPlotBy()	指定列或行在图表上用作数据系列的方式。
getPlotVisibleOnly()	如果仅绘制可见单元格，则为 True。如果绘制可见单元格和隐藏单元格，则为 False。
getSeries()	表示单个系列或图表中的系列集合。
getSeriesNameLevel()	指定图表系列名称级别枚举常量，引用源系列名称的级别。
getShowAllFieldButtons()	指定是否在数据透视图上显示所有字段按钮。
getShowDataLabelsOverMaximum()	指定当值大于数值轴上的最大值时是否显示数据标签。如果数值轴小于数据点的大小，则可以使用此属性来设置是否显示数据标签。该属性只适用于二维图表。
getStyle()	指定图表的图表样式。
getTitle()	表示指定图表的标题，包括标题的文本、可见性、位置和格式。
getTop()	指定从工作表) 或图表 () 上 (的图表区顶部到第 1 行的上边缘到第 1 行顶部的距离（以磅为单位）。
getWidth()	指定图表对象的宽度（以磅为单位）。
getWorksheet()	包含当前 chart 的 worksheet 对象。
setCategoryLabelLevel(categoryLabelLevel)	指定图表类别标签级别枚举常量，引用源类别标签的级别。
setChartType(chartType)	指定图表的类型。有关详细信息，请参阅 `ExcelScript.ChartType`。
setData(sourceData, seriesBy)	重置图表的源数据。
setDisplayBlanksAs(displayBlanksAs)	指定在图表上绘制空白单元格的方式。
setHeight(height)	指定图表对象的高度（以磅为单位）。
setLeft(left)	从图表左侧到工作表原点的距离，以磅为单位。
setName(name)	指定图表对象的名称。
setPlotBy(plotBy)	指定列或行在图表上用作数据系列的方式。
setPlotVisibleOnly(plotVisibleOnly)	如果仅绘制可见单元格，则为 True。如果绘制可见单元格和隐藏单元格，则为 False。
setPosition(startCell, endCell)	相对于工作表上的单元格放置图表。
setSeriesNameLevel(seriesNameLevel)	指定图表系列名称级别枚举常量，引用源系列名称的级别。
setShowAllFieldButtons(showAllFieldButtons)	指定是否在数据透视图上显示所有字段按钮。
setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)	指定当值大于数值轴上的最大值时是否显示数据标签。如果数值轴小于数据点的大小，则可以使用此属性来设置是否显示数据标签。该属性只适用于二维图表。
setStyle(style)	指定图表的图表样式。
setTop(top)	指定从工作表) 或图表 () 上 (的图表区顶部到第 1 行的上边缘到第 1 行顶部的距离（以磅为单位）。
setWidth(width)	指定图表对象的宽度（以磅为单位）。

方法详细信息

activate()

在 Excel UI 中激活图表。

activate(): void;

void

addChartSeries(name, index)

向集合添加新系列。在根据图表类型) (设置其值、x 轴值或气泡大小之前，新添加的序列才可见。

addChartSeries(name?: string, index?: number): ChartSeries;

参数

name: string

可选。系列的名称。

index: number

可选。要添加的序列的索引值。从零开始编制索引。

ExcelScript.ChartSeries

示例

/**
 * This sample produces a line chart with two series.
 * The chart assumes data in A1:E5 that looks like this:
 * Product Qtr1 Qtr2 Qtr3 Qtr4
 * Frames 5000 7000 6544 4377
 * Saddles 400 323 276 651
 */
function main(workbook: ExcelScript.Workbook) {
  // Establish the ranges to use.
  const sheet = workbook.getActiveWorksheet();
  const headerRange = sheet.getRange("A1:E1");
  const firstSeriesRange = sheet.getRange("A2:E2");
  const secondSeriesRange = sheet.getRange("A3:E3");

  // Create the chart.
  const lineChart = sheet.addChart(ExcelScript.ChartType.line, headerRange);

  // Add the first chart series.
  const firstSeries = lineChart.addChartSeries();
  firstSeries.setXAxisValues(headerRange);
  firstSeries.setValues(firstSeriesRange);

  // Add the second chart series.
  const secondSeries = lineChart.addChartSeries();
  secondSeries.setXAxisValues(headerRange);
  secondSeries.setValues(secondSeriesRange);
}

delete()

删除 chart 对象。

delete(): void;

void

getAxes()

表示图表坐标轴。

getAxes(): ChartAxes;

ExcelScript.ChartAxes

getCategoryLabelLevel()

指定图表类别标签级别枚举常量，引用源类别标签的级别。

getCategoryLabelLevel(): number;

number

getChartType()

指定图表的类型。有关详细信息，请参阅 ExcelScript.ChartType。

getChartType(): ChartType;

ExcelScript.ChartType

getDataLabels()

表示图表上的数据标签。

getDataLabels(): ChartDataLabels;

ExcelScript.ChartDataLabels

getDataTable()

获取图表上的数据表。如果图表不允许使用数据表，则此方法返回 undefined。

getDataTable(): ChartDataTable;

ExcelScript.ChartDataTable

getDisplayBlanksAs()

指定在图表上绘制空白单元格的方式。

getDisplayBlanksAs(): ChartDisplayBlanksAs;

ExcelScript.ChartDisplayBlanksAs

getFormat()

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

getFormat(): ChartAreaFormat;

ExcelScript.ChartAreaFormat

getHeight()

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

getHeight(): number;

number

getId()

图表的唯一 ID。

getId(): string;

string

getImage(width, height, fittingMode)

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

getImage(
            width?: number,
            height?: number,
            fittingMode?: ImageFittingMode
        ): string;

参数

width: number

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

height: number

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

fittingMode: ExcelScript.ImageFittingMode

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

string

示例

/**
 * This script returns an image of the first chart in the first worksheet.
 * That image is 600x400 pixels and the chart will be 
 * stretched to fill those dimensions.
 * The returned image can be used in a Power Automate flow.
 */
function main(workbook: ExcelScript.Workbook): string {
  // Get the first chart in the first worksheet.
  const firstSheet = workbook.getFirstWorksheet();
  const firstChart = firstSheet.getCharts()[0];

  // Get an image of the chart as a base64-encoded string.
  const base64String = firstChart.getImage(
    600, /* Width */
    400, /* Height */
    ExcelScript.ImageFittingMode.fill /* Fill to match the dimensions. */
  );

  return base64String;
}

getLeft()

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

getLeft(): number;

number

getLegend()

表示图表的图例。

getLegend(): ChartLegend;

ExcelScript.ChartLegend

getName()

指定图表对象的名称。

getName(): string;

string

getPivotOptions()

封装数据透视图的选项。

getPivotOptions(): ChartPivotOptions;

ExcelScript.ChartPivotOptions

getPlotArea()

表示图表的绘图区。

getPlotArea(): ChartPlotArea;

ExcelScript.ChartPlotArea

getPlotBy()

指定列或行在图表上用作数据系列的方式。

getPlotBy(): ChartPlotBy;

ExcelScript.ChartPlotBy

示例

/**
 * This sample performs the "Switch Row/Column" action on a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let columnClusteredChart = selectedSheet.getChart("ColumnClusteredChart");
  
  // Switch the row and column for the chart's data source.
  if (columnClusteredChart.getPlotBy() === ExcelScript.ChartPlotBy.columns) {
    // If the chart is grouped by columns, switch it to rows.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.rows);
  } else {
    // If the chart is grouped by rows, switch it to columns.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.columns);
  }
}

getPlotVisibleOnly()

如果仅绘制可见单元格，则为 True。如果绘制可见单元格和隐藏单元格，则为 False。

getPlotVisibleOnly(): boolean;

boolean

getSeries()

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

getSeries(): ChartSeries[];

ExcelScript.ChartSeries[]

示例

/**
 * This sample sets the overlap of the columns in a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let chart = selectedSheet.getChart("ColumnClusteredChart");

  // Set the overlap of every column of each series within a category.
  let seriesList = chart.getSeries();
  seriesList.forEach((series) => {
    // An overlap of 25 means the columns have 25% of their length overlapping with the adjacent columns in the same category.
    series.setOverlap(25);
  });
}

getSeriesNameLevel()

指定图表系列名称级别枚举常量，引用源系列名称的级别。

getSeriesNameLevel(): number;

number

getShowAllFieldButtons()

指定是否在数据透视图上显示所有字段按钮。

getShowAllFieldButtons(): boolean;

boolean

getShowDataLabelsOverMaximum()

指定当值大于数值轴上的最大值时是否显示数据标签。如果数值轴小于数据点的大小，则可以使用此属性来设置是否显示数据标签。该属性只适用于二维图表。

getShowDataLabelsOverMaximum(): boolean;

boolean

getStyle()

指定图表的图表样式。

getStyle(): number;

number

getTitle()

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

getTitle(): ChartTitle;

ExcelScript.ChartTitle

getTop()

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

getTop(): number;

number

getWidth()

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

getWidth(): number;

number

getWorksheet()

包含当前 chart 的 worksheet 对象。

getWorksheet(): Worksheet;

ExcelScript.Worksheet

setCategoryLabelLevel(categoryLabelLevel)

指定图表类别标签级别枚举常量，引用源类别标签的级别。

setCategoryLabelLevel(categoryLabelLevel: number): void;

参数

categoryLabelLevel: number

void

setChartType(chartType)

指定图表的类型。有关详细信息，请参阅 ExcelScript.ChartType。

setChartType(chartType: ChartType): void;

参数

chartType: ExcelScript.ChartType

void

setData(sourceData, seriesBy)

重置图表的源数据。

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

参数

sourceData: ExcelScript.Range

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

seriesBy: ExcelScript.ChartSeriesBy

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

void

setDisplayBlanksAs(displayBlanksAs)

指定在图表上绘制空白单元格的方式。

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

参数

displayBlanksAs: ExcelScript.ChartDisplayBlanksAs

void

setHeight(height)

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

setHeight(height: number): void;

参数

height: number

void

setLeft(left)

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

setLeft(left: number): void;

参数

left: number

void

setName(name)

指定图表对象的名称。

setName(name: string): void;

参数

name: string

void

示例

/**
 * This sample creates a column-clustered chart based on the current worksheet's data.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the data range.
  let range = selectedSheet.getUsedRange();

  // Insert a chart using the data on the current worksheet.
  let chart = selectedSheet.addChart(ExcelScript.ChartType.columnClustered, range);

  // Name the chart for easy access in other scripts.
  chart.setName("ColumnChart");
}

setPlotBy(plotBy)

指定列或行在图表上用作数据系列的方式。

setPlotBy(plotBy: ChartPlotBy): void;

参数

plotBy: ExcelScript.ChartPlotBy

void

示例

/**
 * This sample performs the "Switch Row/Column" action on a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let columnClusteredChart = selectedSheet.getChart("ColumnClusteredChart");
  
  // Switch the row and column for the chart's data source.
  if (columnClusteredChart.getPlotBy() === ExcelScript.ChartPlotBy.columns) {
    // If the chart is grouped by columns, switch it to rows.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.rows);
  } else {
    // If the chart is grouped by rows, switch it to columns.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.columns);
  }
}

setPlotVisibleOnly(plotVisibleOnly)

如果仅绘制可见单元格，则为 True。如果绘制可见单元格和隐藏单元格，则为 False。

setPlotVisibleOnly(plotVisibleOnly: boolean): void;

参数

plotVisibleOnly: boolean

void

setPosition(startCell, endCell)

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

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

参数

startCell: ExcelScript.Range | string

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

endCell: ExcelScript.Range | string

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

void

示例

/**
 * This sample moves an existing chart to a specific place on the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();
  
  // Get an existing chart named "ColumnChart".
  let chart = selectedSheet.getChart("ColumnChart");

  // Place the chart over the range "F1:L13".
  chart.setPosition("F1", "L13");
}

setSeriesNameLevel(seriesNameLevel)

指定图表系列名称级别枚举常量，引用源系列名称的级别。

setSeriesNameLevel(seriesNameLevel: number): void;

参数

seriesNameLevel: number

void

setShowAllFieldButtons(showAllFieldButtons)

指定是否在数据透视图上显示所有字段按钮。

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

参数

showAllFieldButtons: boolean

void

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

参数

showDataLabelsOverMaximum: boolean

void

setStyle(style)

指定图表的图表样式。

setStyle(style: number): void;

参数

style: number

void

setTop(top)

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

setTop(top: number): void;

参数

top: number

void

setWidth(width)

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

setWidth(width: number): void;

参数

width: number

void