Utiliser les feuilles de calcul et les commandes de complément Excel

13 minutes

Dans cette section, vous découvrirez comment utiliser des feuilles de calcul dans les classeurs Excel. Vous allez également découvrir comment créer et utiliser des commandes de complément pour vos solutions personnalisées.

Feuilles de calcul et classeur

Un classeur est l'objet racine lors de l'utilisation des API Excel.

Diagramme montrant la hiérarchie d’objets Excel.

Un classeur est une propriété du contexte de complément Excel, context.workbook, et contient une collection de feuilles de calcul.

Une feuille de calcul contient des collections pour charts, tables, et pivotTables parmi d’autres propriétés.

Opérations de feuilles de calcul de base

L’interaction avec des feuilles de calcul est une opération fondamentale de création d’un complément Excel.

L’API Office.js peut itérer des feuilles de calcul dans un objet classeur ou vous pouvez sélectionner des feuilles de calcul spécifiques sur la base du nom, de l’ID ou du statut actif de la feuille de calcul.

Les développeurs peuvent créer des feuilles de calcul à l’aide de la méthode workbook.worksheets.add().

Opérations de feuilles de calcul avancées

Il existe de nombreuses opérations de feuille de calcul avancées, y compris les événements de feuille de calcul pour onActivated, onAdded, onDeactivated, et onDeleted.

Les développeurs peuvent également figer les volets de feuille de calcul et protéger ou ôter la protection des feuilles de calcul.

Les exemples de code suivants illustrent des opérations courantes que les développeurs peuvent effectuer à partir de compléments Excel personnalisés à l’aide de l’API Office.js :

Obtenir la feuille de calcul active

const worksheet = context.workbook.worksheets.getActiveWorksheet();

Obtenir une feuille de calcul par nom

const worksheet = context.workbook.worksheets.getItem("MyNewWorksheet");

Définir la feuille de calcul active
```
someWorksheet.activate();
```

Créer une feuille de calcul

const worksheet = context.workbook.worksheets.add("MyNewWorksheet");

Supprimer une feuille de calcul
```
someWorksheet.delete();
```

Brancher dans l’événement onDeactivated

currWorksheet.onDeactivated.add((args) => {
  console.log("Worksheet " + args.worksheetId + " deactivated");
});

Figer la première ligne de la feuille de calcul
```
currWorksheet.freezePanes.freezeRows(1);
```

Activer ou désactiver la protection de la feuille de calcul

currWorksheet.load("protection/protected");
return context.sync().then(() => {
  if (currWorksheet.protection.protected)
    currWorksheet.protection.unprotect();
  else
    currWorksheet.protection.protect();
}).then(context.sync);

Commandes de complément

Les commandes de complément sont un moyen facile de personnaliser l’interface utilisateur Office par défaut en y ajoutant des éléments d’interface utilisateur de votre choix qui exécutent des actions.

Les commandes de complément sont configurées dans l’élément VersionOverrides d’un manifeste de complément.

Les commandes de complément peuvent étendre les menus contextuels, les onglets et les groupes de ruban existants, ou créer des onglets et groupes de ruban personnalisés.

Élément ExtensionPoint

L’élément ExtensionPoint définit l’emplacement où les commandes de complément doivent s’afficher dans l’interface utilisateur Office, y compris dans un onglet de ruban existant (OfficeTab), un onglet personnalisé (CustomTab) ou dans un menu contextuel disponible en cliquant avec le bouton droit sur l’interface utilisateur Office (OfficeMenu).

Les commandes de complément prennent en charge les boutons et les contrôles de menu. Les boutons permettent d'effectuer une seule action et les menus offrent un sous-menu d'actions.

Actions des commandes

L’action ShowTaskpane() est la plus courante pour les commandes d’un complément. Elle permet de lancer le complément dans un volet des tâches. L’utilisation d’une commande de complément pour lancer un complément est considérée comme une bonne pratique et est incorporée dans la plupart des modèles et générateurs de compléments Office.

L’action ExecuteFunction permet à une commande de complément d’exécuter un script en arrière-plan sans afficher l’interface utilisateur. Ce type de commande nécessite la définition d’un FunctionFile dans le manifeste.

Commande de complément dans le manifeste

Découvrons comment les différents éléments du manifeste de complément correspondent aux éléments rendus dans l’expérience utilisateur Excel.

L’image suivante est une capture d’écran d’une application cliente Office à gauche et une version condensée d’un fichier manifeste de complément à droite :

Capture d’écran d’une application Office en regard d’un extrait de manifeste de complément.

Le manifeste commence par l’élément ExtensionPoint qui contient toutes les personnalisations définies pour le ruban Office :

Capture d’écran d’une application Office en regard d’un extrait de manifeste de complément avec le point d’extension mis en surbrillance.

L'ensemble du contenu de l'élément ExtensionPoint définit l'onglet personnalisé dans le ruban et tous les boutons dans l'onglet :

Capture d’écran d’une application Office en regard d’un extrait de manifeste de complément avec l’onglet personnalisé mis en surbrillance dans les deux.

Chaque bouton du ruban est défini à l’aide d’un élément Control. Un contrôle peut être de types différents, définis dans la propriété xsi:type. Tous les contrôles dans ce ruban sont des boutons :

Capture d’écran d’une application Office en regard d’un extrait de manifeste de complément avec des onglets personnalisés mis en surbrillance et numérotés dans les deux.

Dans un contrôle, les développeurs peuvent définir des actions ou des éléments. Un élément Action est utilisé pour effectuer une action, par exemple afficher un volet des tâches ou exécuter une fonction personnalisée.

La collection Items permet aux développeurs d’ajouter des éléments de menu au bouton du ruban, comme illustré dans l’image suivante. Notez que chaque élément de sous-menu comporte également un élément Action :

Capture d’écran d’une application Office en regard d’un manifeste de complément avec les éléments Objet mis en surbrillance et numérotés dans les deux.

Commande de complément ExecuteFunction

L’action de commande de complément ExecuteFunction permet aux développeurs de créer des fonctions personnalisées, définies dans JavaScript, pour qu’elles s’exécutent lorsqu’un bouton est sélectionné dans le ruban.

Tout d’abord, définissez la fonction dans un fichier script. Par exemple, ajoutez le code suivant à un nouveau fichier dans votre complément appelé fnFile.html :

<script>
(function () {
  // must call Office.initialize
  Office.initialize => (reason) {
    // Initialize add-in
  };
})();
// function must be global
function doStuff(event) {
  // do stuff with Office.js
}
</script>

Pour appeler la fonction, utilisez le type d’action ExecuteFunction dans le manifeste de complément pour appeler la fonction lorsque le bouton personnalisé est sélectionné :

<FunctionFile resid="Contoso.FnFile.Url" />
...
<Control xsi:type="Button" id="Contoso.FnBtn">
  <Label resid="Contoso.FnBtn.Label" />
  <Icon>
    <bt:Image size="16" resid="Contoso.FnBtn.Icon" />
    <bt:Image size="32" resid="Contoso.FnBtn.Icon" />
    <bt:Image size="80" resid="Contoso.FnBtn.Icon" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>doStuff</FunctionName>
  </Action>
  </Control>
...
<Resources>
  <bt:Urls>
    <bt:Url id="Contoso.FnFile.Url"
            DefaultValue="https://REPLACE_ADD-IN_APP_URL/FnFile.html" />
      ...

Résumé

Dans cette unité, vous avez découvert comment utiliser des feuilles de calcul dans les classeurs Excel. Vous avez également découvert comment créer et utiliser des commandes de complément pour vos solutions personnalisées.

Continuer