Obtenir des plages de feuilles de calcul Excel avec l’API JavaScript

Lorsque votre complément doit lire, écrire ou mettre en forme des cellules, commencez par obtenir un Range objet. Cet article présente des méthodes courantes pour obtenir une plage dans une feuille de calcul. Pour l’ensemble de la surface de l’API, voir Classe Excel.Range.

Remarque

L’API JavaScript Excel ne comprend pas d’objet ou de classe « Cellule ». L’API JavaScript Excel définit plutôt toutes les cellules Excel comme objetsRange. Une cellule individuelle dans l’interface utilisateur d’Excel se traduit par un objetRange avec une cellule dans l’API JavaScript Excel. Un objet Range peut également contenir plusieurs cellules contiguës. Consultez Travailler avec des cellules de calcul à l’aide de l’API JavaScript Excel pour en savoir plus.

Utilisez l’approche de récupération de plage qui correspond à la façon dont votre complément identifie les données.

  • Utilisez une adresse telle que B2 :C5 lorsque vous connaissez les cellules exactes.
  • Utilisez une plage nommée lorsque le classeur définit déjà un nom réutilisable tel que MyRange.
  • Utilisez la plage sélectionnée lorsque votre complément doit fonctionner sur les cellules sélectionnées par l’utilisateur.
  • Utilisez la plage utilisée lorsque vous avez besoin de la plus petite zone qui contient des données ou une mise en forme.
  • Utilisez l’intégralité de la plage de feuille de calcul lorsque votre complément doit fonctionner avec chaque cellule de la feuille.

Obtenir une plage par adresse

Utilisez getRange(address) lorsque vous connaissez déjà la référence de cellule. Dans cet exemple, le complément obtient B2 :C5 à partir de l’exemple de feuille de calcul, charge la address propriété et écrit le résultat dans la console.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:C5");

    range.load("address");
    await context.sync();

    console.log(`The address of the range B2:C5 is "${range.address}"`);
});

Obtenir une plage nommée

Utilisez une plage nommée lorsque la feuille de calcul définit déjà un nom explicite pour un bloc de cellules. Dans cet exemple, le complément obtient la plage nommée MyRange à partir de l’exemple de feuille de calcul, puis lit son adresse.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("MyRange");

    range.load("address");
    await context.sync();

    console.log(`The address of the range "MyRange" is "${range.address}"`);
});

Obtenir la plage sélectionnée

Utilisez getSelectedRange() quand votre complément doit fonctionner avec les cellules sélectionnées par l’utilisateur. Cette méthode est utile pour les actions telles que la mise en forme, la copie ou l’analyse d’une zone choisie par l’utilisateur. Dans cet exemple, le complément obtient la plage sélectionnée, charge sa address propriété et écrit le résultat dans la console.

await Excel.run(async (context) => {
    const range = context.workbook.getSelectedRange();

    range.load("address");
    await context.sync();

    console.log(`The address of the selected range is "${range.address}"`);
});

Pour d’autres tâches de sélection, telles que le déplacement par programmation de la sélection ou son extension au bord de la plage utilisée, voir Sélectionner ou obtenir la plage Excel actuelle avec l’API JavaScript.

Obtenir la plage utilisée

Utilisez getUsedRange() lorsque vous avez besoin de la plus petite plage qui contient une cellule avec une valeur ou une mise en forme. Si la feuille de calcul est vide, getUsedRange() retourne une plage qui contient uniquement la cellule supérieure gauche. Dans cet exemple, le complément obtient la plage utilisée à partir de la feuille de calcul Exemple et lit son adresse.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getUsedRange();

    range.load("address");
    await context.sync();

    console.log(`The address of the used range in the worksheet is "${range.address}"`);
});

Obtenir l’intégralité de la plage de feuilles de calcul

Utilisez getRange() sans argument lorsque vous avez besoin d’une plage qui représente la feuille de calcul entière. Dans cet exemple, le complément obtient la plage entière à partir de l’exemple de feuille de calcul et lit son adresse.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange();

    range.load("address");
    await context.sync();

    console.log(`The address of the entire worksheet range is "${range.address}"`);
});
  • Last updated on