ExcelScript.Chart interface

Referência

Pacote:: ExcelScript

Representa um objeto chart em uma pasta de trabalho.

Métodos

activate()	Ativa o gráfico na interface do usuário do Excel.
addChartSeries(name, index)	Adiciona uma nova série para o conjunto. A nova série adicionada não fica visível até que valores, valores de eixo x ou tamanhos de bolha para ela sejam definidos (dependendo do tipo de gráfico).
delete()	Exclui o objeto de gráfico.
getAxes()	Representa os eixos de um gráfico.
getCategoryLabelLevel()	Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, referindo-se ao nível dos rótulos de categoria de origem.
getChartType()	Especifica o tipo do gráfico. Confira `ExcelScript.ChartType` detalhes.
getDataLabels()	Representa os rótulos de dados no gráfico.
getDataTable()	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`.
getDisplayBlanksAs()	Especifica a forma como as células em branco são plotadas em um gráfico.
getFormat()	Encapsula as propriedades de formato da área do gráfico.
getHeight()	Especifica a altura, em pontos, do objeto gráfico.
getId()	Id exclusiva do gráfico.
getImage(width, height, fittingMode)	Processa o gráfico como uma imagem codificada em base64, dimensionando o gráfico para se ajustar às dimensões especificadas. A proporção é preservada como parte do redimensionamento.
getLeft()	A distância, em pontos, da esquerda do gráfico à origem da planilha.
getLegend()	Representa a legenda do gráfico.
getName()	Especifica o nome de um objeto gráfico.
getPivotOptions()	Encapsula as opções para um gráfico dinâmico.
getPlotArea()	Representa a área de plotagem para o gráfico.
getPlotBy()	Especifica a forma como as colunas ou linhas são usadas como série de dados no gráfico.
getPlotVisibleOnly()	Verdadeiro se apenas as células visíveis forem plotadas. Falso se ambas as células visíveis e ocultas forem plotadas..
getSeries()	Representa uma única série ou uma coleção de séries no gráfico.
getSeriesNameLevel()	Especifica uma constante de enumeração de nível de série de gráficos, referindo-se ao nível dos nomes da série de origem.
getShowAllFieldButtons()	Especifica se é necessário exibir todos os botões de campo em um Gráfico Dinâmico.
getShowDataLabelsOverMaximum()	Especifica se deve mostrar os rótulos de dados quando o valor é maior que o valor máximo no eixo de valor. Se o eixo de valor se tornar menor que o tamanho dos pontos de dados, você poderá usar essa propriedade para definir se deve mostrar os rótulos de dados. Essa propriedade se aplica somente a gráficos 2D.
getStyle()	Especifica o estilo do gráfico para o gráfico.
getTitle()	Representa o título do gráfico especificado, incluindo o respectivo texto, a visibilidade, a posição e a formatação.
getTop()	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).
getWidth()	Especifica a largura, em pontos, do objeto gráfico.
getWorksheet()	A planilha que contém o gráfico atual.
setCategoryLabelLevel(categoryLabelLevel)	Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, referindo-se ao nível dos rótulos de categoria de origem.
setChartType(chartType)	Especifica o tipo do gráfico. Confira `ExcelScript.ChartType` detalhes.
setData(sourceData, seriesBy)	Redefine os dados de origem do gráfico.
setDisplayBlanksAs(displayBlanksAs)	Especifica a forma como as células em branco são plotadas em um gráfico.
setHeight(height)	Especifica a altura, em pontos, do objeto gráfico.
setLeft(left)	A distância, em pontos, da esquerda do gráfico à origem da planilha.
setName(name)	Especifica o nome de um objeto gráfico.
setPlotBy(plotBy)	Especifica a forma como as colunas ou linhas são usadas como série de dados no gráfico.
setPlotVisibleOnly(plotVisibleOnly)	Verdadeiro se apenas as células visíveis forem plotadas. Falso se ambas as células visíveis e ocultas forem plotadas..
setPosition(startCell, endCell)	Posiciona o gráfico em relação às células na planilha.
setSeriesNameLevel(seriesNameLevel)	Especifica uma constante de enumeração de nível de série de gráficos, referindo-se ao nível dos nomes da série de origem.
setShowAllFieldButtons(showAllFieldButtons)	Especifica se é necessário exibir todos os botões de campo em um Gráfico Dinâmico.
setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)	Especifica se deve mostrar os rótulos de dados quando o valor é maior que o valor máximo no eixo de valor. Se o eixo de valor se tornar menor que o tamanho dos pontos de dados, você poderá usar essa propriedade para definir se deve mostrar os rótulos de dados. Essa propriedade se aplica somente a gráficos 2D.
setStyle(style)	Especifica o estilo do gráfico para o gráfico.
setTop(top)	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).
setWidth(width)	Especifica a largura, em pontos, do objeto gráfico.

Detalhes do método

activate()

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

activate(): void;

Retornos

void

addChartSeries(name, index)

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

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

Parâmetros

name: string

Opcional. Nome da série.

index: number

Opcional. Valor de índice da série a ser adicionada. Indexados com zero.

Retornos

ExcelScript.ChartSeries

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

delete()

Exclui o objeto de gráfico.

delete(): void;

Retornos

void

getAxes()

Representa os eixos de um gráfico.

getAxes(): ChartAxes;

Retornos

ExcelScript.ChartAxes

getCategoryLabelLevel()

Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, referindo-se ao nível dos rótulos de categoria de origem.

getCategoryLabelLevel(): number;

Retornos

number

getChartType()

Especifica o tipo do gráfico. Confira ExcelScript.ChartType detalhes.

getChartType(): ChartType;

Retornos

ExcelScript.ChartType

getDataLabels()

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

getDataLabels(): ChartDataLabels;

Retornos

ExcelScript.ChartDataLabels

getDataTable()

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

ExcelScript.ChartDataTable

getDisplayBlanksAs()

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

getDisplayBlanksAs(): ChartDisplayBlanksAs;

Retornos

ExcelScript.ChartDisplayBlanksAs

getFormat()

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

getFormat(): ChartAreaFormat;

Retornos

ExcelScript.ChartAreaFormat

getHeight()

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

getHeight(): number;

Retornos

number

getId()

Id exclusiva do gráfico.

getId(): string;

Retornos

string

getImage(width, height, fittingMode)

Processa o gráfico como uma imagem codificada em base64, dimensionando o gráfico para se ajustar às dimensões especificadas. A proporção é preservada como parte do redimensionamento.

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

Parâmetros

width: number

Opcional. A largura desejada da imagem resultante.

height: number

Opcional. A altura desejada da imagem resultante.

fittingMode: ExcelScript.ImageFittingMode

Opcional. O método usado para escalar o gráfico para as dimensões especificadas (se a altura e a largura forem definidas).

Retornos

string

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

getLeft()

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

getLeft(): number;

Retornos

number

getLegend()

Representa a legenda do gráfico.

getLegend(): ChartLegend;

Retornos

ExcelScript.ChartLegend

getName()

Especifica o nome de um objeto gráfico.

getName(): string;

Retornos

string

getPivotOptions()

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

getPivotOptions(): ChartPivotOptions;

Retornos

ExcelScript.ChartPivotOptions

getPlotArea()

Representa a área de plotagem para o gráfico.

getPlotArea(): ChartPlotArea;

Retornos

ExcelScript.ChartPlotArea

getPlotBy()

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

getPlotBy(): ChartPlotBy;

Retornos

ExcelScript.ChartPlotBy

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

getPlotVisibleOnly()

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

boolean

getSeries()

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

getSeries(): ChartSeries[];

Retornos

ExcelScript.ChartSeries[]

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

getSeriesNameLevel()

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

getSeriesNameLevel(): number;

Retornos

number

getShowAllFieldButtons()

Especifica se é necessário exibir todos os botões de campo em um Gráfico Dinâmico.

getShowAllFieldButtons(): boolean;

Retornos

boolean

getShowDataLabelsOverMaximum()

Especifica se deve mostrar os rótulos de dados quando o valor é maior que o valor máximo no eixo de valor. Se o eixo de valor se tornar menor que o tamanho dos pontos de dados, você poderá usar essa propriedade para definir se deve mostrar os rótulos de dados. Essa propriedade se aplica somente a gráficos 2D.

getShowDataLabelsOverMaximum(): boolean;

Retornos

boolean

getStyle()

Especifica o estilo do gráfico para o gráfico.

getStyle(): number;

Retornos

number

getTitle()

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

getTitle(): ChartTitle;

Retornos

ExcelScript.ChartTitle

getTop()

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

number

getWidth()

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

getWidth(): number;

Retornos

number

getWorksheet()

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

getWorksheet(): Worksheet;

Retornos

ExcelScript.Worksheet

setCategoryLabelLevel(categoryLabelLevel)

Especifica uma constante de enumeração de nível de rótulo de categoria de gráfico, referindo-se ao nível dos rótulos de categoria de origem.

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parâmetros

categoryLabelLevel: number

Retornos

void

setChartType(chartType)

Especifica o tipo do gráfico. Confira ExcelScript.ChartType detalhes.

setChartType(chartType: ChartType): void;

Parâmetros

chartType: ExcelScript.ChartType

Retornos

void

setData(sourceData, seriesBy)

Redefine os dados de origem do gráfico.

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

Parâmetros

sourceData: ExcelScript.Range

O objeto range correspondente aos dados de origem.

seriesBy: ExcelScript.ChartSeriesBy

Especifica a forma como as colunas ou linhas são usadas como série de dados no gráfico. Pode ser um dos seguintes: Auto (padrão), Linhas e Colunas. Confira ExcelScript.ChartSeriesBy detalhes.

Retornos

void

setDisplayBlanksAs(displayBlanksAs)

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

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parâmetros

displayBlanksAs: ExcelScript.ChartDisplayBlanksAs

Retornos

void

setHeight(height)

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

setHeight(height: number): void;

Parâmetros

height: number

Retornos

void

setLeft(left)

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

setLeft(left: number): void;

Parâmetros

left: number

Retornos

void

setName(name)

Especifica o nome de um objeto gráfico.

setName(name: string): void;

Parâmetros

name: string

Retornos

void

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

setPlotBy(plotBy)

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

plotBy: ExcelScript.ChartPlotBy

Retornos

void

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

setPlotVisibleOnly(plotVisibleOnly)

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

plotVisibleOnly: boolean

Retornos

void

setPosition(startCell, endCell)

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

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

Parâmetros

startCell: ExcelScript.Range | string

A célula inicial. Esse é o local para o qual o gráfico será movido. A célula inicial é a célula superior esquerda ou direita, dependendo das configurações de exibição do usuário, da esquerda para a direita.

endCell: ExcelScript.Range | string

Opcional. A célula final. Quando é especificada, a altura e a largura do gráfico são definidas para cobrirem totalmente essa célula ou intervalo.

Retornos

void

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

setSeriesNameLevel(seriesNameLevel)

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

setSeriesNameLevel(seriesNameLevel: number): void;

Parâmetros

seriesNameLevel: number

Retornos

void

setShowAllFieldButtons(showAllFieldButtons)

Especifica se é necessário exibir todos os botões de campo em um Gráfico Dinâmico.

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

Parâmetros

showAllFieldButtons: boolean

Retornos

void

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

Parâmetros

showDataLabelsOverMaximum: boolean

Retornos

void

setStyle(style)

Especifica o estilo do gráfico para o gráfico.

setStyle(style: number): void;

Parâmetros

style: number

Retornos

void

setTop(top)

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

top: number

Retornos

void

setWidth(width)

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

setWidth(width: number): void;

Parâmetros

width: number

Retornos

void