Utiliser des objets JavaScript intégrés dans les scripts Office

JavaScript fournit plusieurs objets intégrés que vous pouvez utiliser dans vos scripts Office, que vous ayez des scripts en JavaScript ou TypeScript (un sur-ensemble de JavaScript). Cet article explique comment utiliser certains des objets JavaScript intégrés dans les scripts Office pour Excel.

Tableau

L’objet Array fournit un moyen standardisé d’utiliser des tableaux dans votre script. Bien que les tableaux soient des constructions JavaScript standard, ils se rapportent aux scripts Office de deux manières principales : les plages et les collections.

Utiliser des plages

Les plages contiennent plusieurs tableaux bidimensionnels qui correspondent directement aux cellules de cette plage. Ces tableaux contiennent des informations spécifiques sur chaque cellule de cette plage. Par exemple, Range.getValues retourne toutes les valeurs de ces cellules (avec le mappage des lignes et des colonnes du tableau à deux dimensions aux lignes et colonnes de cette sous-section de feuille de calcul). Range.getFormulas et Range.getNumberFormats sont d’autres méthodes fréquemment utilisées qui retournent des tableaux comme Range.getValues.

Le script suivant recherche dans la plage A1:D4 n’importe quel format de nombre contenant un « $ ». Le script définit la couleur de remplissage dans ces cellules sur « jaune ».

function main(workbook: ExcelScript.Workbook) {
  // Get the range From A1 to D4.
  let range = workbook.getActiveWorksheet().getRange("A1:D4");

  // Get the number formats for each cell in the range.
  let rangeNumberFormats = range.getNumberFormats();
  // Iterate through the arrays of rows and columns corresponding to those in the range.
  rangeNumberFormats.forEach((rowItem, rowIndex) => {
    rangeNumberFormats[rowIndex].forEach((columnItem, columnIndex) => {
      // Treat the numberFormat as a string so we can do text comparisons.
      let columnItemText = columnItem as string;
      if (columnItemText.indexOf("$") >= 0) {
        // Set the cell's fill to yellow.
        range.getCell(rowIndex, columnIndex).getFormat().getFill().setColor("yellow");
      }
    });
  });
}

Utiliser des collections

De nombreux objets Excel sont contenus dans une collection. La collection est gérée par l’API Scripts Office et exposée sous forme de tableau. Par exemple, toutes les formes d’une feuille de calcul sont contenues dans un Shape[] qui est retourné par la Worksheet.getShapes méthode . Vous pouvez utiliser ce tableau pour lire les valeurs de la collection, ou vous pouvez accéder à des objets spécifiques à partir des méthodes de get* l’objet parent.

Le script suivant journalise le type de chaque forme dans la feuille de calcul active.

function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the shapes in this worksheet.
  let shapes = selectedSheet.getShapes();

  // Log the type of every shape in the collection.
  shapes.forEach((shape) => {
    console.log(shape.getType());
  });
}

Le script suivant supprime la forme la plus ancienne de la feuille de calcul active.

function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the first (oldest) shape in the worksheet.
  // Note that this script will thrown an error if there are no shapes.
  let shape = selectedSheet.getShapes()[0];

  // Remove the shape from the worksheet.
  shape.delete();
}

Date

L’objet Date fournit un moyen standardisé d’utiliser des dates dans votre script. Date.now() génère un objet avec la date et l’heure actuelles, ce qui est utile lors de l’ajout d’horodatages à l’entrée de données de votre script.

Le script suivant ajoute la date actuelle à la feuille de calcul. Notez qu’à l’aide de la toLocaleDateString méthode , Excel reconnaît la valeur en tant que date et modifie automatiquement le format de nombre de la cellule.

function main(workbook: ExcelScript.Workbook) {
  // Get the range for cell A1.
  let range = workbook.getActiveWorksheet().getRange("A1");

  // Get the current date and time.
  let date = new Date(Date.now());

  // Set the value at A1 to the current date, using a localized string.
  range.setValue(date.toLocaleDateString());
}

La section Utiliser des dates des exemples contient d’autres scripts liés aux dates.

Mathématiques

L’objet Math fournit des méthodes et des constantes pour les opérations mathématiques courantes. Celles-ci fournissent de nombreuses fonctions également disponibles dans Excel, sans qu’il soit nécessaire d’utiliser le moteur de calcul du classeur. Cela évite à votre script d’avoir à interroger le classeur, ce qui améliore les performances.

Le script suivant utilise Math.min pour rechercher et journaliser le plus petit nombre dans la plage A1:D4 . Notez que cet exemple suppose que la plage entière contient uniquement des nombres, et non des chaînes.

function main(workbook: ExcelScript.Workbook) {
  // Get the range from A1 to D4.
  let comparisonRange = workbook.getActiveWorksheet().getRange("A1:D4");

  // Load the range's values.
  let comparisonRangeValues = comparisonRange.getValues();

  // Set the minimum values as the first value.
  let minimum = comparisonRangeValues[0][0];

  // Iterate over each row looking for the smallest value.
  comparisonRangeValues.forEach((rowItem, rowIndex) => {
    // Iterate over each column looking for the smallest value.
    comparisonRangeValues[rowIndex].forEach((columnItem) => {
      // Use `Math.min` to set the smallest value as either the current cell's value or the previous minimum.
      minimum = Math.min(minimum, columnItem);
    });
  });

  console.log(minimum);
}

L’utilisation de bibliothèques JavaScript externes n’est pas prise en charge

Les scripts Office ne prennent pas en charge l’utilisation de bibliothèques tierces externes. Votre script peut uniquement utiliser les objets JavaScript intégrés et les API de scripts Office.

Voir aussi

• Objets intégrés standard
• Environnement de l’éditeur de code de scripts Office