All posts in API JavaScript

Pour récupérer les propriétés d’une cellule (police, taille des caractères, couleur, attributs, couleur d’arrière-plan, etc.), vous utiliserez la méthode getCellProperties(). Indiquez les propriétés que vous voulez récupérer sous la forme d’un objet JSON :

const proprieties = cellule.getCellProperties({

  prop: true;

});

Les propriétés récupérables sont listées sur cette page : https://bit.ly/2LQyCVy

A titre d’exemple, nous allons récupérer les propriétés suivantes :

• address
• format/font/name
• format/font/color
• format/font/bold
• format/font/italic
• format/fill/color
• style

Voici le code utilisé :

async function run() {

  await Excel.run(async (context) => {

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

    let cellule = feuille.getCell(0,0);

    const lesProp = cellule.getCellProperties({

      address: true,

      format: {

        fill: {

          color: true

        },

        font: {

          color: true,

          bold: true,

          italic: true,

          name: true

        }

      },

      style: true

    })

    await context.sync();

    const proprietes = lesProp.value;

    console.log(proprietes);

  });

}

La feuille courante est placée dans la constante feuille :

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

La cellule dont on veut connaitre les propriétés est la cellule A1 :

let cellule = feuille.getCell(0,0);

Les propriétés de cette cellule sont placées dans la constante lesProp :

const lesProp = cellule.getCellProperties({

  address: true,

  format: {

    fill: {

      color: true

    },

    font: {

      color: true,

      bold: true,

      italic: true,

      name: true

    }

  },

  style: true

})

L’instruction await context.sync() synchronise l’état entre les objets proxy de JavaScript et les objets réels dans Excel, ce qui provoque la récupération des propriétés de la cellule A1 :

await context.sync();

L’instruction suivante affiche les propriétés récupérées :

console.log(proprietes.value);

Le résultat est retourné sous la forme d’un tableau. Voici un exemple de ce que vous obtiendrez :

[

    [

        {

            "@odata.type": "Microsoft.ExcelServices.CellPropertiesInternal",

            "address": "Sample!A1",

            "format": {

                "@odata.type": "Microsoft.ExcelServices.CellPropertiesFormatInternal",

                "font": {

                    "@odata.type": "Microsoft.ExcelServices.CellPropertiesFont",

                    "bold": true,

                    "color": "#44546A",

                    "italic": false,

                    "name": "Calibri"

                },

                "fill": {

                    "@odata.type": "Microsoft.ExcelServices.CellPropertiesFill",

                    "color": "#FFFFFF"

                }

            },

            "style": "Heading1"

        }

    ]

]

Pour afficher ces propriétés dans la console, il suffit d’utiliser des instructions « à point ».

Dans un premier temps, on récupère l’objet JSON contenu dans le tableau de tableau avec cette instruction :

const valeurs = lesProp.value[0][0];

Ensuite, on parse les différentes propriétés et on les affiche dans la console :

console.log(`Adresse : ${valeurs.address}`);

console.log(`Police : ${valeurs.format.font.name}, couleur : ${valeurs.format.font.color}, gras : ${valeurs.format.font.bold}, italique : ${valeurs.format.font.italic}`);

console.log(`Couleur d'arrière-plan : ${valeurs.format.fill.color}`);

console.log(`Style : ${valeurs.style}`);

Voici un exemple d’exécution :

Pour obtenir le nom des feuilles du classeur courant :

• On récupère le classeur (wb).
• On récupère les feuilles de calcul (ws).
• On charge les propriétés items (les éléments de la collection ws) et name (le nom de ces éléments) des feuilles de calcul.
• On synchronise les données.
• On boucle sur les feuilles de calcul avec une boucle for of :

async function run() {

  await Excel.run(async function (context) {

    const wb = context.workbook;

    const ws = wb.worksheets;

    ws.load(['items','name']);

    await context.sync();

    for (let feuille of ws.items) {

      console.log(`nom  : ${feuille.name}`);

    }

  });

}

Voici un exemple d’exécution. Ici, le classeur contient quatre feuilles nommées Feuil1 à Feuil4 :

Plusieurs métadonnées (aussi appelées propriétés du document) peuvent être associées aux classeurs Excel. Par exemple, le nom de l’auteur, les commentaires attachés au classeur, la date de création du classeur, etc..

Ces propriétés sont définies dans l’écran backstage d’Excel, en sélectionnant l’onglet Fichier dans le ruban :

Pour avoir une liste exhaustive des propriétés qui peuvent être attachées à un classeur, consultez cette page :

https://docs.microsoft.com/en-us/javascript/api/excel/excel.documentproperties?view=office-js

Pour lire une ou plusieurs propriétés du classeur, vous utiliserez la méthode load() sur l’objet workbook.properties. Passez le nom des propriétés à récupérer en paramètres à la fonction load(). Les propriétés peuvent être définies dans une chaîne ou dans un tableau. Elles doivent être séparées entre elles par des virgules.

Supposons par exemple que vous vouliez connaitre :

• Le nom du classeur.
• Le nom de l’auteur.
• La date de création du classeur.

Vous utiliserez le code suivant :

async function run() {

  await Excel.run(async (context) => {

    let wbProp = context.workbook.properties;

    wbProp.load('author, title, creationDate');

    // Ou, sous la forme d'un tableau de chaînes

    // wbProp.load(['author', 'title', 'creationDate']);

    await context.sync();

    console.log('Auteur : ' + wbProp.author);

    console.log('Titre : ' + wbProp.title);

    console.log('Date de création du classeur : ' + wbProp.creationDate.toLocaleDateString());

  });

}

Voici un exemple d’exécution :

Remarque

La méthode load() n’est nécessaire que lorsque vous souhaitez lire les propriétés sur un objet proxy. Si vous définissez des propriétés ou appliquez des méthodes sur un objet proxy, la méthode load() n’est pas nécessaire.

Remarque

Il est possible de faire référence à des constantes, variables et propriétés sans utiliser l’opérateur de concaténation de JavaScript. Pour cela, vous devez utiliser des chaînes de caractères avec des expressions incluses :

• Délimitez les chaînes par des apostrophes penchées obtenues en appuyant simultanément sur les touches Alt Gr et 7.

• Insérez des constantes, variables ou propriétés dans la chaîne à l’intérieur d’une déclaration ${…}.

Ces instructions :

    console.log('Auteur : ' + wbProp.author);

    console.log('Titre : ' + wbProp.title);

    console.log('Date de création du classeur : ' + wbProp.creationDate.toLocaleDateString());

Deviennent alors :

console.log(`Auteur : ${wbProp.author}`);

console.log(`Titre : ${wbProp.title}`);

console.log(`Date de création du classeur : ${wbProp.creationDate.toLocaleDateString()}`);

Pour interagir avec un classeur Excel, vous allez passer par le modèle objet Excel, via la fonction asynchrone Excel.run(). Vous utiliserez ce « squelette standard » :

$('#run').click(() => tryCatch(run));

async function run() {

  await Excel.run(async (context) => {

    // Entrez votre code ici

    console.log("La fonction run() s'est exécutée");

    await context.sync();

  });

}

async function tryCatch(callback) {

  try {

    await callback();

  } catch (error) {

    console.error(error);

  }

}

Ce code est disponible en cliquant ici

La plupart de ces instructions devraient vous être familières.

Quelques nouveautés cependant.

La fonction Excel.run() exécute des instructions JavaScript / TypeScript qui interagissent de façon asynchrone sur le modèle objet Excel via l’objet context. Cet objet représente l’environnement runtime d’Excel. C’est à travers lui que vous pourrez interagir en lecture et en écriture sur vos classeurs.

Les objets JavaScript définis dans un complément Excel sont des proxy. Lorsque vous utilisez des propriétés (en lecture ou en écriture) de ces objets, ou lorsque vous leur appliquez des méthodes, les instructions correspondantes sont placées dans une file d’attente.

L’instruction await context.sync() exécute les commandes qui sont dans la file d’attente. En d’autres termes, elle synchronise l’état entre les objets proxy de JavaScript et les objets réels dans Excel. Elle doit être systématiquement utilisée dans la fonction Excel.run().

Pour créer ce squelette standard, cliquez sur l’icône de menu dans le volet Code (1), puis cliquez sur New Snippet (2) :

Comme vous pouvez le voir, le code généré est légèrement différent du squelette standard. Il contient en particulier une autre instruction :

Cette instruction récupère le classeur actif et le place dans la constante sheet.

En agissant sur cette constante via des propriétés et des méthodes, vous allez pouvoir lire et modifier le contenu de la feuille courante et, si nécessaire, modifier son apparence.

Les promises (promesses en français) sont apparues avec la version ECMAScript 6 (ES6) de JavaScript. Elles permettent de faire des opérations asynchrones en attendant un résultat dans le futur (une promesse). Ce résultat peut être un succès ou un échec.

Pour créer une nouvelle promise, vous devez instancier la classe Promise en lui passant une fonction anonyme qui a deux arguments (le second étant facultatif). Le premier paramètre est le nom de la fonction à exécuter en cas de succès. Le second est le nom de la fonction à exécuter en cas d’échec.

Premier exemple de promise

new Promise(function(resolve, reject) {  setTimeout(() => {    resolve("Promise résolue")  }, 1000);});

L’objet créé à partir de la classe Promise exécute la fonction resolve() au bout de 1000ms pour indiquer que la promise est résolue. Ici, la fonction reject() n’est jamais exécutée.

Un autre exemple avec les fonctions then() et catch()

Les fonctions then() et catch() peuvent être chaînées à l’exécution d’une promise. La fonction then() prend en argument une fonction anonyme qui peut récupérer des données passées par la promise en cas de succès. La fonction catch() prend en argument une fonction anonyme qui récupère un objet JSON qui précise la nature de l’erreur.

Voici un exemple de promise à laquelle on chaîne la fonction then() pour afficher un message lorsque la promise est résolue :

let promise = new Promise((resolve, reject) =>{

  setTimeout(() => {

    resolve('promise résolue');

  }, 3000);

});

promise.then((value) => {

  console.log(value);

});

console.log('Promise lancée mais pas encore résolue');

Le premier bloc d’instructions définit la promise et l’affecte à la variable promise.

Le deuxième bloc d’instructions lance la promise puis affiche un message lorsqu’elle est résolue.

La dernière instruction affiche un message juste après le lancement de la promise.

Voici ce qui s’affiche dans la console (le second texte s’affiche au bout de 3 secondes) :

Promise lancée mais pas encore résolue

Promise résolue

La méthode then() peut être chaînée à la promise pour simplifier le code :

let promise = new Promise((resolve, reject) =>{

  setTimeout(() => {

    resolve('promise résolue');

  }, 3000);

}).then((value) => {

  console.log(value);

});

console.log('Promise lancée mais pas encore résolue');

Un troisième exemple de code asynchrone avec une attente synchrone

A titre d’exemple, vous allez créer votre premier snippet pour tester l’utilisation des mots-clés async et await.

Dans la fenêtre Code, cliquez sur le menu (1), puis sur New Snippet (2) :

Modifiez le code TypeScript du snippet comme ceci :

$("#run").click(affichage);

async function attendre(ms) {

  let promise = new Promise((resolve) => {

    setTimeout(resolve,ms);

  });

  return promise;

}

async function affichage() {

  let compteur = 1;

  setTimeout(() => {

    ++compteur;

    console.log('Dans la fonction setTimeout() de affichage(), compteur vaut ' + compteur);

  }, 1000);

  console.log('Juste après le setTimeout de la fonction affichage(), compteur vaut ' + compteur);

  await attendre(2000);

  console.log('compteur vaut ' + compteur + ' après l\'instruction await');

}

La fonction asynchrone attendre() fait une pause de ms dans l’exécution du code. Pour cela, elle définit une promise et retourne sa fonction de callback resolve() au bout de ms millisecondes.

Au clic sur le bouton, la fonction asynchrone affichage() est exécutée.

Une variable compteur est initialisée à 1. Un timeout de 1000ms est alors déclenché. Lorsqu’il est terminé, le compteur est incrémenté et un message s’affiche dans la console (1).

L’instruction suivante affiche un message dans la console (2). Ce message apparaîtra avant le message du timeout précédent.

L’instruction suivante fait une pause de 2000ms via la fonction attendre(). Un message est alors affiché dans la console (3).

Voici le résultat de ce code :

Ce code est disponible en cliquant ici

On appelle callback une fonction B passée en paramètre d’une fonction A. La fonction B est appelée à la fin de la fonction A pour effectuer une autre opération. En d’autres termes, B s’exécute une fois que la fonction A est terminée.

function bonjour() {

  console.log("Bonjour");

}

function action(nom, callback) {

  console.log('Bonjour ' + nom);

  callback();

}

action('Michel', bonjour);

Ce code affiche le texte suivant dans la console :

Bonjour Michel

Bonjour

La fonction action() est appelée à la fin du code. On lui transmet une chaîne et une fonction de callback. La chaîne transmise est affichée dans la console, à la suite du mot Bonjour. Puis la fonction de callback (ici la fonction bonjour()) est appelée. Ce qui déclenche l’affichage de la chaîne Bonjour dans la console.

Lorsqu’un code s’exécute de façon synchrone, les instructions s’exécutent l’une après l’autre dans un thread. Pour que plusieurs instructions s’exécutent en parallèle, vous devez les placer dans autant de threads que nécessaires.

Lorsqu’un code s’exécute de façon asynchrone, plusieurs flux d’instructions peuvent s’exécuter en parallèle. En effet, le programme n’attend pas la fin d’une instruction pour passer à la suivante.

Pour exécuter du code JavaScript/TypeScript de façon asynchrone, vous pouvez passer par :

• Des fonctions de callback qui s’exécutent lorsqu’une action est terminée.
• Des promises (promesses en français), qui permettent d’exécuter des callbacks de réussite ou d’échec.
• Le mot async. A l’intérieur de la fonction asynchrone, vous pouvez utiliser le mot await pour attendre l’obtention d’un résultat. Cette version moderne des callbacks est celle retenue dans les compléments Office.