Compartir a través de

Excel.ChartCollection class

  • Referencia
Paquete:
excel

Colección de todos los objetos de gráfico en una hoja de cálculo.

Extends
OfficeExtension.ClientObject

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Propiedades

context

Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.
count

Devuelve el número de gráficos de la hoja de cálculo.
items

Obtiene los elementos secundarios cargados en esta colección.

Métodos

add(type, sourceData, seriesBy)

Crea un nuevo gráfico.
add(typeString, sourceData, seriesByString)

Crea un nuevo gráfico.
getCount()

Devuelve el número de gráficos de la hoja de cálculo.
getItem(name)

Obtiene un gráfico mediante su nombre. Si hay varias tablas con el mismo nombre, se devolverá la primera.
getItemAt(index)

Obtiene un gráfico en función de su posición en la colección.
getItemOrNullObject(name)

Obtiene un gráfico mediante su nombre. Si hay varias tablas con el mismo nombre, se devolverá la primera. Si el gráfico no existe, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
load(options)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
load(propertyNames)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
load(propertyNamesAndPaths)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.
toJSON()

Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto original Excel.ChartCollection es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ChartCollectionData) que contiene una matriz de "elementos" con copias superficiales de las propiedades cargadas de los elementos de la colección.

Eventos

onActivated

Se produce cuando se activa un gráfico.
onAdded

Se produce cuando se agrega un nuevo gráfico a la hoja de cálculo.
onDeactivated

Se produce cuando se desactiva un gráfico.
onDeleted

Se produce cuando se elimina un gráfico.

Detalles de las propiedades

context

Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.

context: RequestContext;

Valor de propiedad

Excel.RequestContext

count

Devuelve el número de gráficos de la hoja de cálculo.

readonly count: number;

Valor de propiedad

number

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

items

Obtiene los elementos secundarios cargados en esta colección.

readonly items: Excel.Chart[];

Valor de propiedad

Excel.Chart[]

Detalles del método

add(type, sourceData, seriesBy)

Crea un nuevo gráfico.

add(type: Excel.ChartType, sourceData: Range, seriesBy?: Excel.ChartSeriesBy): Excel.Chart;

Parámetros

type
Excel.ChartType

Representa el tipo de un gráfico. Vea Excel.ChartType para más información.

sourceData
Excel.Range

Objeto Range correspondiente a los datos de origen.

seriesBy
Excel.ChartSeriesBy

Opcional. Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico. Vea Excel.ChartSeriesBy para más información.

Devoluciones

Excel.Chart

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

// Add a chart of chartType "ColumnClustered" on worksheet "Charts" 
// with sourceData from range "A1:B4" and seriesBy set to "auto".
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sheet1");
    const rangeSelection = "A1:B4";
    const range = sheet.getRange(rangeSelection);
    const chart = sheet.charts.add(
    Excel.ChartType.columnClustered, 
    range, 
    Excel.ChartSeriesBy.auto);
    await context.sync();

    console.log("New Chart Added");
});

add(typeString, sourceData, seriesByString)

Crea un nuevo gráfico.

add(typeString: "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel", sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): Excel.Chart;

Parámetros

typeString

"Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel"

Representa el tipo de un gráfico. Vea Excel.ChartType para más información.

sourceData
Excel.Range

Objeto Range correspondiente a los datos de origen.

seriesByString

"Auto" | "Columns" | "Rows"

Opcional. Especifica la manera en que las columnas o las filas se usan como series de datos en el gráfico. Vea Excel.ChartSeriesBy para más información.

Devoluciones

Excel.Chart

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

getCount()

Devuelve el número de gráficos de la hoja de cálculo.

getCount(): OfficeExtension.ClientResult<number>;

Devoluciones

OfficeExtension.ClientResult<number>

Comentarios

[ Conjunto de API: ExcelApi 1.4 ]

getItem(name)

Obtiene un gráfico mediante su nombre. Si hay varias tablas con el mismo nombre, se devolverá la primera.

getItem(name: string): Excel.Chart;

Parámetros

name

string

Nombre del gráfico que se va a recuperar.

Devoluciones

Excel.Chart

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

// Get the number of charts.
await Excel.run(async (context) => { 
    const charts = context.workbook.worksheets.getItem("Sheet1").charts;
    charts.load('count');
    await context.sync();
    
    console.log("charts: Count= " + charts.count);
});

getItemAt(index)

Obtiene un gráfico en función de su posición en la colección.

getItemAt(index: number): Excel.Chart;

Parámetros

index

number

Valor de índice del objeto que se va a recuperar. Indizado con cero.

Devoluciones

Excel.Chart

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Ejemplos

await Excel.run(async (context) => { 
    const lastPosition = context.workbook.worksheets.getItem("Sheet1").charts.count - 1;
    const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItemAt(lastPosition);
    await context.sync();

    console.log(chart.name);
});

getItemOrNullObject(name)

Obtiene un gráfico mediante su nombre. Si hay varias tablas con el mismo nombre, se devolverá la primera. Si el gráfico no existe, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).

getItemOrNullObject(name: string): Excel.Chart;

Parámetros

name

string

Nombre del gráfico que se va a recuperar.

Devoluciones

Excel.Chart

Comentarios

[ Conjunto de API: ExcelApi 1.4 ]

load(options)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

load(options?: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.ChartCollection;

Parámetros

options

Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

Proporciona opciones para las propiedades del objeto que se van a cargar.

Devoluciones

Excel.ChartCollection

load(propertyNames)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

load(propertyNames?: string | string[]): Excel.ChartCollection;

Parámetros

propertyNames

string | string[]

Una cadena delimitada por comas o una matriz de cadenas que especifican las propiedades que se van a cargar.

Devoluciones

Excel.ChartCollection

Ejemplos

await Excel.run(async (context) => { 
    const charts = context.workbook.worksheets.getItem("Sheet1").charts;
    charts.load('items');
    await context.sync();
    
    for (let i = 0; i < charts.items.length; i++) {
        console.log(charts.items[i].name);
    }
});

load(propertyNamesAndPaths)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.ChartCollection;

Parámetros

propertyNamesAndPaths
OfficeExtension.LoadOption

propertyNamesAndPaths.select es una cadena delimitada por comas que especifica las propiedades que se van a cargar y propertyNamesAndPaths.expand es una cadena delimitada por comas que especifica las propiedades de navegación que se van a cargar.

Devoluciones

Excel.ChartCollection

toJSON()

Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto original Excel.ChartCollection es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.ChartCollectionData) que contiene una matriz de "elementos" con copias superficiales de las propiedades cargadas de los elementos de la colección.

toJSON(): Excel.Interfaces.ChartCollectionData;

Devoluciones

Excel.Interfaces.ChartCollectionData

Detalles del evento

onActivated

Se produce cuando se activa un gráfico.

readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.8 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml

await Excel.run(async (context) => {

    const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");

    // Register the onActivated and onDeactivated event handlers.
    pieChart.onActivated.add(chartActivated);
    pieChart.onDeactivated.add(chartDeactivated);

    await context.sync();

    console.log("Added handlers for Chart onActivated and onDeactivated events.");
});

...

async function chartActivated(event) {
    await Excel.run(async (context) => {
        // Retrieve the worksheet.
        const sheet = context.workbook.worksheets.getActiveWorksheet();

        // Retrieve the activated chart by ID and load the name of the chart. 
        const activatedChart = sheet.charts.getItem(event.chartId);
        activatedChart.load(["name"]);
        await context.sync();

        // Print out the activated chart's data.
        console.log(`A chart was activated. ID: ${event.chartId}. Chart name: ${activatedChart.name}.`);
    });
}

onAdded

Se produce cuando se agrega un nuevo gráfico a la hoja de cálculo.

readonly onAdded: OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.8 ]

Ejemplos

await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet()
        .charts.onAdded.add(function (event) {
        return Excel.run(async (context) => {
            console.log("A chart has been added with ID: " + event.chartId);
            await context.sync();
        });
    });
    await context.sync();
});

onDeactivated

Se produce cuando se desactiva un gráfico.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.8 ]

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml

await Excel.run(async (context) => {

    const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");

    // Register the onActivated and onDeactivated event handlers.
    pieChart.onActivated.add(chartActivated);
    pieChart.onDeactivated.add(chartDeactivated);

    await context.sync();

    console.log("Added handlers for Chart onActivated and onDeactivated events.");
});

...

async function chartDeactivated(event) {
    await Excel.run(async (context) => {
        // Callback function for when the chart is deactivated.
        console.log("The pie chart is NOT active.");
    });
}

onDeleted

Se produce cuando se elimina un gráfico.

readonly onDeleted: OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>;

Tipo de evento

OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>

Comentarios

[ Conjunto de API: ExcelApi 1.8 ]

Ejemplos

await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet()
        .charts.onDeleted.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The chart with this ID was deleted: " + event.chartId);
            await context.sync();
        });
    });
    await context.sync();
});