ExcelScript.Chart interface

Ссылка

Пакет:: ExcelScript

Представляет объект диаграммы в книге.

Методы

activate()	Активирует диаграмму в пользовательском интерфейсе Excel.
addChartSeries(name, index)	Добавляет новый ряд в коллекцию. Новый добавленный ряд не отображается до тех пор, пока не будут заданы значения, значения оси X или размеры пузырьков (в зависимости от типа диаграммы).
delete()	Удаляет объект диаграммы.
getAxes()	Представляет оси диаграммы.
getCategoryLabelLevel()	Задает константу перечисления уровня меток категории диаграммы, ссылающуюся на уровень исходных меток категорий.
getChartType()	Указывает тип диаграммы. Дополнительные сведения см. в этой `ExcelScript.ChartType` статье.
getDataLabels()	Представляет метки данных на диаграмме.
getDataTable()	Возвращает таблицу данных на диаграмме. Если диаграмма не позволяет использовать таблицу данных, этот метод возвращает `undefined`.
getDisplayBlanksAs()	Указывает способ построения пустых ячеек на диаграмме.
getFormat()	Инкапсулирует свойства формата для области диаграммы.
getHeight()	Задает высоту объекта диаграммы (в точках).
getId()	Уникальный идентификатор диаграммы.
getImage(width, height, fittingMode)	Отрисовывает диаграмму в виде изображения с кодировкой base64, масштабируя ее в соответствии с указанным размером. Пропорции сохраняются при изменении размера.
getLeft()	Расстояние в пунктах от левого края диаграммы до начала листа.
getLegend()	Представляет условные обозначения для диаграммы.
getName()	Указывает имя объекта диаграммы.
getPivotOptions()	Объединяет параметры для сводной диаграммы.
getPlotArea()	Представляет область диаграммы.
getPlotBy()	Определяет способ использования столбцов или строк в качестве рядов данных на диаграмме.
getPlotVisibleOnly()	True, если отображаются только видимые ячейки. False, если отображаются как видимые, так и скрытые ячейки.
getSeries()	Представляет один ряд данных или коллекцию рядов данных в диаграмме.
getSeriesNameLevel()	Указывает константу перечисления уровня имен рядов диаграммы, ссылающуюся на уровень имен исходных рядов.
getShowAllFieldButtons()	Указывает, должны ли отображаться все кнопки полей в сводной диаграмме.
getShowDataLabelsOverMaximum()	Указывает, следует ли отображать метки данных, если значение больше максимального значения на оси значений. Если ось значений становится меньше, чем размер точек данных, можно использовать это свойство, чтобы задать, следует ли отображать метки данных. Это свойство применяется только к двухd-диаграммам.
getStyle()	Задает стиль диаграммы.
getTitle()	Представляет заголовок указанной диаграммы, включая его текст, видимость, положение и форматирование.
getTop()	Указывает расстояние (в точках) от верхнего края объекта до верхней строки 1 (на листе) или верхней части области диаграммы (на диаграмме).
getWidth()	Задает ширину объекта диаграммы (в точках).
getWorksheet()	Лист, содержащий текущую диаграмму.
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)	Указывает, следует ли отображать метки данных, если значение больше максимального значения на оси значений. Если ось значений становится меньше, чем размер точек данных, можно использовать это свойство, чтобы задать, следует ли отображать метки данных. Это свойство применяется только к двухd-диаграммам.
setStyle(style)	Задает стиль диаграммы.
setTop(top)	Указывает расстояние (в точках) от верхнего края объекта до верхней строки 1 (на листе) или верхней части области диаграммы (на диаграмме).
setWidth(width)	Задает ширину объекта диаграммы (в точках).

Сведения о методе

activate()

Активирует диаграмму в пользовательском интерфейсе Excel.

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()

Удаляет объект диаграммы.

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()

Уникальный идентификатор диаграммы.

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()

Указывает, следует ли отображать метки данных, если значение больше максимального значения на оси значений. Если ось значений становится меньше, чем размер точек данных, можно использовать это свойство, чтобы задать, следует ли отображать метки данных. Это свойство применяется только к двухd-диаграммам.

getShowDataLabelsOverMaximum(): boolean;

Возвращаемое значение

boolean

getStyle()

Задает стиль диаграммы.

getStyle(): number;

Возвращаемое значение

number

getTitle()

Представляет заголовок указанной диаграммы, включая его текст, видимость, положение и форматирование.

getTitle(): ChartTitle;

Возвращаемое значение

ExcelScript.ChartTitle

getTop()

Указывает расстояние (в точках) от верхнего края объекта до верхней строки 1 (на листе) или верхней части области диаграммы (на диаграмме).

getTop(): number;

Возвращаемое значение

number

getWidth()

Задает ширину объекта диаграммы (в точках).

getWidth(): number;

Возвращаемое значение

number

getWorksheet()

Лист, содержащий текущую диаграмму.

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

Определяет способ использования столбцов или строк в качестве рядов данных на диаграмме. Может быть одним из следующих значений: Auto (по умолчанию), Rows и Columns. Дополнительные сведения см. в этой 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)

setTop(top: number): void;

Параметры

top: number

Возвращаемое значение

void

setWidth(width)

Задает ширину объекта диаграммы (в точках).

setWidth(width: number): void;

Параметры

width: number

Возвращаемое значение

void