Excel.ChartCollection class

  • Référence
Paquet:
excel

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

Extends
OfficeExtension.ClientObject

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

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.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.

É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

Facultatif. 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"

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