ExcelScript.Chart interface

Ativa o gráfico na interface do usuário do Excel.

activate(): void;

Retornos

Adiciona uma nova série para o conjunto. A nova série adicionada não ficará visível até que os valores, os valores do eixo x ou os tamanhos de bolha sejam definidos (dependendo do tipo de gráfico).

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

Parâmetros

Retornos

Exemplos

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

Exclui o objeto de gráfico.

delete(): void;

Retornos

Representa os eixos de um gráfico.

getAxes(): ChartAxes;

Retornos

Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, fazendo referência ao nível dos rótulos de categoria de origem.

getCategoryLabelLevel(): number;

Retornos

Especifica o tipo do gráfico. Consulte ExcelScript.ChartType para obter detalhes.

getChartType(): ChartType;

Retornos

Representa os rótulos de dados no gráfico.

getDataLabels(): ChartDataLabels;

Retornos

Obtém a tabela de dados no gráfico. Se o gráfico não permitir uma tabela de dados, esse método retornará undefined.

getDataTable(): ChartDataTable;

Retornos

Especifica a maneira como as células em branco são plotadas em um gráfico.

getDisplayBlanksAs(): ChartDisplayBlanksAs;

Retornos

Encapsula as propriedades de formato da área do gráfico.

getFormat(): ChartAreaFormat;

Retornos

Especifica a altura, em pontos, do objeto de gráfico.

getHeight(): number;

Retornos

Id exclusiva do gráfico.

getId(): string;

Retornos

Renderiza o gráfico como uma imagem codificada em Base64 dimensionando-o para ajustá-lo às dimensões especificadas. A taxa de proporção é preservada como parte do redimensionamento.

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

Parâmetros

Retornos

Exemplos

/**
 * 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;
}

A distância, em pontos, da esquerda do gráfico à origem da planilha.

getLeft(): number;

Retornos

Representa a legenda do gráfico.

getLegend(): ChartLegend;

Retornos

Especifica o nome de um objeto de gráfico.

getName(): string;

Retornos

Encapsula as opções para um gráfico dinâmico.

getPivotOptions(): ChartPivotOptions;

Retornos

Representa a área de plotagem do gráfico.

getPlotArea(): ChartPlotArea;

Retornos

Especifica a forma como as colunas ou linhas são usadas como série de dados no gráfico.

getPlotBy(): ChartPlotBy;

Retornos

Exemplos

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

Verdadeiro se apenas as células visíveis forem plotadas. Falso se ambas as células visíveis e ocultas forem plotadas..

getPlotVisibleOnly(): boolean;

Retornos

Representa uma única série ou uma coleção de séries no gráfico.

getSeries(): ChartSeries[];

Retornos

Exemplos

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

Especifica uma constante de enumeração de nível de nome de série de gráfico, referindo-se ao nível dos nomes de série de origem.

getSeriesNameLevel(): number;

Retornos

Especifica se todos os botões de campo devem ser exibidos em um Gráfico Dinâmico.

getShowAllFieldButtons(): boolean;

Retornos

Especifica se os rótulos de dados devem ser exibidos quando o valor for maior que o valor máximo no eixo do valor. Se o eixo dos valores se tornar menor que o tamanho dos pontos de dados, você poderá usar esta propriedade para definir se deseja exibir os rótulos de dados. Essa propriedade se aplica somente a gráficos 2D.

getShowDataLabelsOverMaximum(): boolean;

Retornos

Especifica o estilo do gráfico.

getStyle(): number;

Retornos

Representa o título do gráfico especificado, incluindo o respectivo texto, a visibilidade, a posição e a formatação.

getTitle(): ChartTitle;

Retornos

Exemplos

/**
 * This sample sets the title text for an existing chart.
 * This assumes the active worksheet has a chart.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first chart on the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const chart = sheet.getCharts()[0];
  
  // Set the chart title.
  chart.getTitle().setText("Quarterly Sales by Product");
}

Especifica a distância, em pontos, da borda superior do objeto até a parte superior da linha 1 (em uma planilha) ou a parte superior da área do gráfico (em um gráfico).

getTop(): number;

Retornos

Especifica a largura, em pontos, do objeto de gráfico.

getWidth(): number;

Retornos

A planilha que contém o gráfico atual.

getWorksheet(): Worksheet;

Retornos

Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, fazendo referência ao nível dos rótulos de categoria de origem.

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parâmetros

Retornos

Especifica o tipo do gráfico. Consulte ExcelScript.ChartType para obter detalhes.

setChartType(chartType: ChartType): void;

Parâmetros

Retornos

Redefine os dados de origem do gráfico.

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

Parâmetros

Retornos

Especifica a maneira como as células em branco são plotadas em um gráfico.

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parâmetros

Retornos

Especifica a altura, em pontos, do objeto de gráfico.

setHeight(height: number): void;

Parâmetros

Retornos

Exemplos

/**
 * This sample sets the height of an existing chart.
 * This assumes the active worksheet has a chart.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first chart on the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const chart = sheet.getCharts()[0];
  
  // Set the chart height to 300 points.
  chart.setHeight(300);
}

A distância, em pontos, da esquerda do gráfico à origem da planilha.

setLeft(left: number): void;

Parâmetros

Retornos

Exemplos

/**
 * This sample sets the left position of an existing chart.
 * This assumes the active worksheet has a chart.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first chart on the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const chart = sheet.getCharts()[0];
  
  // Set the left position to 50 points from the left edge.
  chart.setLeft(50);
}

Especifica o nome de um objeto de gráfico.

setName(name: string): void;

Parâmetros

Retornos

Exemplos

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

Especifica a forma como as colunas ou linhas são usadas como série de dados no gráfico.

setPlotBy(plotBy: ChartPlotBy): void;

Parâmetros

Retornos

Exemplos

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

Verdadeiro se apenas as células visíveis forem plotadas. Falso se ambas as células visíveis e ocultas forem plotadas..

setPlotVisibleOnly(plotVisibleOnly: boolean): void;

Parâmetros

Retornos

Posiciona o gráfico em relação às células na planilha.

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

Parâmetros

Retornos

Exemplos

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

Especifica uma constante de enumeração de nível de nome de série de gráfico, referindo-se ao nível dos nomes de série de origem.

setSeriesNameLevel(seriesNameLevel: number): void;

Parâmetros

Retornos

Especifica se todos os botões de campo devem ser exibidos em um Gráfico Dinâmico.

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

Parâmetros

Retornos

Especifica se os rótulos de dados devem ser exibidos quando o valor for maior que o valor máximo no eixo do valor. Se o eixo dos valores se tornar menor que o tamanho dos pontos de dados, você poderá usar esta propriedade para definir se deseja exibir os rótulos de dados. Essa propriedade se aplica somente a gráficos 2D.

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

Parâmetros

Retornos

Especifica o estilo do gráfico.

setStyle(style: number): void;

Parâmetros

Retornos

Especifica a distância, em pontos, da borda superior do objeto até a parte superior da linha 1 (em uma planilha) ou a parte superior da área do gráfico (em um gráfico).

setTop(top: number): void;

Parâmetros

Retornos

Exemplos

/**
 * This sample sets the top position of an existing chart.
 * This assumes the active worksheet has a chart.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first chart on the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const chart = sheet.getCharts()[0];
  
  // Set the top position to 100 points from the top edge.
  chart.setTop(100);
}

Especifica a largura, em pontos, do objeto de gráfico.

setWidth(width: number): void;

Parâmetros

Retornos

Exemplos

/**
 * This sample sets the width of an existing chart.
 * This assumes the active worksheet has a chart.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first chart on the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const chart = sheet.getCharts()[0];
  
  // Set the chart width to 500 points.
  chart.setWidth(500);
}