ExcelScript.Chart interface

Referencia

Paquete:: ExcelScript

Representa un objeto de gráfico de una hoja de cálculo.

Métodos

activate()	Activa el gráfico en la interfaz de usuario de Excel.
addChartSeries(name, index)	Agrega una nueva serie a la colección. La nueva serie agregada no es visible hasta que se establecen valores, valores del eje X o tamaños de burbuja para ella (según el tipo de gráfico).
delete()	Elimina el objeto de gráfico.
getAxes()	Representa los ejes del gráfico.
getCategoryLabelLevel()	Especifica una constante de enumeración de nivel de etiqueta de categoría de gráfico, que hace referencia al nivel de las etiquetas de categoría de origen.
getChartType()	Especifica el tipo del gráfico. Vea `ExcelScript.ChartType` para más información.
getDataLabels()	Representa la clase DataLabels del gráfico.
getDataTable()	Obtiene la tabla de datos del gráfico. Si el gráfico no permite una tabla de datos, este método devuelve `undefined`.
getDisplayBlanksAs()	Especifica la forma en que las celdas en blanco se trazan en un gráfico.
getFormat()	Encapsula las propiedades de formato del área del gráfico.
getHeight()	Especifica el alto, en puntos, del objeto de gráfico.
getId()	Identificador único del gráfico.
getImage(width, height, fittingMode)	Representa el gráfico como una imagen con codificación Base64 al escalar el gráfico a las dimensiones especificadas. La relación de aspecto se conserva como parte del cambio de tamaño.
getLeft()	Distancia, en puntos, desde el lado izquierdo del gráfico hasta el origen de la hoja de cálculo.
getLegend()	Representa la leyenda del gráfico.
getName()	Especifica el nombre de un objeto de gráfico.
getPivotOptions()	Contiene las opciones del gráfico dinámico.
getPlotArea()	Representa el área de trazado del gráfico.
getPlotBy()	Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico.
getPlotVisibleOnly()	True si solo se trazan las celdas visibles. False si se trazan tanto las celdas visibles como las ocultas.
getSeries()	Representa una sola serie o una colección de series del gráfico.
getSeriesNameLevel()	Especifica una constante de enumeración de nivel de nombre de serie de gráfico, que hace referencia al nivel de los nombres de las series de origen.
getShowAllFieldButtons()	Especifica si se van a mostrar todos los botones de campo en un gráfico dinámico.
getShowDataLabelsOverMaximum()	Especifica si se muestran las etiquetas de datos cuando el valor es mayor que el valor máximo en el eje de valores. Si el eje de valores es menor que el tamaño de los puntos de datos, puede usar esta propiedad para establecer si desea mostrar las etiquetas de datos. Esta propiedad solo se aplica a gráficos 2D.
getStyle()	Especifica el estilo del gráfico.
getTitle()	Representa el título del gráfico especificado, incluido el texto, la visibilidad, la posición y el formato del título.
getTop()	Especifica la distancia, en puntos, desde el borde superior del objeto hasta la parte superior de la fila 1 (en una hoja de cálculo) o la parte superior del área del gráfico (en un gráfico).
getWidth()	Especifica el ancho, en puntos, del objeto de gráfico.
getWorksheet()	La hoja de cálculo que contiene el gráfico actual.
setCategoryLabelLevel(categoryLabelLevel)	Especifica una constante de enumeración de nivel de etiqueta de categoría de gráfico, que hace referencia al nivel de las etiquetas de categoría de origen.
setChartType(chartType)	Especifica el tipo del gráfico. Vea `ExcelScript.ChartType` para más información.
setData(sourceData, seriesBy)	Configura los datos de origen para el gráfico.
setDisplayBlanksAs(displayBlanksAs)	Especifica la forma en que las celdas en blanco se trazan en un gráfico.
setHeight(height)	Especifica el alto, en puntos, del objeto de gráfico.
setLeft(left)	Distancia, en puntos, desde el lado izquierdo del gráfico hasta el origen de la hoja de cálculo.
setName(name)	Especifica el nombre de un objeto de gráfico.
setPlotBy(plotBy)	Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico.
setPlotVisibleOnly(plotVisibleOnly)	True si solo se trazan las celdas visibles. False si se trazan tanto las celdas visibles como las ocultas.
setPosition(startCell, endCell)	Coloca el gráfico con respecto a las celdas de la hoja de cálculo.
setSeriesNameLevel(seriesNameLevel)	Especifica una constante de enumeración de nivel de nombre de serie de gráfico, que hace referencia al nivel de los nombres de las series de origen.
setShowAllFieldButtons(showAllFieldButtons)	Especifica si se van a mostrar todos los botones de campo en un gráfico dinámico.
setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)	Especifica si se muestran las etiquetas de datos cuando el valor es mayor que el valor máximo en el eje de valores. Si el eje de valores es menor que el tamaño de los puntos de datos, puede usar esta propiedad para establecer si desea mostrar las etiquetas de datos. Esta propiedad solo se aplica a gráficos 2D.
setStyle(style)	Especifica el estilo del gráfico.
setTop(top)	Especifica la distancia, en puntos, desde el borde superior del objeto hasta la parte superior de la fila 1 (en una hoja de cálculo) o la parte superior del área del gráfico (en un gráfico).
setWidth(width)	Especifica el ancho, en puntos, del objeto de gráfico.

Detalles del método

activate()

Activa el gráfico en la interfaz de usuario de Excel.

activate(): void;

Devoluciones

void

addChartSeries(name, index)

Agrega una nueva serie a la colección. La nueva serie agregada no es visible hasta que se establecen valores, valores del eje X o tamaños de burbuja para ella (según el tipo de gráfico).

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

Parámetros

name: string

Opcional. Nombre de la serie.

index: number

Opcional. Valor de índice de la serie que se va a agregar. Indizado con cero.

Devoluciones

ExcelScript.ChartSeries

Ejemplos

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

Elimina el objeto de gráfico.

delete(): void;

Devoluciones

void

getAxes()

Representa los ejes del gráfico.

getAxes(): ChartAxes;

Devoluciones

ExcelScript.ChartAxes

getCategoryLabelLevel()

Especifica una constante de enumeración de nivel de etiqueta de categoría de gráfico, que hace referencia al nivel de las etiquetas de categoría de origen.

getCategoryLabelLevel(): number;

Devoluciones

number

getChartType()

Especifica el tipo del gráfico. Vea ExcelScript.ChartType para más información.

getChartType(): ChartType;

Devoluciones

ExcelScript.ChartType

getDataLabels()

Representa la clase DataLabels del gráfico.

getDataLabels(): ChartDataLabels;

Devoluciones

ExcelScript.ChartDataLabels

getDataTable()

Obtiene la tabla de datos del gráfico. Si el gráfico no permite una tabla de datos, este método devuelve undefined.

getDataTable(): ChartDataTable;

Devoluciones

ExcelScript.ChartDataTable

getDisplayBlanksAs()

Especifica la forma en que las celdas en blanco se trazan en un gráfico.

getDisplayBlanksAs(): ChartDisplayBlanksAs;

Devoluciones

ExcelScript.ChartDisplayBlanksAs

getFormat()

Encapsula las propiedades de formato del área del gráfico.

getFormat(): ChartAreaFormat;

Devoluciones

ExcelScript.ChartAreaFormat

getHeight()

Especifica el alto, en puntos, del objeto de gráfico.

getHeight(): number;

Devoluciones

number

getId()

Identificador único del gráfico.

getId(): string;

Devoluciones

string

getImage(width, height, fittingMode)

Representa el gráfico como una imagen con codificación Base64 al escalar el gráfico a las dimensiones especificadas. La relación de aspecto se conserva como parte del cambio de tamaño.

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

Parámetros

width: number

Opcional. Ancho deseado de la imagen resultante.

height: number

Opcional. Alto deseado de la imagen resultante.

fittingMode: ExcelScript.ImageFittingMode

Opcional. Método utilizado para escalar el gráfico a las dimensiones especificadas (si se establecen tanto el alto como el ancho).

Devoluciones

string

Ejemplos

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

Distancia, en puntos, desde el lado izquierdo del gráfico hasta el origen de la hoja de cálculo.

getLeft(): number;

Devoluciones

number

getLegend()

Representa la leyenda del gráfico.

getLegend(): ChartLegend;

Devoluciones

ExcelScript.ChartLegend

getName()

Especifica el nombre de un objeto de gráfico.

getName(): string;

Devoluciones

string

getPivotOptions()

Contiene las opciones del gráfico dinámico.

getPivotOptions(): ChartPivotOptions;

Devoluciones

ExcelScript.ChartPivotOptions

getPlotArea()

Representa el área de trazado del gráfico.

getPlotArea(): ChartPlotArea;

Devoluciones

ExcelScript.ChartPlotArea

getPlotBy()

Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico.

getPlotBy(): ChartPlotBy;

Devoluciones

ExcelScript.ChartPlotBy

Ejemplos

/**
 * 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 si solo se trazan las celdas visibles. False si se trazan tanto las celdas visibles como las ocultas.

getPlotVisibleOnly(): boolean;

Devoluciones

boolean

getSeries()

Representa una sola serie o una colección de series del gráfico.

getSeries(): ChartSeries[];

Devoluciones

ExcelScript.ChartSeries[]

Ejemplos

/**
 * 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 una constante de enumeración de nivel de nombre de serie de gráfico, que hace referencia al nivel de los nombres de las series de origen.

getSeriesNameLevel(): number;

Devoluciones

number

getShowAllFieldButtons()

Especifica si se van a mostrar todos los botones de campo en un gráfico dinámico.

getShowAllFieldButtons(): boolean;

Devoluciones

boolean

getShowDataLabelsOverMaximum()

Especifica si se muestran las etiquetas de datos cuando el valor es mayor que el valor máximo en el eje de valores. Si el eje de valores es menor que el tamaño de los puntos de datos, puede usar esta propiedad para establecer si desea mostrar las etiquetas de datos. Esta propiedad solo se aplica a gráficos 2D.

getShowDataLabelsOverMaximum(): boolean;

Devoluciones

boolean

getStyle()

Especifica el estilo del gráfico.

getStyle(): number;

Devoluciones

number

getTitle()

Representa el título del gráfico especificado, incluido el texto, la visibilidad, la posición y el formato del título.

getTitle(): ChartTitle;

Devoluciones

ExcelScript.ChartTitle

getTop()

Especifica la distancia, en puntos, desde el borde superior del objeto hasta la parte superior de la fila 1 (en una hoja de cálculo) o la parte superior del área del gráfico (en un gráfico).

getTop(): number;

Devoluciones

number

getWidth()

Especifica el ancho, en puntos, del objeto de gráfico.

getWidth(): number;

Devoluciones

number

getWorksheet()

La hoja de cálculo que contiene el gráfico actual.

getWorksheet(): Worksheet;

Devoluciones

ExcelScript.Worksheet

setCategoryLabelLevel(categoryLabelLevel)

Especifica una constante de enumeración de nivel de etiqueta de categoría de gráfico, que hace referencia al nivel de las etiquetas de categoría de origen.

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parámetros

categoryLabelLevel: number

Devoluciones

void

setChartType(chartType)

Especifica el tipo del gráfico. Vea ExcelScript.ChartType para más información.

setChartType(chartType: ChartType): void;

Parámetros

chartType: ExcelScript.ChartType

Devoluciones

void

setData(sourceData, seriesBy)

Configura los datos de origen para el gráfico.

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

Parámetros

sourceData: ExcelScript.Range

Objeto de intervalo correspondiente a los datos de origen.

seriesBy: ExcelScript.ChartSeriesBy

Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico. Puede ser una de las siguientes: Auto (valor predeterminado), Filas y Columnas. Vea ExcelScript.ChartSeriesBy para más información.

Devoluciones

void

setDisplayBlanksAs(displayBlanksAs)

Especifica la forma en que las celdas en blanco se trazan en un gráfico.

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parámetros

displayBlanksAs: ExcelScript.ChartDisplayBlanksAs

Devoluciones

void

setHeight(height)

Especifica el alto, en puntos, del objeto de gráfico.

setHeight(height: number): void;

Parámetros

height: number

Devoluciones

void

setLeft(left)

Distancia, en puntos, desde el lado izquierdo del gráfico hasta el origen de la hoja de cálculo.

setLeft(left: number): void;

Parámetros

left: number

Devoluciones

void

setName(name)

Especifica el nombre de un objeto de gráfico.

setName(name: string): void;

Parámetros

name: string

Devoluciones

void

Ejemplos

/**
 * 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 la manera en que las columnas o las filas se usan como series de datos en el gráfico.

setPlotBy(plotBy: ChartPlotBy): void;

Parámetros

plotBy: ExcelScript.ChartPlotBy

Devoluciones

void

Ejemplos

/**
 * 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 si solo se trazan las celdas visibles. False si se trazan tanto las celdas visibles como las ocultas.

setPlotVisibleOnly(plotVisibleOnly: boolean): void;

Parámetros

plotVisibleOnly: boolean

Devoluciones

void

setPosition(startCell, endCell)

Coloca el gráfico con respecto a las celdas de la hoja de cálculo.

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

Parámetros

startCell: ExcelScript.Range | string

Celda de inicio. Aquí es adonde se moverá el gráfico. La celda de inicio es la celda superior izquierda o superior derecha, en función de la configuración del usuario de la presentación de derecha a izquierda.

endCell: ExcelScript.Range | string

Opcional. Última celda. Si se especifica, el ancho y el alto del gráfico se establecerán de modo que cubran totalmente esta celda o rango.

Devoluciones

void

Ejemplos

/**
 * 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 una constante de enumeración de nivel de nombre de serie de gráfico, que hace referencia al nivel de los nombres de las series de origen.

setSeriesNameLevel(seriesNameLevel: number): void;

Parámetros

seriesNameLevel: number

Devoluciones

void

setShowAllFieldButtons(showAllFieldButtons)

Especifica si se van a mostrar todos los botones de campo en un gráfico dinámico.

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

Parámetros

showAllFieldButtons: boolean

Devoluciones

void

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

Parámetros

showDataLabelsOverMaximum: boolean

Devoluciones

void

setStyle(style)

Especifica el estilo del gráfico.

setStyle(style: number): void;

Parámetros

style: number

Devoluciones

void

setTop(top)

Especifica la distancia, en puntos, desde el borde superior del objeto hasta la parte superior de la fila 1 (en una hoja de cálculo) o la parte superior del área del gráfico (en un gráfico).

setTop(top: number): void;

Parámetros

top: number

Devoluciones

void

setWidth(width)

Especifica el ancho, en puntos, del objeto de gráfico.

setWidth(width: number): void;

Parámetros

width: number

Devoluciones

void