Excel.Chart class
Représente un objet de graphique dans un classeur. Pour en savoir plus sur le modèle objet de graphique, voir Utiliser des graphiques à l’aide de l’API JavaScript Excel.
- Extends
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Propriétés
axes | Représente les axes du graphique. |
category |
Spécifie une constante d’énumération de niveau d’étiquette de catégorie de graphique, faisant référence au niveau des étiquettes de catégorie source. |
chart |
Spécifie le type du graphique. Pour plus d’informations, consultez |
context | Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office. |
data |
Représente les étiquettes des données sur le graphique. |
display |
Spécifie la façon dont les cellules vides sont tracées sur un graphique. |
format | Regroupe les propriétés de format de la zone de graphique. |
height | Spécifie la hauteur, en points, de l’objet de graphique. |
id | L’ID unique du graphique. |
left | La distance, en points, entre le côté gauche du graphique et l’origine de la feuille de calcul. |
legend | Représente la légende du graphique. |
name | Spécifie le nom d’un objet graphique. |
plot |
Représente la zone de traçage du graphique. |
plot |
Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique. |
plot |
Vrai si seules les cellules visibles sont tracées. Faux si les deux cellules visibles et masquées sont tracées. |
series | Représente une série ou une collection de séries dans le graphique. |
series |
Spécifie une constante d’énumération de niveau de nom de série de graphique, faisant référence au niveau des noms des séries sources. |
show |
Spécifie s’il faut afficher tous les boutons de champ sur un graphique croisé dynamique. |
show |
Spécifie s’il faut afficher les étiquettes de données lorsque la valeur est supérieure à la valeur maximale sur l’axe des valeurs. Si l’axe des valeurs devient plus petit que la taille des points de données, vous pouvez utiliser cette propriété pour définir s’il faut afficher les étiquettes de données. Cette propriété s'applique uniquement aux graphiques 2D. |
style | Spécifie le style de graphique pour le graphique. |
title | Représente le titre du graphique indiqué et comprend le texte, la visibilité, la position et la mise en forme du titre. |
top | Spécifie la distance, en points, entre le bord supérieur de l’objet et le haut de la ligne 1 (dans une feuille de calcul) ou le haut de la zone de graphique (sur un graphique). |
width | Spécifie la largeur, en points, de l’objet graphique. |
worksheet | Feuille de calcul contenant le graphique actuel. |
Méthodes
delete() | Supprime l’objet de graphique. |
get |
Restitue le graphique sous la forme d’une image encodée en Base64 en le mettant à l’échelle pour qu’il s’adapte aux dimensions spécifiées. Les proportions sont conservées dans le cadre du redimensionnement. |
get |
Restitue le graphique sous la forme d’une image encodée en Base64 en le mettant à l’échelle pour qu’il s’adapte aux dimensions spécifiées. Les proportions sont conservées dans le cadre du redimensionnement. |
load(options) | Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter |
load(property |
Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter |
load(property |
Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter |
set(properties, options) | Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type. |
set(properties) | Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant. |
set |
Redéfinit les données sources du graphique. |
set |
Redéfinit les données sources du graphique. |
set |
Positionne le graphique par rapport aux cellules dans la feuille de calcul. |
toJSON() | Remplace la méthode JavaScript |
Événements
on |
Se produit lorsque le graphique est activé. |
on |
Se produit lorsque le graphique est désactivé. |
Détails de la propriété
axes
Représente les axes du graphique.
readonly axes: Excel.ChartAxes;
Valeur de propriété
Remarques
categoryLabelLevel
Spécifie une constante d’énumération de niveau d’étiquette de catégorie de graphique, faisant référence au niveau des étiquettes de catégorie source.
categoryLabelLevel: number;
Valeur de propriété
number
Remarques
chartType
Spécifie le type du graphique. Pour plus d’informations, consultez Excel.ChartType
.
chartType: Excel.ChartType | "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";
Valeur de propriété
Excel.ChartType | "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"
Remarques
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é
dataLabels
Représente les étiquettes des données sur le graphique.
readonly dataLabels: Excel.ChartDataLabels;
Valeur de propriété
Remarques
displayBlanksAs
Spécifie la façon dont les cellules vides sont tracées sur un graphique.
displayBlanksAs: Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted";
Valeur de propriété
Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted"
Remarques
format
Regroupe les propriétés de format de la zone de graphique.
readonly format: Excel.ChartAreaFormat;
Valeur de propriété
Remarques
height
Spécifie la hauteur, en points, de l’objet de graphique.
height: number;
Valeur de propriété
number
Remarques
id
L’ID unique du graphique.
readonly id: string;
Valeur de propriété
string
Remarques
left
La distance, en points, entre le côté gauche du graphique et l’origine de la feuille de calcul.
left: number;
Valeur de propriété
number
Remarques
legend
Représente la légende du graphique.
readonly legend: Excel.ChartLegend;
Valeur de propriété
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
// Set to show legend of Chart1 and make it on top of the chart.
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.legend.visible = true;
chart.legend.position = "Top";
chart.legend.overlay = false;
await context.sync()
console.log("Legend Shown ");
});
name
Spécifie le nom d’un objet graphique.
name: string;
Valeur de propriété
string
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
// Rename the chart to new name, resize the chart to 200 points in both height and weight.
// Move Chart1 to 100 points to the top and left.
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.name = "New Name";
chart.top = 100;
chart.left = 100;
chart.height = 200;
chart.width = 200;
await context.sync();
});
plotArea
Représente la zone de traçage du graphique.
readonly plotArea: Excel.ChartPlotArea;
Valeur de propriété
Remarques
plotBy
Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique.
plotBy: Excel.ChartPlotBy | "Rows" | "Columns";
Valeur de propriété
Excel.ChartPlotBy | "Rows" | "Columns"
Remarques
plotVisibleOnly
Vrai si seules les cellules visibles sont tracées. Faux si les deux cellules visibles et masquées sont tracées.
plotVisibleOnly: boolean;
Valeur de propriété
boolean
Remarques
series
Représente une série ou une collection de séries dans le graphique.
readonly series: Excel.ChartSeriesCollection;
Valeur de propriété
Remarques
seriesNameLevel
Spécifie une constante d’énumération de niveau de nom de série de graphique, faisant référence au niveau des noms des séries sources.
seriesNameLevel: number;
Valeur de propriété
number
Remarques
showAllFieldButtons
Spécifie s’il faut afficher tous les boutons de champ sur un graphique croisé dynamique.
showAllFieldButtons: boolean;
Valeur de propriété
boolean
Remarques
showDataLabelsOverMaximum
Spécifie s’il faut afficher les étiquettes de données lorsque la valeur est supérieure à la valeur maximale sur l’axe des valeurs. Si l’axe des valeurs devient plus petit que la taille des points de données, vous pouvez utiliser cette propriété pour définir s’il faut afficher les étiquettes de données. Cette propriété s'applique uniquement aux graphiques 2D.
showDataLabelsOverMaximum: boolean;
Valeur de propriété
boolean
Remarques
style
Spécifie le style de graphique pour le graphique.
style: number;
Valeur de propriété
number
Remarques
title
Représente le titre du graphique indiqué et comprend le texte, la visibilité, la position et la mise en forme du titre.
readonly title: Excel.ChartTitle;
Valeur de propriété
Remarques
top
Spécifie la distance, en points, entre le bord supérieur de l’objet et le haut de la ligne 1 (dans une feuille de calcul) ou le haut de la zone de graphique (sur un graphique).
top: number;
Valeur de propriété
number
Remarques
width
Spécifie la largeur, en points, de l’objet graphique.
width: number;
Valeur de propriété
number
Remarques
worksheet
Feuille de calcul contenant le graphique actuel.
readonly worksheet: Excel.Worksheet;
Valeur de propriété
Remarques
Détails de la méthode
delete()
Supprime l’objet de graphique.
delete(): void;
Retours
void
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.delete();
await context.sync();
});
getImage(width, height, fittingMode)
Restitue le graphique sous la forme d’une image encodée en Base64 en le mettant à l’échelle pour qu’il s’adapte aux dimensions spécifiées. Les proportions sont conservées dans le cadre du redimensionnement.
getImage(width?: number, height?: number, fittingMode?: Excel.ImageFittingMode): OfficeExtension.ClientResult<string>;
Paramètres
- width
-
number
Optional. Largeur souhaitée de l’image produite.
- height
-
number
Optional. Hauteur souhaitée de l’image produite.
- fittingMode
- Excel.ImageFittingMode
Optional. Méthode utilisée pour mettre à l’échelle le graphique aux dimensions spécifiées (si la hauteur et la largeur sont définies).
Retours
OfficeExtension.ClientResult<string>
Remarques
[ Ensemble d’API : ExcelApi 1.2 ]
Exemples
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
const image = chart.getImage();
await context.sync();
});
getImage(width, height, fittingModeString)
Restitue le graphique sous la forme d’une image encodée en Base64 en le mettant à l’échelle pour qu’il s’adapte aux dimensions spécifiées. Les proportions sont conservées dans le cadre du redimensionnement.
getImage(width?: number, height?: number, fittingModeString?: "Fit" | "FitAndCenter" | "Fill"): OfficeExtension.ClientResult<string>;
Paramètres
- width
-
number
Optional. Largeur souhaitée de l’image produite.
- height
-
number
Optional. Hauteur souhaitée de l’image produite.
- fittingModeString
-
"Fit" | "FitAndCenter" | "Fill"
Optional. Méthode utilisée pour mettre à l’échelle le graphique aux dimensions spécifiées (si la hauteur et la largeur sont définies).
Retours
OfficeExtension.ClientResult<string>
Remarques
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.ChartLoadOptions): Excel.Chart;
Paramètres
Fournit des options pour les propriétés de l’objet à charger.
Retours
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.Chart;
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
Exemples
// Get a chart named "Chart1".
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.load('name');
await context.sync();
console.log(chart.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?: {
select?: string;
expand?: string;
}): Excel.Chart;
Paramètres
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
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
set(properties, options)
Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.
set(properties: Interfaces.ChartUpdateData, options?: OfficeExtension.UpdateOptions): void;
Paramètres
- properties
- Excel.Interfaces.ChartUpdateData
Objet JavaScript avec des propriétés qui sont structurées isomorphes en fonction des propriétés de l’objet sur lequel la méthode est appelée.
- options
- OfficeExtension.UpdateOptions
Fournit une option permettant de supprimer les erreurs si l’objet properties tente de définir des propriétés en lecture seule.
Retours
void
set(properties)
Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.
set(properties: Excel.Chart): void;
Paramètres
- properties
- Excel.Chart
Retours
void
setData(sourceData, seriesBy)
Redéfinit les données sources du graphique.
setData(sourceData: Range, seriesBy?: Excel.ChartSeriesBy): void;
Paramètres
- sourceData
- Excel.Range
Objet de plage correspondant aux données sources.
- seriesBy
- Excel.ChartSeriesBy
Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique. Il peut s’agir de l’un des éléments suivants : Auto (valeur par défaut), Lignes et Colonnes. Pour plus d’informations, consultez Excel.ChartSeriesBy
.
Retours
void
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
// Set the sourceData to be the range at "A1:B4" and seriesBy to be "Columns".
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sheet1");
const chart = sheet.charts.getItem("Chart1");
const sourceData = sheet.getRange("A1:B4");
chart.setData(sourceData, "Columns");
await context.sync();
});
setData(sourceData, seriesByString)
Redéfinit les données sources du graphique.
setData(sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): void;
Paramètres
- sourceData
- Excel.Range
Objet de plage correspondant aux données sources.
- seriesByString
-
"Auto" | "Columns" | "Rows"
Spécifie la façon dont les colonnes ou les lignes sont utilisées comme séries de données sur le graphique. Il peut s’agir de l’un des éléments suivants : Auto (valeur par défaut), Lignes et Colonnes. Pour plus d’informations, consultez Excel.ChartSeriesBy
.
Retours
void
Remarques
setPosition(startCell, endCell)
Positionne le graphique par rapport aux cellules dans la feuille de calcul.
setPosition(startCell: Range | string, endCell?: Range | string): void;
Paramètres
- startCell
-
Excel.Range | string
Cellule de début. Il s’agit de l’emplacement où le graphique sera déplacé. La cellule de début est la cellule supérieure gauche ou supérieure droite, selon les paramètres d’affichage droite-gauche définis par l’utilisateur.
- endCell
-
Excel.Range | string
Optional. Cellule de fin. Si une valeur est indiquée, la largeur et la hauteur du graphique seront définies de manière à couvrir entièrement cette cellule/plage.
Retours
void
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
await Excel.run(async (context) => {
const sheetName = "Charts";
const rangeSelection = "A1:B4";
const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeSelection);
const sourceData = sheetName + "!" + "A1:B4";
const chart = context.workbook.worksheets.getItem(sheetName).charts.add("pie", range, "auto");
chart.width = 500;
chart.height = 300;
chart.setPosition("C2", null);
await context.sync();
});
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.Chart
est un objet API, la toJSON
méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.ChartData
que ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.
toJSON(): Excel.Interfaces.ChartData;
Retours
Détails de l'événement
onActivated
Se produit lorsque le graphique est activé.
readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;
Type d'événement
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}.`);
});
}
onDeactivated
Se produit lorsque le graphique est désactivé.
readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;
Type d'événement
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.");
});
}