Partager via

Rechercher des cellules spéciales dans une plage à l’aide de l’API JavaScript Excel

  • Article

Cet article fournit des exemples de code qui recherchent des cellules spéciales dans une plage à l’aide de l’API JavaScript Excel. Pour obtenir la liste complète des propriétés et méthodes prises en charge par l’objet Range , voir Classe Excel.Range.

Rechercher des plages avec des cellules spéciales

Les méthodes Range.getSpecialCells et Range.getSpecialCellsOrNullObject recherchent des plages en fonction des caractéristiques de leurs cellules et des types de valeurs de leurs cellules. Ces deux méthodes renvoient à desRangeAreasobjets. Voici les signatures des méthodes à partir des types de fichiers de données TypeScript:

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

L’exemple de code suivant utilise la getSpecialCells méthode pour rechercher toutes les cellules avec des formules. Tenez compte du code suivant :

  • Cela limite la partie de la feuille qui nécessite d’être recherchée en appelant d’abordWorksheet.getUsedRangeet en appelantgetSpecialCellsuniquement pour cette plage.
  • LagetSpecialCellsméthode renvoie unRangeAreasobjet, toutes les cellules alors dotées de formules seront colorées en rose même si elles ne sont pas adjacentes.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

Si aucune cellule avec la caractéristique ciblée n’existe dans la plage getSpecialCells lève une erreurItemNotFound. Cela dévie le flux de contrôle vers un(e)catchbloc/méthode, s’il en existe. S’il n’y a pas de catch bloc, l’erreur arrête la méthode.

Si vous attendez que des cellules avec la caractéristique ciblée existent toujours, vous souhaiterez probablement que votre code lève une erreur si ces cellules ne sont pas là. Mais dans les scénarios où les cellules ne correspondent pas; votre code doit vérifier cette possibilité et le gérer gracieusement sans émettre d’erreur. Vous pouvez obtenir ce comportement avec la getSpecialCellsOrNullObjectméthode et sa propriété renvoyéeisNullObject. L’exemple de code suivant utilise ce modèle. Tenez compte du code suivant :

  • La getSpecialCellsOrNullObject méthode retourne toujours un objet proxy, de sorte qu’elle n’est jamais null dans le sens JavaScript ordinaire. Mais si les cellules non correspondantes sont introuvables, la propriétéisNullObject de l’objet est établi àtrue.
  • Il appelle context.syncavant de tester la isNullObject propriété . Il s’agit d’une condition avec toutes les méthodes et propriétés*OrNullObject, car vous devez toujours télécharger et synchroniser une propriété afin de le lire. Toutefois, il n’est pas nécessaire de charger explicitement la isNullObject propriété. Il est automatiquement chargé par le context.sync même si load n’est pas appelé sur l’objet . Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.
  • Vous pouvez tester ce code en sélectionnant d’abord une plage qui n’a pas de cellules de formule et en l’exécutant. Puis sélectionnez une plage qui dispose au moins d’une cellule dotée d’une formule et en l’exécutant à nouveau.
await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

Par souci de simplicité, tous les autres exemples de code de cet article utilisent la getSpecialCells méthode au lieu de getSpecialCellsOrNullObject.

Réduisez les cellules cibles avec les types de valeur de cellule

Les méthodesRange.getSpecialCells() et Range.getSpecialCellsOrNullObject()acceptent un deuxième paramètre facultatif utilisé pour affiner davantage les cellules ciblées. Ce deuxième paramètre est unExcel.SpecialCellValueType que vous utilisez afin de spécifier que vous souhaitez uniquement les cellules qui contiennent certains types de valeurs.

Notes

Le paramètre Excel.SpecialCellValueType peut uniquement être utilisé si le paramètre Excel.SpecialCellType est défini sur Excel.SpecialCellType.formulasou Excel.SpecialCellType.constants.

Test d’un type de valeur de cellule unique

Le Excel.SpecialCellValueType enum dispose de ces quatre types de base (outre les autres valeurs combinées décrites plus loin dans cette section):

  • Excel.SpecialCellValueType.errors
  • Excel.SpecialCellValueType.logical (ce qui signifie booléen)
  • Excel.SpecialCellValueType.numbers
  • Excel.SpecialCellValueType.text

L’exemple de code suivant recherche des cellules spéciales qui sont des constantes numériques et les colore en rose. Tenez compte du code suivant :

  • Il met uniquement en surbrillance les cellules qui ont une valeur numérique littérale. Il ne met pas en surbrillance les cellules qui ont une formule (même si le résultat est un nombre) ou des cellules booléennes, de texte ou d’état d’erreur.
  • Pour tester le code, assurez-vous que la feuille de calcul dispose de certaines cellules avec des valeurs de nombre littérales, certaines avec d’autres sortes de valeurs littérales, et certaines avec des formules.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Test d’un type de valeur de cellule multiple

Parfois, vous avez besoin d’exécuter plus d’un type de valeur de cellule, tel que toutes les cellules à valeur de texte et à valeur booléen (Excel.SpecialCellValueType.logical). Le Excel.SpecialCellValueType enum comporte des valeurs avec les types combinés. Par exemple,Excel.SpecialCellValueType.logicalTextcible toutes les cellules à valeur texte et booléen. Excel.SpecialCellValueType.all est la valeur par défaut, ce qui ne limite pas les types de valeur de cellule renvoyés. L’exemple de code suivant colorie toutes les cellules avec des formules qui produisent un nombre ou une valeur booléenne.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Voir aussi