Objet Range (interface API JavaScript pour Excel)

Office and SharePoint Add-ins

La dernière version de ce complément Office est disponible dans le référentiel GitHub des compléments.


S’applique à : Excel 2016, Excel Online, Office 2016

Une plage représente un ensemble constitué d’une ou de plusieurs cellules contiguës comme une cellule, une ligne, une colonne, un bloc de cellules, etc.

PropriétéTypeDescription
addressstringReprésente la référence de plage dans le style A1. La valeur d’adresse contient la référence de feuille (par exemple, Feuille1! A1:B4). En lecture seule.
addressLocalstringReprésente la référence de la plage spécifiée dans le langage de l’utilisateur. En lecture seule.
cellCountintNombre de cellules dans la plage. En lecture seule.
columnCountintReprésente le nombre total de colonnes dans la plage. En lecture seule.
columnIndexintReprésente le numéro de colonne de la première cellule de la plage. Avec indice zéro. En lecture seule.
formulasobject[][]Représente la formule dans le style de notation A1.
formulasLocalobject[][]Représente la formule en notation A1, en utilisant le langage et les paramètres de format de nombre régionaux de l’utilisateur. Par exemple, la formule « =SUM(A1, 1.5) » en anglais deviendrait « =SUMME(A1; 1,5) » en allemand.
numberFormatobject[][]Représente le code de format de nombre pour une cellule donnée.
rowCountintRenvoie le nombre total de lignes de la plage. En lecture seule.
rowIndexintRenvoie le numéro de ligne de la première cellule de la plage. Avec indice zéro. En lecture seule.
textobject[][]Valeurs de texte de la plage spécifiée. La valeur de texte ne dépend pas de la largeur de la cellule. Le remplacement par le signe # qui se produit dans l’interface utilisateur d’Excel n’a aucun effet sur la valeur de texte renvoyée par l’API. En lecture seule.
valueTypesstringReprésente le type de données de chaque cellule. En lecture seule. Les valeurs possibles sont les suivantes : Unknown (inconnu), Empty (vide), String (chaîne), Integer (entier), Double (double), Boolean (valeur booléenne), Error (erreur).
valuesobject[][]Représente les valeurs brutes de la plage spécifiée. Les données renvoyées peuvent être des chaînes, des valeurs numériques ou des valeurs booléennes. Une cellule contenant une erreur renvoie une chaîne d’erreur.

Voir des exemples d’accès aux propriétés.

RelationTypeDescription
formatRangeFormatRenvoie un objet de format, qui comprend les propriétés de police, de remplissage, de bordures, d’alignement, etc. de la plage. En lecture seule.
worksheetWorksheetFeuille de calcul contenant la plage. En lecture seule.
MéthodeType renvoyéDescription
clear(applyTo: string)voidSupprime les valeurs et les propriétés de format, de remplissage, de bordure, etc. de la plage.
delete(shift: string)voidSupprime les cellules associées à la plage.
getBoundingRect(anotherRange: Range or string)RangeRenvoie le plus petit objet de plage qui englobe les plages données. Par exemple, la valeur getBoundingRect pour « B2:C5 » et « D10:E15 » est « B2:E15 ».
getCell(row: number, column: number)RangeRenvoie l’objet de plage qui contient une cellule donnée sur la base des numéros de ligne et de colonne. La cellule peut se trouver en dehors des limites de ses plages parent, pour peu qu’elle reste dans la grille de la feuille de calcul. L’emplacement de la cellule renvoyée est déterminé à partir de la cellule supérieure gauche de la plage.
getColumn(column: number)RangeObtient une colonne contenue dans la plage.
getEntireColumn()RangeObtient un objet qui représente la colonne entière de la plage.
getEntireRow()RangeObtient un objet qui représente la ligne entière de la plage.
getIntersection(anotherRange: Range or string)RangeObtient l’objet de plage qui représente l’intersection rectangulaire des plages données.
getLastCell()RangeObtient la dernière cellule de la plage. Par exemple, la dernière cellule de la plage « B2:D5 » est « D5 ».
getLastColumn()RangeObtient la dernière colonne de la plage. Par exemple, la dernière colonne de la plage « B2:D5 » est « D2:D5 ».
getLastRow()RangeObtient la dernière ligne de la plage. Par exemple, la dernière ligne de la plage « B2:D5 » est « B5:D5 ».
getOffsetRange(rowOffset: number, columnOffset: number)RangeObtient un objet qui représente une plage décalée par rapport à la plage spécifiée. Les dimensions de la plage renvoyée correspondent à celle de la plage initiale. Si la plage obtenue se retrouve en dehors des limites de la grille de la feuille de calcul, une exception est déclenchée.
getRow(row: number)RangeObtient une ligne contenue dans la plage.
getUsedRange()RangeRenvoie la plage utilisée d’un objet de plage donné.
insert(shift: string)RangeInsère une cellule ou une plage de cellules dans la feuille de calcul à la place d’une plage donnée et décale les autres cellules pour libérer de l’espace. Renvoie un nouvel objet Range dans l’espace vide qui s’est créé.
load(param: object)voidRemplit l’objet proxy créé dans le calque JavaScript avec des valeurs de propriété et d’objet spécifiées dans le paramètre.
select()voidSélectionne la plage spécifiée dans l’interface utilisateur d’Excel.

Supprime les valeurs et les propriétés de format, de remplissage, de bordure, etc. de la plage.

Syntaxe

jsrangeObject.clear(applyTo);

Paramètres

ParamètreTypeDescription
applyTostringFacultatif. Détermine le type d’action de suppression. Les valeurs possibles sont les suivantes : All (option par défaut),Formats ,Contents

Retourne

void

Exemples

L’exemple ci-dessous efface le format et le contenu de la plage.


Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D:F";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Supprime les cellules associées à la plage.

Syntaxe

jsrangeObject.delete(shift);

Paramètres

ParamètreTypeDescription
ShiftstringIndique la façon dont les cellules doivent être décalées. Les valeurs possibles sont les suivantes : Up (vers le haut), Left (vers la gauche)

Retourne

void

Exemples


Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D:F";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete();
    return ctx.sync(); 
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Renvoie le plus petit objet de plage qui englobe les plages données. Par exemple, la valeur GetBoundingRect pour « B2:C5 » et « D10:E15 » est « B2:E15 ».

Syntaxe

jsrangeObject.getBoundingRect(anotherRange);

Paramètres

ParamètreTypeDescription
anotherRangerange ou stringNom, adresse ou objet de plage.

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D4:G6";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    var range = range.getBoundingRect("G4:H8");
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // Prints Sheet1!D4:H8
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Renvoie l’objet de plage qui contient une cellule donnée sur la base des numéros de ligne et de colonne. La cellule peut se trouver en dehors des limites de ses plages parent, pour peu qu’elle reste dans la grille de la feuille de calcul. L’emplacement de la cellule renvoyée est déterminé à partir de la cellule supérieure gauche de la plage.

Syntaxe

jsrangeObject.getCell(row, column);

Paramètres

ParamètreTypeDescription
rownumberNuméro de ligne de la cellule à récupérer. Avec indice zéro.
columnnumberNuméro de colonne de la cellule à récupérer. Avec indice zéro.

Retourne

Range

Exemples


Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var worksheet = ctx.workbook.worksheets.getItem(sheetName);
    var range = worksheet.getRange(rangeAddress);
    var cell = range.cell(0,0);
    cell.load('address');
    return ctx.sync().then(function() {
        console.log(cell.address);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient une colonne contenue dans la plage.

Syntaxe

jsrangeObject.getColumn(column);

Paramètres

ParamètreTypeDescription
columnnumberNuméro de colonne de la plage à récupérer. Avec indice zéro.

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet19";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!B1:B8
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient un objet qui représente la colonne entière de la plage.

Syntaxe

jsrangeObject.getEntireColumn();

Paramètres

Aucun

Retourne

Range

Exemples

Remarque : les propriétés de grille de la plage (valeurs, format de nombre, formules) contiennent la valeur null car la plage en question est illimitée.



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D:F";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    var rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    return ctx.sync().then(function() {
        console.log(rangeEC.address);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient un objet qui représente la ligne entière de la plage.

Syntaxe

jsrangeObject.getEntireRow();

Paramètres

Aucun

Retourne

Range

Exemples



Excel.run(function (ctx) {
    var sheetName = "Sheet1";
    var rangeAddress = "D:F"; 
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    var rangeER = range.getEntireRow();
    rangeER.load('address');
    return ctx.sync().then(function() {
        console.log(rangeER.address);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Les propriétés de grille de la plage (valeurs, format de nombre, formules) contiennent la valeur null car la plage en question est illimitée.

Obtient l’objet de plage qui représente l’intersection rectangulaire des plages données.

Syntaxe

jsrangeObject.getIntersection(anotherRange);

Paramètres

ParamètreTypeDescription
anotherRangerange ou stringObjet de plage ou adresse de plage utilisé pour déterminer l’intersection des plages.

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!D4:F6
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient la dernière cellule de la plage. Par exemple, la dernière cellule de la plage « B2:D5 » est « D5 ».

Syntaxe

jsrangeObject.getLastCell();

Paramètres

Aucun

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!F8
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient la dernière colonne de la plage. Par exemple, la dernière colonne de la plage « B2:D5 » est « D2:D5 ».

Syntaxe

jsrangeObject.getLastColumn();

Paramètres

Aucun

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!F1:F8
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient la dernière ligne de la plage. Par exemple, la dernière ligne de la plage « B2:D5 » est « B5:D5 ».

Syntaxe

jsrangeObject.getLastRow();

Paramètres

Aucun

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!A8:F8
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient un objet qui représente une plage décalée par rapport à la plage spécifiée. Les dimensions de la plage renvoyée correspondent à celle de la plage initiale. Si la plage obtenue se retrouve en dehors des limites de la grille de la feuille de calcul, une exception est déclenchée.

Syntaxe

jsrangeObject.getOffsetRange(rowOffset, columnOffset);

Paramètres

ParamètreTypeDescription
rowOffsetnumberNombre de lignes (positif, négatif ou nul) duquel décaler la plage. Les valeurs positives représentent un décalage vers le bas et les valeurs négatives un décalage vers le haut.
columnOffsetnumberNombre de colonnes (positif, négatif ou nul) duquel décaler la plage. Les valeurs positives représentent un décalage vers la droite et les valeurs négatives un décalage vers la gauche.

Retourne

Range

Exemples


Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D4:F6";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!H3:K5
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtient une ligne contenue dans la plage.

Syntaxe

jsrangeObject.getRow(row);

Paramètres

ParamètreTypeDescription
rownumberNuméro de ligne de la plage à récupérer. Avec indice zéro.

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    return ctx.sync().then(function() {
        console.log(range.address); // prints Sheet1!A2:F2
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Renvoie la plage utilisée d’un objet de plage donné.

Syntaxe

jsrangeObject.getUsedRange();

Paramètres

Aucun

Retourne

Range

Exemples



Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "D:F";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    var rangeUR = range.getUsedRange();
    rangeUR.load('address');
    return ctx.sync().then(function() {
        console.log(rangeUR.address);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Insère une cellule ou une plage de cellules dans la feuille de calcul à la place d’une plage donnée et décale les autres cellules pour libérer de l’espace. Renvoie un nouvel objet Range dans l’espace vide qui s’est créé.

Syntaxe

jsrangeObject.insert(shift);

Paramètres

ParamètreTypeDescription
ShiftstringIndique la façon dont les cellules doivent être décalées. Les valeurs possibles sont les suivantes : Down (vers le bas), Right (vers la droite)

Retourne

Range

Exemples


    
Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "F5:F10";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert();
    return ctx.sync(); 
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Remplit l’objet proxy créé dans le calque JavaScript avec des valeurs de propriété et d’objet spécifiées dans le paramètre.

Syntaxe

jsobject.load(param);

Paramètres

ParamètreTypeDescription
paramobjectFacultatif. Accepte les noms de paramètre et de relation sous forme de chaîne délimitée ou de tableau. Sinon, indiquez l’objet loadOption.

Renvoie

void

Sélectionne la plage spécifiée dans l’interface utilisateur d’Excel.

Syntaxe

jsrangeObject.select();

Paramètres

Aucun

Retourne

void

Exemples



Excel.run(function (ctx) {
    var sheetName = "Sheet1";
    var rangeAddress = "F5:F10"; 
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    return ctx.sync(); 
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Cet exemple utilise l’adresse de la plage pour obtenir l’objet de la plage.



Excel.run(function (ctx) {
    var sheetName = "Sheet1";
    var rangeAddress = "A1:F8"; 
    var worksheet = ctx.workbook.worksheets.getItem(sheetName);
    var range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    return ctx.sync().then(function() {
        console.log(range.cellCount);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Cet exemple utilise une plage nommée pour obtenir l’objet de la plage.



Excel.run(function (ctx) { 
    var rangeName = 'MyRange';
    var range = ctx.workbook.names.getItem(rangeName).range;
    range.load('cellCount');
    return ctx.sync().then(function() {
        console.log(range.cellCount);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

L’exemple ci-dessous définit le format de nombre, les valeurs et les formules dans une grille 2x3.


Excel.run(function (ctx) { 
    var sheetName = "Sheet1";
    var rangeAddress = "F5:G7";
    var numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    var values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    var formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    return ctx.sync().then(function() {
        console.log(range.text);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Obtenir la feuille de calcul contenant la plage


Excel.run(function (ctx) { 
    var names = ctx.workbook.names;
    var namedItem = names.getItem('MyRange');
    range = namedItem.range;
    var rangeWorksheet = range.worksheet;
    rangeWorksheet.load('name');
    return ctx.sync().then(function() {
            console.log(rangeWorksheet.name);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

Afficher: