Restrictions TypeScript dans les scripts Office

Les scripts Office utilisent le langage TypeScript. Dans la plupart des cas, tout code TypeScript ou JavaScript fonctionne dans les scripts Office. Toutefois, quelques restrictions sont appliquées par l’éditeur de code pour garantir que votre script fonctionne de manière cohérente et comme prévu avec votre classeur Excel.

Aucun type « any » dans les scripts Office

L’écriture de types est facultative dans TypeScript, car les types peuvent être déduits. Toutefois, les scripts Office exigent qu’une variable ne puisse pas être de type quelconque. Les éléments explicites et implicites any ne sont pas autorisés dans les scripts Office. Ces cas sont signalés comme des erreurs.

Explicite any

Vous ne pouvez pas déclarer explicitement une variable de type any dans les scripts Office (autrement dit, let value: any;). Le any type provoque des problèmes lorsqu’il est traité par Excel. Par exemple, un Range doit savoir qu’une valeur est , stringnumberou boolean. Vous recevrez une erreur au moment de la compilation (une erreur avant l’exécution du script) si une variable est explicitement définie comme type any dans le script.

Dans la capture d’écran précédente, [2, 14] Explicit Any is not allowed indique que la ligne #2, colonne #14 définit le any type. Cela vous permet de localiser l’erreur.

Pour contourner ce problème, définissez toujours le type de la variable. Si vous n’êtes pas certain du type d’une variable, vous pouvez utiliser un type union. Cela peut être utile pour les variables qui contiennent Range des valeurs, qui peuvent être de type string, numberou boolean (le type des Range valeurs est une union de celles-ci : string | number | boolean).

Implicite any

Les types de variables TypeScript peuvent être définis implicitement . Si le compilateur TypeScript n’est pas en mesure de déterminer le type d’une variable (soit parce que le type n’est pas défini explicitement ou parce que l’inférence de type n’est pas possible), il s’agit d’un implicite any et vous recevrez une erreur au moment de la compilation.

Le cas le plus courant sur un implicite any se trouve dans une déclaration de variable, telle que let value;. Il existe deux façons d’éviter cela :

• Affectez la variable à un type implicitement identifiable (let value = 5; ou let value = workbook.getWorksheet();).
• Tapez explicitement la variable (let value: number;)

Aucune classe ou interface Office Script n’hérite

Les classes et interfaces créées dans votre script Office ne peuvent pas étendre ou implémenter des classes ou des interfaces de scripts Office. En d’autres termes, rien dans l’espace ExcelScript de noms ne peut avoir de sous-classes ou de sous-interfaces.

Fonctions TypeScript incompatibles

Les API Scripts Office ne peuvent pas être utilisées dans les éléments suivants :

• Fonctions du générateur
• Array.sort

eval n’est pas pris en charge

La fonction eval JavaScript n’est pas prise en charge pour des raisons de sécurité.

Identificateurs restreints

Les mots suivants ne peuvent pas être utilisés comme identificateurs dans un script. Il s’agit de conditions réservées.

• Excel
• ExcelScript
• console

Seules les fonctions de flèche dans les rappels de tableau

Vos scripts peuvent uniquement utiliser des fonctions de flèche lors de la fourniture d’arguments de rappel pour les méthodes Array . Vous ne pouvez pas passer une sorte d’identificateur ou de fonction « traditionnelle » à ces méthodes.

const myArray = [1, 2, 3, 4, 5, 6];
let filteredArray = myArray.filter((x) => {
  return x % 2 === 0;
});
/*
  The following code generates a compiler error in the Office Scripts Code Editor.
  filteredArray = myArray.filter(function (x) {
    return x % 2 === 0;
  });
*/

Les unions de ExcelScript types et de types définis par l’utilisateur ne sont pas prises en charge

Les scripts Office sont convertis au moment de l’exécution de blocs de code synchrones en blocs de code asynchrones. La communication avec le classeur par le biais de promesses est masquée au créateur du script. Cette conversion ne prend pas en charge les types union qui incluent des ExcelScript types et des types définis par l’utilisateur. Dans ce cas, le Promise est retourné au script, mais le compilateur de script Office ne l’attend pas et le créateur du script ne peut pas interagir avec le Promise.

L’exemple de code suivant montre une union non prise en charge entre ExcelScript.Table et une interface personnalisée MyTable .

function main(workbook: ExcelScript.Workbook) {
  const selectedSheet = workbook.getActiveWorksheet();

  // This union is not supported.
  const tableOrMyTable: ExcelScript.Table | MyTable = selectedSheet.getTables()[0];

  // `getName` returns a promise that can't be resolved by the script.
  const name = tableOrMyTable.getName();

  // This logs "{}" instead of the table name.
  console.log(name);
}

interface MyTable {
  getName(): string
}

Les constructeurs ne prennent pas en charge les API et console instructions de scripts Office

console les instructions et de nombreuses API de scripts Office nécessitent une synchronisation avec le classeur Excel. Ces synchronisations utilisent await des instructions dans la version d’exécution compilée du script. await n’est pas pris en charge dans les constructeurs. Si vous avez besoin de classes avec des constructeurs, évitez d’utiliser des API de scripts Office ou console des instructions dans ces blocs de code.

L’exemple de code suivant illustre ce scénario. Il génère une erreur indiquant failed to load [code] [library].

function main(workbook: ExcelScript.Workbook) {
  class MyClass {
    constructor() {
      // Console statements and Office Scripts APIs aren't supported in constructors.
      console.log("This won't print.");
    }
  }

  let test = new MyClass();
}

Avertissements sur les performances

Le linter de l’éditeur de code émet des avertissements si le script peut rencontrer des problèmes de performances. Les cas et la façon de les contourner sont documentés dans Améliorer les performances de vos scripts Office.

Appels d’API externes

Pour plus d’informations, consultez Prise en charge des appels d’API externes dans les scripts Office .

Voir aussi

• Notions de base pour les scripts Office dans Excel
• Améliorer les performances de vos scripts Office