Excel.Workbook class
Workbook est l’objet de niveau supérieur qui contient des objets de classeur associés tels que des feuilles de calcul, des tableaux et des plages. Pour en savoir plus sur le modèle objet de classeur, consultez Utiliser des classeurs à l’aide de l’API JavaScript Excel.
- Extends
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Propriétés
application | Représente l’application Excel instance qui contient ce classeur. |
auto |
Spécifie si le classeur est en mode Enregistrement automatique. |
bindings | Représente une collection de liaisons appartenant au classeur. |
calculation |
Renvoie un nombre sur la version de moteur de calcul Excel. |
chart |
True si tous les graphiques dans le classeur suivent les points de données réelles auquel qu’il sont joints. False si les graphiques suivent l’index des points de données. |
comments | Représente une collection de commentaires associés au classeur. |
context | Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office. |
custom |
Représente la collection de parties XML personnalisées contenues dans ce classeur. |
data |
Représente toutes les connexions de données dans le classeur. |
functions | Représente une collection de fonctions de feuille de calcul qui peuvent être utilisées pour le calcul. |
is |
Spécifie si des modifications ont été apportées depuis le dernier enregistrement du classeur. Vous pouvez définir cette propriété |
linked |
Retourne une collection de classeurs liés. Dans les formules, les liens de classeur peuvent être utilisés pour référencer des données (valeurs de cellule et noms) en dehors du classeur actif. |
name | Obtient le nom du classeur. |
names | Représente une collection d’éléments nommés de portée classeur (plages et constantes nommées). |
pivot |
Représente une collection de tableaux croisés dynamiques associés au classeur. |
pivot |
Représente une collection de PivotTableStyles associée au classeur. |
previously |
Spécifie si le classeur a déjà été enregistré localement ou en ligne. |
properties | Obtient les propriétés du classeur. |
protection | Retourne l’objet de protection d’un classeur. |
queries | Retourne une collection de requêtes Power Query qui font partie du classeur. |
read |
Retourne |
settings | Représente une collection de paramètres associés au classeur. |
slicers | Représente une collection de segments associés au classeur. |
slicer |
Représente une collection de styles associés au classeur. |
styles | Représente une collection de styles associés au classeur. |
tables | Représente une collection de tableaux associés au classeur. |
table |
Représente une collection de TableStyles associés au classeur. |
timeline |
Représente une collection de TimelineStyles associés au classeur. |
use |
True si les calculs réalisés dans ce classeur utiliseront uniquement la précision des nombres tels qu’ils sont affichés. Les données perdent définitivement en précision lors du basculement de cette propriété de |
worksheets | Représente une collection de feuilles de calcul associées au classeur. |
Méthodes
close(close |
Fermer le classeur actif. |
close(close |
Fermer le classeur actif. |
get |
Obtient la cellule active du classeur. |
get |
Obtient la feuille de calcul active du classeur. S’il n’y a pas de graphique actif, une |
get |
Obtient la feuille de calcul active du classeur. S’il n’existe aucun graphique actif, cette méthode retourne un objet avec sa |
get |
Obtient le segment actif actuel du classeur. S’il n’y a pas de segment actif, une |
get |
Obtient le segment actif actuel du classeur. S’il n’existe aucun segment actif, cette méthode retourne un objet avec sa |
get |
Retourne |
get |
Retourne un |
get |
Obtient la plage unique actuellement sélectionnée à partir du classeur. Si plusieurs plages sont sélectionnées, cette méthode génère une erreur. |
get |
Obtient la ou les plage(s) sélectionnée(s) actuelle(s) dans le classeur. Contrairement à |
insert |
Insère les feuilles de calcul spécifiées à partir d’un classeur source dans le classeur actif. Remarque* : Cette API est actuellement prise en charge uniquement pour Office sur Windows, Mac et le web. |
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 |
save(save |
Enregistrer le classeur actif. |
save(save |
Enregistrer le classeur actif. |
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. |
toJSON() | Remplace la méthode JavaScript |
Événements
on |
Se produit lorsque le classeur est activé. Remarque : Cet événement ne se déclenche pas lorsque le classeur est ouvert. |
on |
Se produit lorsque le paramètre Enregistrement automatique est modifié sur le classeur. |
on |
Se produit quand la sélection change dans le document. |
Détails de la propriété
application
Représente l’application Excel instance qui contient ce classeur.
readonly application: Excel.Application;
Valeur de propriété
Remarques
autoSave
Spécifie si le classeur est en mode Enregistrement automatique.
readonly autoSave: boolean;
Valeur de propriété
boolean
Remarques
bindings
Représente une collection de liaisons appartenant au classeur.
readonly bindings: Excel.BindingCollection;
Valeur de propriété
Remarques
calculationEngineVersion
Renvoie un nombre sur la version de moteur de calcul Excel.
readonly calculationEngineVersion: number;
Valeur de propriété
number
Remarques
chartDataPointTrack
True si tous les graphiques dans le classeur suivent les points de données réelles auquel qu’il sont joints. False si les graphiques suivent l’index des points de données.
chartDataPointTrack: boolean;
Valeur de propriété
boolean
Remarques
comments
Représente une collection de commentaires associés au classeur.
readonly comments: Excel.CommentCollection;
Valeur de propriété
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é
customXmlParts
Représente la collection de parties XML personnalisées contenues dans ce classeur.
readonly customXmlParts: Excel.CustomXmlPartCollection;
Valeur de propriété
Remarques
dataConnections
Représente toutes les connexions de données dans le classeur.
readonly dataConnections: Excel.DataConnectionCollection;
Valeur de propriété
Remarques
functions
Représente une collection de fonctions de feuille de calcul qui peuvent être utilisées pour le calcul.
readonly functions: Excel.Functions;
Valeur de propriété
Remarques
isDirty
Spécifie si des modifications ont été apportées depuis le dernier enregistrement du classeur. Vous pouvez définir cette propriété true
sur si vous souhaitez fermer un classeur modifié sans l’enregistrer ou sans être invité à l’enregistrer.
isDirty: boolean;
Valeur de propriété
boolean
Remarques
linkedWorkbooks
Retourne une collection de classeurs liés. Dans les formules, les liens de classeur peuvent être utilisés pour référencer des données (valeurs de cellule et noms) en dehors du classeur actif.
readonly linkedWorkbooks: Excel.LinkedWorkbookCollection;
Valeur de propriété
Remarques
name
Obtient le nom du classeur.
readonly name: string;
Valeur de propriété
string
Remarques
names
Représente une collection d’éléments nommés de portée classeur (plages et constantes nommées).
readonly names: Excel.NamedItemCollection;
Valeur de propriété
Remarques
pivotTables
Représente une collection de tableaux croisés dynamiques associés au classeur.
readonly pivotTables: Excel.PivotTableCollection;
Valeur de propriété
Remarques
[ Ensemble d’API : ExcelApi 1.3 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml
await Excel.run(async (context) => {
// Get the names of all the PivotTables in the workbook.
const pivotTables = context.workbook.pivotTables;
pivotTables.load("name");
await context.sync();
// Display the names in the console.
console.log("PivotTables in the workbook:")
pivotTables.items.forEach((pivotTable) => {
console.log(`\t${pivotTable.name}`);
});
});
pivotTableStyles
Représente une collection de PivotTableStyles associée au classeur.
readonly pivotTableStyles: Excel.PivotTableStyleCollection;
Valeur de propriété
Remarques
previouslySaved
Spécifie si le classeur a déjà été enregistré localement ou en ligne.
readonly previouslySaved: boolean;
Valeur de propriété
boolean
Remarques
properties
Obtient les propriétés du classeur.
readonly properties: Excel.DocumentProperties;
Valeur de propriété
Remarques
[ Ensemble d’API : ExcelApi 1.7 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/properties.yaml
await Excel.run(async (context) => {
let titleValue = "Excel document properties API";
let subjectValue = "Set and get document properties";
let keywordsValue = "Set and get operations";
let commentsValue = "This is an Excel document properties API code sample";
let categoryValue = "Office Add-ins";
let managerValue = "John";
let companyValue = "Microsoft";
let docProperties = context.workbook.properties;
// Set the writeable document properties.
docProperties.title = titleValue;
docProperties.subject = subjectValue;
docProperties.keywords = keywordsValue;
docProperties.comments = commentsValue;
docProperties.category = categoryValue;
docProperties.manager = managerValue;
docProperties.company = companyValue;
await context.sync();
console.log("Set the following document properties: title, subject, keywords, comments, category, manager, company.");
});
protection
Retourne l’objet de protection d’un classeur.
readonly protection: Excel.WorkbookProtection;
Valeur de propriété
Remarques
queries
Retourne une collection de requêtes Power Query qui font partie du classeur.
readonly queries: Excel.QueryCollection;
Valeur de propriété
Remarques
readOnly
Retourne true
si le classeur est ouvert en mode lecture seule.
readonly readOnly: boolean;
Valeur de propriété
boolean
Remarques
settings
Représente une collection de paramètres associés au classeur.
readonly settings: Excel.SettingCollection;
Valeur de propriété
Remarques
slicers
Représente une collection de segments associés au classeur.
readonly slicers: Excel.SlicerCollection;
Valeur de propriété
Remarques
slicerStyles
Représente une collection de styles associés au classeur.
readonly slicerStyles: Excel.SlicerStyleCollection;
Valeur de propriété
Remarques
styles
Représente une collection de styles associés au classeur.
readonly styles: Excel.StyleCollection;
Valeur de propriété
Remarques
[ Ensemble d’API : ExcelApi 1.7 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml
await Excel.run(async (context) => {
let styles = context.workbook.styles;
// Add a new style to the style collection.
// Styles is in the Home tab ribbon.
styles.add("Diagonal Orientation Style");
let newStyle = styles.getItem("Diagonal Orientation Style");
// The "Diagonal Orientation Style" properties.
newStyle.textOrientation = 38;
newStyle.autoIndent = true;
newStyle.includeProtection = true;
newStyle.shrinkToFit = true;
newStyle.locked = false;
await context.sync();
console.log("Successfully added a new style with diagonal orientation to the Home tab ribbon.");
});
tables
Représente une collection de tableaux associés au classeur.
readonly tables: Excel.TableCollection;
Valeur de propriété
Remarques
tableStyles
Représente une collection de TableStyles associés au classeur.
readonly tableStyles: Excel.TableStyleCollection;
Valeur de propriété
Remarques
timelineStyles
Représente une collection de TimelineStyles associés au classeur.
readonly timelineStyles: Excel.TimelineStyleCollection;
Valeur de propriété
Remarques
usePrecisionAsDisplayed
True si les calculs réalisés dans ce classeur utiliseront uniquement la précision des nombres tels qu’ils sont affichés. Les données perdent définitivement en précision lors du basculement de cette propriété de false
à true
.
usePrecisionAsDisplayed: boolean;
Valeur de propriété
boolean
Remarques
worksheets
Représente une collection de feuilles de calcul associées au classeur.
readonly worksheets: Excel.WorksheetCollection;
Valeur de propriété
Remarques
Détails de la méthode
close(closeBehavior)
Fermer le classeur actif.
close(closeBehavior?: Excel.CloseBehavior): void;
Paramètres
- closeBehavior
- Excel.CloseBehavior
comportement de fermeture du classeur.
Retours
void
Remarques
[ Ensemble d’API : ExcelApi 1.11 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml
await Excel.run(async (context) => {
context.workbook.close(Excel.CloseBehavior.save);
});
close(closeBehaviorString)
Fermer le classeur actif.
close(closeBehaviorString?: "Save" | "SkipSave"): void;
Paramètres
- closeBehaviorString
-
"Save" | "SkipSave"
comportement de fermeture du classeur.
Retours
void
Remarques
getActiveCell()
Obtient la cellule active du classeur.
getActiveCell(): Excel.Range;
Retours
Remarques
[ Ensemble d’API : ExcelApi 1.7 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-get-active-cell.yaml
await Excel.run(async (context) => {
let myWorkbook = context.workbook;
let activeCell = myWorkbook.getActiveCell();
activeCell.load("address");
await context.sync();
console.log("The active cell is " + activeCell.address);
});
getActiveChart()
Obtient la feuille de calcul active du classeur. S’il n’y a pas de graphique actif, une ItemNotFound
exception est levée.
getActiveChart(): Excel.Chart;
Retours
Remarques
getActiveChartOrNullObject()
Obtient la feuille de calcul active du classeur. S’il n’existe aucun graphique actif, 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.
getActiveChartOrNullObject(): Excel.Chart;
Retours
Remarques
getActiveSlicer()
Obtient le segment actif actuel du classeur. S’il n’y a pas de segment actif, une ItemNotFound
exception est levée.
getActiveSlicer(): Excel.Slicer;
Retours
Remarques
getActiveSlicerOrNullObject()
Obtient le segment actif actuel du classeur. S’il n’existe aucun segment actif, 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.
getActiveSlicerOrNullObject(): Excel.Slicer;
Retours
Remarques
getIsActiveCollabSession()
Retourne true
si le classeur est modifié par plusieurs utilisateurs (par le biais de la co-création). Sachez qu’il peut y avoir un certain délai entre le moment où le classeur status change et le moment où les modifications sont reflétées sur le résultat de la méthode.
getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;
Retours
OfficeExtension.ClientResult<boolean>
Remarques
getLinkedEntityCellValue(linkedEntityCellValueId)
Retourne un LinkedEntityCellValue
en fonction du fourni LinkedEntityId
.
getLinkedEntityCellValue(linkedEntityCellValueId: LinkedEntityId): OfficeExtension.ClientResult<LinkedEntityCellValue>;
Paramètres
- linkedEntityCellValueId
- Excel.LinkedEntityId
Identificateur qui spécifie un individu LinkedEntityCellValue
.
Retours
Remarques
getSelectedRange()
Obtient la plage unique actuellement sélectionnée à partir du classeur. Si plusieurs plages sont sélectionnées, cette méthode génère une erreur.
getSelectedRange(): Excel.Range;
Retours
Remarques
[ Ensemble d’API : ExcelApi 1.1 ]
Exemples
await Excel.run(async (context) => {
const selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
await context.sync();
console.log(selectedRange.address);
});
getSelectedRanges()
Obtient la ou les plage(s) sélectionnée(s) actuelle(s) dans le classeur. Contrairement à getSelectedRange()
, cette méthode retourne un RangeAreas
objet qui représente toutes les plages sélectionnées.
getSelectedRanges(): Excel.RangeAreas;
Retours
Remarques
[ Ensemble d’API : ExcelApi 1.9 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml
await Excel.run(async (context) => {
const selectedRanges = context.workbook.getSelectedRanges();
selectedRanges.format.fill.color = "lightblue";
await context.sync();
})
insertWorksheetsFromBase64(base64File, options)
Insère les feuilles de calcul spécifiées à partir d’un classeur source dans le classeur actif.
Remarque* : Cette API est actuellement prise en charge uniquement pour Office sur Windows, Mac et le web.
insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;
Paramètres
- base64File
-
string
Obligatoire. Chaîne encodée en Base64 représentant le fichier de classeur source.
- options
- Excel.InsertWorksheetOptions
Optional. Options qui définissent les feuilles de calcul à insérer et où les nouvelles feuilles de calcul seront insérées dans le classeur. Par défaut, toutes les feuilles de calcul du classeur source sont insérées à la fin du classeur actif.
Retours
OfficeExtension.ClientResult<string[]>
Tableau d’ID correspondant à chaque feuille de calcul nouvellement insérée.
Remarques
[ Ensemble d’API : ExcelApi 1.13 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-insert-external-worksheets.yaml
// Retrieve the file and set up an HTML FileReader element.
const myFile = <HTMLInputElement>document.getElementById("file");
const reader = new FileReader();
reader.onload = (event) => {
// Remove the metadata before the Base64-encoded string.
const startIndex = reader.result.toString().indexOf("base64,");
externalWorkbook = reader.result.toString().substr(startIndex + 7);
};
// Read the file as a data URL so that we can parse the Base64-encoded string.
reader.readAsDataURL(myFile.files[0]);
...
await Excel.run(async (context) => {
// Retrieve the source workbook.
const workbook = context.workbook;
// Set up the insert options.
const options = {
sheetNamesToInsert: [], // Insert all the worksheets from the source workbook.
positionType: Excel.WorksheetPositionType.after, // Insert after the `relativeTo` sheet.
relativeTo: "Sheet1" // The sheet relative to which the other worksheets will be inserted. Used with `positionType`.
};
// Insert the new worksheets.
workbook.insertWorksheetsFromBase64(externalWorkbook, options);
await context.sync();
});
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.WorkbookLoadOptions): Excel.Workbook;
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.Workbook;
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
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.Workbook;
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
save(saveBehavior)
Enregistrer le classeur actif.
save(saveBehavior?: Excel.SaveBehavior): void;
Paramètres
- saveBehavior
- Excel.SaveBehavior
Le comportement d’enregistrement doit être « Enregistrer » ou « Demander ». La valeur par défaut est « Save ».
Retours
void
Remarques
[ Ensemble d’API : ExcelApi 1.11 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml
await Excel.run(async (context) => {
context.workbook.save(Excel.SaveBehavior.save);
});
save(saveBehaviorString)
Enregistrer le classeur actif.
save(saveBehaviorString?: "Save" | "Prompt"): void;
Paramètres
- saveBehaviorString
-
"Save" | "Prompt"
Le comportement d’enregistrement doit être « Enregistrer » ou « Demander ». La valeur par défaut est « Save ».
Retours
void
Remarques
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.WorkbookUpdateData, options?: OfficeExtension.UpdateOptions): void;
Paramètres
- properties
- Excel.Interfaces.WorkbookUpdateData
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.Workbook): void;
Paramètres
- properties
- Excel.Workbook
Retours
void
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.Workbook
est un objet API, la toJSON
méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.WorkbookData
que ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.
toJSON(): Excel.Interfaces.WorkbookData;
Retours
Détails de l'événement
onActivated
Se produit lorsque le classeur est activé. Remarque : Cet événement ne se déclenche pas lorsque le classeur est ouvert.
readonly onActivated: OfficeExtension.EventHandlers<Excel.WorkbookActivatedEventArgs>;
Type d'événement
Remarques
[ Ensemble d’API : ExcelApi 1.13 ]
Exemples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-activated.yaml
async function workbookActivated(event: Excel.WorkbookActivatedEventArgs) {
await Excel.run(async (context) => {
// Callback function for when the workbook is activated.
console.log("The workbook was activated.");
});
}
...
await Excel.run(async (context) => {
const workbook = context.workbook;
// Register the workbook activated event handler.
workbook.onActivated.add(workbookActivated);
await context.sync();
console.log("Added event handler for workbook activated.");
});
onAutoSaveSettingChanged
Se produit lorsque le paramètre Enregistrement automatique est modifié sur le classeur.
readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;
Type d'événement
Remarques
onSelectionChanged
Se produit quand la sélection change dans le document.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.SelectionChangedEventArgs>;