Excel.Workbook class

Représente l’instance d’application Excel qui contient ce classeur.

readonly application: Excel.Application;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.1

Spécifie si le classeur est en mode d’enregistrement automatique.

readonly autoSave: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Représente une collection de liaisons appartenant au classeur.

readonly bindings: Excel.BindingCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.1

Renvoie un nombre sur la version de moteur de calcul Excel.

readonly calculationEngineVersion: number;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

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é

Remarques

Jeu d’API : ExcelApi 1.9

Représente un ensemble de commentaires associés au classeur.

readonly comments: Excel.CommentCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

Exemples

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

await Excel.run(async (context) => {
    context.workbook.comments.getItemByCell("Comments!A1").delete();
    await context.sync();
});

Contexte de requête associé à l’objet. Cette opération connecte le processus du complément à celui de l’application hôte Office.

context: RequestContext;

Valeur de propriété

Représente l’ensemble des parties XML personnalisées contenues dans ce classeur.

readonly customXmlParts: Excel.CustomXmlPartCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.5

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/18-custom-xml-parts/test-xml-for-unique-namespace.yaml

await Excel.run(async (context) => {
    document.getElementById("display-xml").textContent = "";
    const customXmlParts = context.workbook.customXmlParts;
    customXmlParts.load("items");

    await context.sync();

    for (let i = 0; i < customXmlParts.items.length; i++) {
        customXmlParts.items[i].delete();
    }

    await context.sync();
});

Représente toutes les connexions de données dans le classeur.

readonly dataConnections: Excel.DataConnectionCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.7

Représente un ensemble de fonctions de feuille de calcul pouvant être utilisées pour le calcul.

readonly functions: Excel.Functions;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.2

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-built-in-functions.yaml

await Excel.run(async (context) => {
  // This function uses VLOOKUP to find data in the "Wrench" row
  // on the worksheet, and then it uses SUM to combine the values.
  let range = context.workbook.worksheets.getItem("Sample").getRange("A1:D4");

  // Get the values in the second, third, and fourth columns in the "Wrench" row,
  // and combine those values with SUM.
  let sumOfTwoLookups = context.workbook.functions.sum(
    context.workbook.functions.vlookup("Wrench", range, 2, false),
    context.workbook.functions.vlookup("Wrench", range, 3, false),
    context.workbook.functions.vlookup("Wrench", range, 4, false)
  );
  sumOfTwoLookups.load("value");

  await context.sync();
  console.log(" Number of wrenches sold in November, December, and January = " + sumOfTwoLookups.value);
});

Indique si des modifications ont été apportées depuis le dernier enregistrement du classeur. Vous pouvez définir cette propriété sur true si vous souhaitez fermer un classeur modifié sans l’enregistrer ou être invité à l’enregistrer.

isDirty: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Obtient le nom du classeur.

readonly name: string;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.7

Représente une collection d’éléments nommés de portée de classeur (plages nommées et constantes).

readonly names: Excel.NamedItemCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.1

Représente une collection de tableaux croisés dynamiques associés au classeur.

readonly pivotTables: Excel.PivotTableCollection;

Valeur de propriété

Remarques

Jeu 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}`);
  });
});

Représente une collection de PivotTableStyles associée au classeur.

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

Indique si le classeur a déjà été enregistré localement ou en ligne.

readonly previouslySaved: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Obtient les propriétés du classeur.

readonly properties: Excel.DocumentProperties;

Valeur de propriété

Remarques

Jeu 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.");
});

Renvoie l’objet de protection pour un classeur.

readonly protection: Excel.WorkbookProtection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.7

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/data-protection.yaml

await Excel.run(async (context) => {
    const workbook: Excel.Workbook = context.workbook;
    workbook.protection.unprotect();
});

Renvoie un ensemble de requêtes Power Query qui font partie du classeur.

readonly queries: Excel.QueryCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.14

Retourne true si le classeur est ouvert en mode lecture seule.

readonly readOnly: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.8

Représente un ensemble de paramètres associés au classeur.

readonly settings: Excel.SettingCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.4

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    const settings: Excel.SettingCollection = context.workbook.settings;
    settings.onSettingsChanged.add(onChangedSetting);

    await context.sync();
    console.log("Settings changed handler registered.");
});

Représente une collection de segments associés au classeur.

readonly slicers: Excel.SlicerCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

Représente une collection de styles associés au classeur.

readonly slicerStyles: Excel.SlicerStyleCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

Représente une collection de styles associés au classeur.

readonly styles: Excel.StyleCollection;

Valeur de propriété

Remarques

Jeu 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.");
});

Représente une collection de tableaux associés au classeur.

readonly tables: Excel.TableCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.1

Représente une collection de TableStyles associés au classeur.

readonly tableStyles: Excel.TableStyleCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

Représente une collection de TimelineStyles associés au classeur.

readonly timelineStyles: Excel.TimelineStyleCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.10

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 perdront définitivement de leur précision lors du basculement de cette propriété de false à true.

usePrecisionAsDisplayed: boolean;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.9

Représente une collection de feuilles de calcul associées au classeur.

readonly worksheets: Excel.WorksheetCollection;

Valeur de propriété

Remarques

Jeu d’API : ExcelApi 1.1

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/list-worksheets.yaml

await Excel.run(async (context) => {
    const sheets: Excel.WorksheetCollection = context.workbook.worksheets;
    sheets.load("items/name");
    
    await context.sync();

    if (sheets.items.length > 1) {
        console.log(`There are ${sheets.items.length} worksheets in the workbook:`);
    } else {
        console.log(`There is one worksheet in the workbook:`);
    }
    for (let i in sheets.items) {
        console.log(sheets.items[i].name);
    } 
});

Fermer le classeur actif.

close(closeBehavior?: Excel.CloseBehavior): void;

Paramètres

Retours

Remarques

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

Fermer le classeur actif.

close(closeBehavior?: "Save" | "SkipSave"): void;

Paramètres

Retours

Remarques

Jeu d’API : ExcelApi 1.11

Obtient la cellule active du classeur.

getActiveCell(): Excel.Range;

Retours

Remarques

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

Obtient la feuille de calcul active du classeur. S’il n’y a aucun graphique actif, une ItemNotFound exception est levée.

getActiveChart(): Excel.Chart;

Retours

Remarques

Jeu d’API : ExcelApi 1.9

Obtient la feuille de calcul active du classeur. S’il n’y a pas de graphique actif, cette méthode renvoie un objet dont la isNullObject propriété est définie sur true. Pour plus d’informations, consultez * Méthodes et propriétés d’OrNullObject.

getActiveChartOrNullObject(): Excel.Chart;

Retours

Remarques

Jeu d’API : ExcelApi 1.9

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

Jeu d’API : ExcelApi 1.10

Obtient le segment actif actuel du classeur. S’il n’y a pas de segment actif, cette méthode renvoie un objet dont la isNullObject propriété est définie sur true. Pour plus d’informations, consultez * Méthodes et propriétés d’OrNullObject.

getActiveSlicerOrNullObject(): Excel.Slicer;

Retours

Remarques

Jeu d’API : ExcelApi 1.10

Retourne true si le classeur est en cours de modification par plusieurs utilisateurs (par le biais de la co-édition). Veuillez noter qu’il peut y avoir un certain délai entre le moment où le status du classeur change et le moment où les modifications sont répercutées sur le résultat de la méthode.

getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;

Retours

Remarques

Jeu d’API : ExcelApi 1.9

Retourne a LinkedEntityCellValue en fonction de la valeur .LinkedEntityId

getLinkedEntityCellValue(linkedEntityCellValueId: LinkedEntityId): OfficeExtension.ClientResult<LinkedEntityCellValue>;

Paramètres

Retours

Remarques

Jeu d’API : ExcelApi 1.16

Obtient la plage unique actuellement sélectionnée à partir du classeur. Si plusieurs plages sont sélectionnées, cette méthode renvoie une erreur.

getSelectedRange(): Excel.Range;

Retours

Remarques

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

Obtient la ou les plage(s) sélectionnée(s) actuelle(s) dans le classeur. Contrairement à getSelectedRange(), cette méthode renvoie un RangeAreas objet qui représente toutes les plages sélectionnées.

getSelectedRanges(): Excel.RangeAreas;

Retours

Remarques

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

Insère les feuilles de calcul spécifiées à partir d’un classeur source dans le classeur actif.

La extensionHardening clé de Registre Windows affecte cette API. L’extension de fichier définie par le base64File paramètre doit correspondre au type de fichier réel du fichier inséré. Si extensionHardening est configuré pour refuser les incompatibilités et que l’extension de fichier ne correspond pas au type de fichier réel, cette API génère l’erreur suivante : « Cette opération n’est pas autorisée en raison de la stratégie de renforcement de l’extension. »

insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;

Paramètres

Retours

Tableau d’ID correspondant à chaque feuille de calcul nouvellement insérée.

Remarques

Jeu d’API : ExcelApi 1.13

Pour l’instant, cette API n’est prise en charge que pour Office sur Windows, Mac et le web. Dans Excel sur le Web, cette API ne prend pas en charge l’insertion de graphiques, de commentaires, de tableaux croisés dynamiques ou de segments.

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 = document.getElementById("file") as HTMLInputElement;
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();
});

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

Retours

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

Retours

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

Retours

Enregistrer le classeur actif.

save(saveBehavior?: Excel.SaveBehavior): void;

Paramètres

Retours

Remarques

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

Enregistrer le classeur actif.

save(saveBehavior?: "Save" | "Prompt"): void;

Paramètres

Retours

Remarques

Jeu d’API : ExcelApi 1.11

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez transmettre soit un objet ordinaire avec les propriétés appropriées, soit un autre objet API du même type.

set(properties: Interfaces.WorkbookUpdateData, options?: OfficeExtension.UpdateOptions): void;

Paramètres

Retours

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

Retours

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringify, à son tour, appelle 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 simple (typé ) Excel.Interfaces.WorkbookDataqui contient des copies superficielles de toutes les propriétés enfants chargées à partir de l’objet d’origine.

toJSON(): Excel.Interfaces.WorkbookData;

Retours

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

Jeu 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.");
});

Se produit lorsque le paramètre d’enregistrement automatique est modifié dans le classeur.

readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;

Type d’événement

Remarques

Jeu d’API : ExcelApi 1.9

Se produit quand la sélection change dans le document.

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.SelectionChangedEventArgs>;

Type d’événement

Remarques

Jeu d’API : ExcelApi 1.2