Excel.ChartCollection class

Référence

Paquet:: excel

Collection de tous les objets de graphique d’une feuille de calcul.

Extends: OfficeExtension.ClientObject

Remarques

Propriétés

context	Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.
count	Renvoie le nombre de graphiques dans la feuille de calcul.
items	Obtient l’élément enfant chargé dans cette collection de sites.

Méthodes

add(type, sourceData, seriesBy)	Crée un graphique.
add(typeString, sourceData, seriesByString)	Crée un graphique.
getCount()	Renvoie le nombre de graphiques dans la feuille de calcul.
getItem(name)	Extrait un graphique à l’aide de son nom. Si plusieurs graphiques portent le même nom, c’est le premier d’entre eux qui est renvoyé.
getItemAt(index)	Extrait un graphique en fonction de sa position dans la collection.
getItemOrNullObject(name)	Extrait un graphique à l’aide de son nom. Si plusieurs graphiques portent le même nom, c’est le premier d’entre eux qui est renvoyé. Si le graphique n’existe pas, cette méthode retourne un objet avec sa `isNullObject` propriété définie sur `true`. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.
load(options)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNames)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNamesAndPaths)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
toJSON()	Remplace la méthode JavaScript `toJSON()` afin de fournir une sortie plus utile lorsqu’un objet API est passé à `JSON.stringify()`. (`JSON.stringify`appelle à son tour la `toJSON` méthode de l’objet qui lui est passé.) Alors que l’objet d’origine `Excel.ChartCollection` est un objet API, la `toJSON` méthode renvoie un objet JavaScript brut (typé en tant `Excel.Interfaces.ChartCollectionData`que ) qui contient un tableau « items » avec des copies superficielles de toutes les propriétés chargées à partir des éléments de la collection.

Événements

onActivated	Se produit lorsqu’un graphique est activé.
onAdded	Se produit lorsqu’un nouveau graphique est ajouté à la feuille de calcul.
onDeactivated	Se produit lorsqu’un graphique est désactivé.
onDeleted	Se produit lorsqu’un graphique est supprimé.

Détails de la propriété

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

context: RequestContext;

Valeur de propriété

Excel.RequestContext

count

Renvoie le nombre de graphiques dans la feuille de calcul.

readonly count: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

items

Obtient l’élément enfant chargé dans cette collection de sites.

readonly items: Excel.Chart[];

Valeur de propriété

Excel.Chart[]

Détails de la méthode

add(type, sourceData, seriesBy)

Crée un graphique.

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

Paramètres

type: Excel.ChartType

Représente le type d’un graphique. Pour plus d’informations, consultez Excel.ChartType .

sourceData: Excel.Range

Objet Range correspondant aux données sources.

seriesBy: Excel.ChartSeriesBy

Optional. Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique. Pour plus d’informations, consultez Excel.ChartSeriesBy .

Retours

Excel.Chart

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

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

Crée un graphique.

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;

Paramètres

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"

Représente le type d’un graphique. Pour plus d’informations, consultez Excel.ChartType .

sourceData: Excel.Range

Objet Range correspondant aux données sources.

seriesByString: "Auto" | "Columns" | "Rows"

Optional. Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique. Pour plus d’informations, consultez Excel.ChartSeriesBy .

Retours

Excel.Chart

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

getCount()

Renvoie le nombre de graphiques dans la feuille de calcul.

getCount(): OfficeExtension.ClientResult<number>;

Retours

OfficeExtension.ClientResult<number>

Remarques

[ Ensemble d’API : ExcelApi 1.4 ]

getItem(name)

Extrait un graphique à l’aide de son nom. Si plusieurs graphiques portent le même nom, c’est le premier d’entre eux qui est renvoyé.

getItem(name: string): Excel.Chart;

Paramètres

name: string

Nom du graphique à extraire.

Retours

Excel.Chart

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

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

Extrait un graphique en fonction de sa position dans la collection.

getItemAt(index: number): Excel.Chart;

Paramètres

index: number

Valeur d’indice de l’objet à récupérer. Avec indice zéro.

Retours

Excel.Chart

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

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)

Extrait un graphique à l’aide de son nom. Si plusieurs graphiques portent le même nom, c’est le premier d’entre eux qui est renvoyé. Si le graphique n’existe pas, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getItemOrNullObject(name: string): Excel.Chart;

Paramètres

name: string

Nom du graphique à extraire.

Retours

Excel.Chart

Remarques

[ Ensemble d’API : ExcelApi 1.4 ]

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

options: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

Fournit des options pour les propriétés de l’objet à charger.

Retours

Excel.ChartCollection

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

propertyNames: string | string[]

Chaîne délimitée par des virgules ou tableau de chaînes qui spécifient les propriétés à charger.

Retours

Excel.ChartCollection

Exemples

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)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

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

Paramètres

propertyNamesAndPaths: OfficeExtension.LoadOption

propertyNamesAndPaths.select est une chaîne délimitée par des virgules qui spécifie les propriétés à charger, et propertyNamesAndPaths.expand est une chaîne délimitée par des virgules qui spécifie les propriétés de navigation à charger.

Retours

Excel.ChartCollection

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringifyappelle à son tour la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine Excel.ChartCollection est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.ChartCollectionDataque ) qui contient un tableau « items » avec des copies superficielles de toutes les propriétés chargées à partir des éléments de la collection.

toJSON(): Excel.Interfaces.ChartCollectionData;

Retours

Excel.Interfaces.ChartCollectionData

Détails de l'événement

onActivated

Se produit lorsqu’un graphique est activé.

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

Type d'événement

OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.8 ]

Exemples

// 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 produit lorsqu’un nouveau graphique est ajouté à la feuille de calcul.

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

Type d'événement

OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.8 ]

Exemples

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 produit lorsqu’un graphique est désactivé.

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

Type d'événement

OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.8 ]

Exemples

// 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 produit lorsqu’un graphique est supprimé.

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

Type d'événement

OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>

Remarques

[ Ensemble d’API : ExcelApi 1.8 ]

Exemples

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

Partager via

Excel.ChartCollection class

Remarques

Propriétés

Méthodes

Événements

Détails de la propriété

context

Valeur de propriété

count

Valeur de propriété

Remarques

items

Valeur de propriété

Détails de la méthode

add(type, sourceData, seriesBy)

Paramètres

Retours

Remarques

Exemples

add(typeString, sourceData, seriesByString)

Paramètres

Retours

Remarques

getCount()

Retours

Remarques

getItem(name)

Paramètres

Retours

Remarques

Exemples

getItemAt(index)

Paramètres

Retours

Remarques

Exemples

getItemOrNullObject(name)

Paramètres

Retours

Remarques

load(options)

Paramètres

Retours

load(propertyNames)

Paramètres

Retours

Exemples

load(propertyNamesAndPaths)

Paramètres

Retours

toJSON()

Retours

Détails de l'événement

onActivated

Type d'événement

Remarques

Exemples

onAdded

Type d'événement

Remarques

Exemples

onDeactivated

Type d'événement

Remarques

Exemples

onDeleted

Type d'événement

Remarques

Exemples

Ressources supplémentaires