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 é visível até que os valores, os valores do eixo x ou os tamanhos das bolhas da mesma estejam 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 etiqueta de categoria de gráfico, referindo-se ao nível das etiquetas da categoria de origem.
getChartType()	Especifica o tipo do gráfico. Veja `ExcelScript.ChartType` para obter 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, este método devolve `undefined`.
getDisplayBlanksAs()	Especifica a forma como as células em branco são desenhadas num gráfico.
getFormat()	Encapsula as propriedades de formato da área do gráfico.
getHeight()	Especifica a altura, em pontos, do objeto de 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 de gráfico.
getPivotOptions()	Encapsula as opções para um gráfico dinâmico.
getPlotArea()	Representa a área de desenho do 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 ao nível do nome da série de gráficos, referindo-se ao nível dos nomes das séries de origem.
getShowAllFieldButtons()	Especifica se pretende apresentar todos os botões de campo num gráfico dinâmico.
getShowDataLabelsOverMaximum()	Especifica se pretende mostrar as etiquetas de dados quando o valor é maior do que o valor máximo no eixo de valores. Se o eixo de valores se tornar menor do que o tamanho dos pontos de dados, pode utilizar esta propriedade para definir se pretende mostrar as etiquetas de dados. Essa propriedade se aplica somente a gráficos 2D.
getStyle()	Especifica o estilo de 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, desde a margem superior do objeto até à parte superior da linha 1 (numa folha de cálculo) ou à parte superior da área do gráfico (num gráfico).
getWidth()	Especifica a largura, em pontos, do objeto de gráfico.
getWorksheet()	A planilha que contém o gráfico atual.
setCategoryLabelLevel(categoryLabelLevel)	Especifica uma constante de enumeração de nível de etiqueta de categoria de gráfico, referindo-se ao nível das etiquetas da categoria de origem.
setChartType(chartType)	Especifica o tipo do gráfico. Veja `ExcelScript.ChartType` para obter 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 desenhadas num gráfico.
setHeight(height)	Especifica a altura, em pontos, do objeto de 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 de 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 ao nível do nome da série de gráficos, referindo-se ao nível dos nomes das séries de origem.
setShowAllFieldButtons(showAllFieldButtons)	Especifica se pretende apresentar todos os botões de campo num gráfico dinâmico.
setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)	Especifica se pretende mostrar as etiquetas de dados quando o valor é maior do que o valor máximo no eixo de valores. Se o eixo de valores se tornar menor do que o tamanho dos pontos de dados, pode utilizar esta propriedade para definir se pretende mostrar as etiquetas de dados. Essa propriedade se aplica somente a gráficos 2D.
setStyle(style)	Especifica o estilo de gráfico para o gráfico.
setTop(top)	Especifica a distância, em pontos, desde a margem superior do objeto até à parte superior da linha 1 (numa folha de cálculo) ou à parte superior da área do gráfico (num gráfico).
setWidth(width)	Especifica a largura, em pontos, do objeto de 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 é visível até que os valores, os valores do eixo x ou os tamanhos das bolhas da mesma estejam 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 adicionar. 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 etiqueta de categoria de gráfico, referindo-se ao nível das etiquetas da categoria de origem.

getCategoryLabelLevel(): number;

Retornos

number

getChartType()

Especifica o tipo do gráfico. Veja ExcelScript.ChartType para obter 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, este método devolve undefined.

getDataTable(): ChartDataTable;

Retornos

ExcelScript.ChartDataTable

getDisplayBlanksAs()

Especifica a forma como as células em branco são desenhadas num 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 de 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 utilizado para dimensionar o gráfico para as dimensões especificadas (se a altura e a largura estiverem 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 de 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 desenho do 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 ao nível do nome da série de gráficos, referindo-se ao nível dos nomes das séries de origem.

getSeriesNameLevel(): number;

Retornos

number

getShowAllFieldButtons()

Especifica se pretende apresentar todos os botões de campo num gráfico dinâmico.

getShowAllFieldButtons(): boolean;

Retornos

boolean

getShowDataLabelsOverMaximum()

Especifica se pretende mostrar as etiquetas de dados quando o valor é maior do que o valor máximo no eixo de valores. Se o eixo de valores se tornar menor do que o tamanho dos pontos de dados, pode utilizar esta propriedade para definir se pretende mostrar as etiquetas de dados. Essa propriedade se aplica somente a gráficos 2D.

getShowDataLabelsOverMaximum(): boolean;

Retornos

boolean

getStyle()

Especifica o estilo de 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, desde a margem superior do objeto até à parte superior da linha 1 (numa folha de cálculo) ou à parte superior da área do gráfico (num gráfico).

getTop(): number;

Retornos

number

getWidth()

Especifica a largura, em pontos, do objeto de 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 etiqueta de categoria de gráfico, referindo-se ao nível das etiquetas da categoria de origem.

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parâmetros

categoryLabelLevel: number

Retornos

void

setChartType(chartType)

Especifica o tipo do gráfico. Veja ExcelScript.ChartType para obter 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 de intervalo 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: Automático (predefinição), Linhas e Colunas. Veja ExcelScript.ChartSeriesBy para obter detalhes.

Retornos

void

setDisplayBlanksAs(displayBlanksAs)

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

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parâmetros

displayBlanksAs: ExcelScript.ChartDisplayBlanksAs

Retornos

void

setHeight(height)

Especifica a altura, em pontos, do objeto de 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 de 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 ao nível do nome da série de gráficos, referindo-se ao nível dos nomes das séries de origem.

setSeriesNameLevel(seriesNameLevel: number): void;

Parâmetros

seriesNameLevel: number

Retornos

void

setShowAllFieldButtons(showAllFieldButtons)

Especifica se pretende apresentar todos os botões de campo num 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 de gráfico para o gráfico.

setStyle(style: number): void;

Parâmetros

style: number

Retornos

void

setTop(top)

Especifica a distância, em pontos, desde a margem superior do objeto até à parte superior da linha 1 (numa folha de cálculo) ou à parte superior da área do gráfico (num gráfico).

setTop(top: number): void;

Parâmetros

top: number

Retornos

void

setWidth(width)

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

setWidth(width: number): void;

Parâmetros

width: number

Retornos

void

Compartilhar via

ExcelScript.Chart interface

Métodos

Detalhes do método

activate()

Retornos

addChartSeries(name, index)

Parâmetros

Retornos

Exemplos

delete()

Retornos

getAxes()

Retornos

getCategoryLabelLevel()

Retornos

getChartType()

Retornos

getDataLabels()

Retornos

getDataTable()

Retornos

getDisplayBlanksAs()

Retornos

getFormat()

Retornos

getHeight()

Retornos

getId()

Retornos

getImage(width, height, fittingMode)

Parâmetros

Retornos

Exemplos

getLeft()

Retornos

getLegend()

Retornos

getName()

Retornos

getPivotOptions()

Retornos

getPlotArea()

Retornos

getPlotBy()

Retornos

Exemplos

getPlotVisibleOnly()

Retornos

getSeries()

Retornos

Exemplos

getSeriesNameLevel()

Retornos

getShowAllFieldButtons()

Retornos

getShowDataLabelsOverMaximum()

Retornos

getStyle()

Retornos

getTitle()

Retornos

getTop()

Retornos

getWidth()

Retornos

getWorksheet()

Retornos

setCategoryLabelLevel(categoryLabelLevel)

Parâmetros

Retornos

setChartType(chartType)

Parâmetros

Retornos

setData(sourceData, seriesBy)

Parâmetros

Retornos

setDisplayBlanksAs(displayBlanksAs)

Parâmetros

Retornos