Excel.Range class

Référence

Paquet:: excel

Range représente un ensemble d’une ou plusieurs cellules contiguës telles qu’une cellule, une ligne, une colonne ou un bloc de cellules. Pour en savoir plus sur l’utilisation des plages dans l’ensemble de l’API, commencez par Plages dans l’API JavaScript Excel.

Extends: OfficeExtension.ClientObject

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Get a Range object by its address.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

Propriétés

address	Spécifie la référence de plage dans le style A1. La valeur d’adresse contient la référence de la feuille (par exemple, « Sheet1 ! A1 :B4").
addressLocal	Représente la référence de plage pour la plage spécifiée dans la langue de l’utilisateur.
cellCount	Spécifie le nombre de cellules dans la plage. Cette API renvoie -1 si le nombre de cellules est supérieur à 2^31-1 (2 147 483 647).
columnCount	Spécifie le nombre total de colonnes dans la plage.
columnHidden	Représente si toutes les colonnes de la plage actuelle sont masquées. La valeur est `true` lorsque toutes les colonnes d’une plage sont masquées. La valeur est quand aucune colonne de la plage n’est `false` masquée. La valeur est `null` lorsque certaines colonnes d’une plage sont masquées et que d’autres colonnes de la même plage ne sont pas masquées.
columnIndex	Spécifie le numéro de colonne de la première cellule de la plage. Avec indice zéro.
context	Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.
format	Renvoie un objet de format, encapsulant la police, le remplissage, les bordures, l’alignement et d’autres propriétés de la plage.
formulas	Représente la formule dans le style de notation A1. Si une cellule n’a pas de formule, sa valeur est retournée à la place.
formulasLocal	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. Si une cellule n’a pas de formule, sa valeur est retournée à la place.
formulasR1C1	Représente la formule dans le style de notation R1C1. Si une cellule n’a pas de formule, sa valeur est retournée à la place.
hidden	Représente si toutes les cellules de la plage actuelle sont masquées. La valeur est `true` lorsque toutes les cellules d’une plage sont masquées. La valeur est quand aucune cellule de la plage n’est `false` masquée. La valeur est `null` lorsque certaines cellules d’une plage sont masquées et que d’autres cellules de la même plage ne sont pas masquées.
numberFormat	Représente le code de format numérique d’Excel pour la plage donnée. Pour plus d’informations sur la mise en forme des nombres Excel, consultez Codes de format de nombre.
rowCount	Renvoie le nombre total de lignes de la plage.
rowHidden	Représente si toutes les lignes de la plage actuelle sont masquées. La valeur est `true` lorsque toutes les lignes d’une plage sont masquées. La valeur est quand aucune ligne de la plage n’est `false` masquée. La valeur est `null` lorsque certaines lignes d’une plage sont masquées et que d’autres lignes de la même plage ne sont pas masquées.
rowIndex	Renvoie le numéro de ligne de la première cellule de la plage. Avec indice zéro.
sort	Représente le tri de plage de la plage actuelle.
text	Valeurs de texte de la plage spécifiée. La valeur de texte ne dépend pas de la largeur de la cellule. La substitution de signe numérique (#) qui se produit dans l’interface utilisateur Excel n’affecte pas la valeur de texte retournée par l’API.
values	Représente les valeurs brutes de la plage spécifiée. Les données retournées peuvent être une chaîne, un nombre ou une valeur booléenne. Les cellules contenant une erreur renvoie la chaîne d’erreur. Si la valeur retournée commence par un signe plus (« + »), moins (« - ») ou égal (« = »), Excel interprète cette valeur comme une formule.
valueTypes	Spécifie le type de données dans chaque cellule.
worksheet	Feuille de calcul contenant la plage.

Méthodes

clear(applyTo)	Effacez les valeurs de plage et la mise en forme, comme le remplissage et la bordure.
clear(applyToString)	Effacez les valeurs de plage et la mise en forme, comme le remplissage et la bordure.
delete(shift)	Supprime les cellules associées à la plage.
delete(shiftString)	Supprime les cellules associées à la plage.
getBoundingRect(anotherRange)	Renvoie le plus petit objet de plage qui englobe les plages données. Par exemple, « `GetBoundingRect` B2 :C5 » et « D10 :E15 » est « B2 :E15 ».
getCell(row, column)	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 sa plage parente, tant qu’elle reste dans la grille de 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)	Obtient une colonne contenue dans la plage.
getColumnsAfter(count)	Obtient un certain nombre de colonnes à droite de l’objet actuel `Range` .
getColumnsBefore(count)	Obtient un certain nombre de colonnes à gauche de l’objet actuel `Range` .
getEntireColumn()	Obtient un objet qui représente la colonne entière de la plage (par exemple, si la plage actuelle représente les cellules « B4 :E11 », il s’agit `getEntireColumn` d’une plage qui représente les colonnes « B :E »).
getEntireRow()	Obtient un objet qui représente la ligne entière de la plage (par exemple, si la plage actuelle représente les cellules « B4 :E11 », il s’agit `GetEntireRow` d’une plage qui représente les lignes « 4:11 »).
getIntersection(anotherRange)	Obtient l’objet de plage qui représente l’intersection rectangulaire des plages données.
getLastCell()	Obtient la dernière cellule de la plage. Par exemple, la dernière cellule de la plage « B2:D5 » est « D5 ».
getLastColumn()	Obtient la dernière colonne de la plage. Par exemple, la dernière colonne de la plage « B2:D5 » est « D2:D5 ».
getLastRow()	Obtient la dernière ligne de la plage. Par exemple, la dernière ligne de la plage « B2:D5 » est « B5:D5 ».
getOffsetRange(rowOffset, columnOffset)	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 à cette plage. Si la plage obtenue se retrouve en dehors des limites de grille de la feuille de calcul, une erreur est déclenchée.
getResizedRange(deltaRows, deltaColumns)	Obtient un `Range` objet similaire à l’objet actuel `Range` , mais avec son coin inférieur droit développé (ou contracté) par un certain nombre de lignes et de colonnes.
getRow(row)	Obtient une ligne contenue dans la plage.
getRowsAbove(count)	Obtient un certain nombre de lignes au-dessus de l’objet actuel `Range` .
getRowsBelow(count)	Obtient un certain nombre de lignes sous l’objet actuel `Range` .
getUsedRange(valuesOnly)	Renvoie la plage utilisée d’un objet de plage donné. Si aucune cellule n’est utilisée dans la plage, cette fonction génère une `ItemNotFound` erreur.
insert(shift)	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. Retourne un nouvel `Range` objet à l’espace maintenant vide.
insert(shiftString)	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. Retourne un nouvel `Range` objet à l’espace maintenant vide.
load(options)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNames)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
load(propertyNamesAndPaths)	Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter `context.sync()` avant de lire les propriétés.
merge(across)	Fusionne la plage de cellules dans une zone de la feuille de calcul.
select()	Sélectionne la plage spécifiée dans l’interface utilisateur d’Excel.
set(properties, options)	Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.
set(properties)	Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.
toJSON()	Remplace la méthode JavaScript `toJSON()` afin de fournir une sortie plus utile lorsqu’un objet API est passé à `JSON.stringify()`. (`JSON.stringify`appelle à son tour la `toJSON` méthode de l’objet qui lui est passé.) Alors que l’objet d’origine `Excel.Range` est un objet API, la `toJSON` méthode renvoie un objet JavaScript brut (typé en tant `Excel.Interfaces.RangeData`que ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.
track()	Effectuer le suivi de l’objet pour l’ajustement automatique en fonction environnant des modifications dans le document. Cet appel est un raccourci pour context.trackedObjects.add(thisObject). Si vous utilisez cet objet sur des `.sync` appels et en dehors de l’exécution séquentielle d’un lot « .run », et que vous obtenez une erreur « InvalidObjectPath » lors de la définition d’une propriété ou de l’appel d’une méthode sur l’objet, vous devez ajouter l’objet à la collection d’objets suivie lors de la première création de l’objet.
unmerge()	Annule la fusion de la plage de cellules.
untrack()	Publication mémoire associée à cet objet si elle a été précédemment suivie. Cet appel est abrégé pour context.trackedObjects.remove(thisObject). Vous rencontrez de nombreux objets suivies ralentit l’application hôte, donc n’oubliez pas de libérer les objets que l'on ajoute, une fois que vous avez terminé à les utiliser. Vous devez appeler `context.sync()` avant que la libération de la mémoire ne prenne effet.

Détails de la propriété

address

Spécifie la référence de plage dans le style A1. La valeur d’adresse contient la référence de la feuille (par exemple, « Sheet1 ! A1 :B4").

readonly address: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

addressLocal

Représente la référence de plage pour la plage spécifiée dans la langue de l’utilisateur.

readonly addressLocal: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

cellCount

Spécifie le nombre de cellules dans la plage. Cette API renvoie -1 si le nombre de cellules est supérieur à 2^31-1 (2 147 483 647).

readonly cellCount: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

columnCount

Spécifie le nombre total de colonnes dans la plage.

readonly columnCount: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

columnHidden

Représente si toutes les colonnes de la plage actuelle sont masquées. La valeur est true lorsque toutes les colonnes d’une plage sont masquées. La valeur est quand aucune colonne de la plage n’est false masquée. La valeur est null lorsque certaines colonnes d’une plage sont masquées et que d’autres colonnes de la même plage ne sont pas masquées.

columnHidden: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

columnIndex

Spécifie le numéro de colonne de la première cellule de la plage. Avec indice zéro.

readonly columnIndex: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

context

Contexte de requête associé à l’objet . Cela connecte le processus du complément au processus de l’application hôte Office.

context: RequestContext;

Valeur de propriété

Excel.RequestContext

format

Renvoie un objet de format, encapsulant la police, le remplissage, les bordures, l’alignement et d’autres propriétés de la plage.

readonly format: Excel.RangeFormat;

Valeur de propriété

Excel.RangeFormat

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

formulas

Représente la formule dans le style de notation A1. Si une cellule n’a pas de formule, sa valeur est retournée à la place.

formulas: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

formulasLocal

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. Si une cellule n’a pas de formule, sa valeur est retournée à la place.

formulasLocal: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

formulasR1C1

Représente la formule dans le style de notation R1C1. Si une cellule n’a pas de formule, sa valeur est retournée à la place.

formulasR1C1: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

hidden

Représente si toutes les cellules de la plage actuelle sont masquées. La valeur est true lorsque toutes les cellules d’une plage sont masquées. La valeur est quand aucune cellule de la plage n’est false masquée. La valeur est null lorsque certaines cellules d’une plage sont masquées et que d’autres cellules de la même plage ne sont pas masquées.

readonly hidden: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

numberFormat

Représente le code de format numérique d’Excel pour la plage donnée. Pour plus d’informations sur la mise en forme des nombres Excel, consultez Codes de format de nombre.

numberFormat: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

rowCount

Renvoie le nombre total de lignes de la plage.

readonly rowCount: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

rowHidden

Représente si toutes les lignes de la plage actuelle sont masquées. La valeur est true lorsque toutes les lignes d’une plage sont masquées. La valeur est quand aucune ligne de la plage n’est false masquée. La valeur est null lorsque certaines lignes d’une plage sont masquées et que d’autres lignes de la même plage ne sont pas masquées.

rowHidden: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

rowIndex

Renvoie le numéro de ligne de la première cellule de la plage. Avec indice zéro.

readonly rowIndex: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

sort

Représente le tri de plage de la plage actuelle.

readonly sort: Excel.RangeSort;

Valeur de propriété

Excel.RangeSort

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

text

Valeurs de texte de la plage spécifiée. La valeur de texte ne dépend pas de la largeur de la cellule. La substitution de signe numérique (#) qui se produit dans l’interface utilisateur Excel n’affecte pas la valeur de texte retournée par l’API.

readonly text: string[][];

Valeur de propriété

string[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

values

Représente les valeurs brutes de la plage spécifiée. Les données retournées peuvent être une chaîne, un nombre ou une valeur booléenne. Les cellules contenant une erreur renvoie la chaîne d’erreur. Si la valeur retournée commence par un signe plus (« + »), moins (« - ») ou égal (« = »), Excel interprète cette valeur comme une formule.

values: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

valueTypes

Spécifie le type de données dans chaque cellule.

readonly valueTypes: Excel.RangeValueType[][];

Valeur de propriété

Excel.RangeValueType[][]

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

worksheet

Feuille de calcul contenant la plage.

readonly worksheet: Excel.Worksheet;

Valeur de propriété

Excel.Worksheet

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Détails de la méthode

clear(applyTo)

Effacez les valeurs de plage et la mise en forme, comme le remplissage et la bordure.

clear(applyTo?: Excel.ClearApplyTo): void;

Paramètres

applyTo: Excel.ClearApplyTo

Optional. Détermine le type d’action de suppression. Pour plus d’informations, consultez Excel.ClearApplyTo .

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

clear(applyToString)

Effacez les valeurs de plage et la mise en forme, comme le remplissage et la bordure.

clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;

Paramètres

applyToString: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"

Optional. Détermine le type d’action de suppression. Pour plus d’informations, consultez Excel.ClearApplyTo .

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

delete(shift)

Supprime les cellules associées à la plage.

delete(shift: Excel.DeleteShiftDirection): void;

Paramètres

shift: Excel.DeleteShiftDirection

Indique la façon dont les cellules doivent être décalées. Pour plus d’informations, consultez Excel.DeleteShiftDirection .

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

delete(shiftString)

Supprime les cellules associées à la plage.

delete(shiftString: "Up" | "Left"): void;

Paramètres

shiftString: "Up" | "Left"

Indique la façon dont les cellules doivent être décalées. Pour plus d’informations, consultez Excel.DeleteShiftDirection .

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

getBoundingRect(anotherRange)

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

getBoundingRect(anotherRange: Range | string): Excel.Range;

Paramètres

anotherRange: Excel.Range | string

L’objet, l’adresse ou le nom de la plage.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

getCell(row, column)

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 sa plage parente, tant qu’elle reste dans la grille de feuille de calcul. L’emplacement de la cellule renvoyée est déterminé à partir de la cellule supérieure gauche de la plage.

getCell(row: number, column: number): Excel.Range;

Paramètres

row: number

Numéro de ligne de la cellule à récupérer. Avec indice zéro.

column: number

Numéro de colonne de la cellule à récupérer. Avec indice zéro.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

getColumn(column)

Obtient une colonne contenue dans la plage.

getColumn(column: number): Excel.Range;

Paramètres

column: number

Numéro de colonne de la plage à récupérer. Avec indice zéro.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

getColumnsAfter(count)

Obtient un certain nombre de colonnes à droite de l’objet actuel Range .

getColumnsAfter(count?: number): Excel.Range;

Paramètres

count: number

Optional. Nombre de colonnes à inclure dans la plage obtenue. En règle générale, utilisez un nombre positif pour créer une plage en dehors de la plage actuelle. Vous pouvez également utiliser un nombre négatif pour créer une plage à l’intérieur de la plage actuelle. La valeur par défaut est 1.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getColumnsBefore(count)

Obtient un certain nombre de colonnes à gauche de l’objet actuel Range .

getColumnsBefore(count?: number): Excel.Range;

Paramètres

count: number

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getEntireColumn()

Obtient un objet qui représente la colonne entière de la plage (par exemple, si la plage actuelle représente les cellules « B4 :E11 », il s’agit getEntireColumn d’une plage qui représente les colonnes « B :E »).

getEntireColumn(): Excel.Range;

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

getEntireRow()

Obtient un objet qui représente la ligne entière de la plage (par exemple, si la plage actuelle représente les cellules « B4 :E11 », il s’agit GetEntireRow d’une plage qui représente les lignes « 4:11 »).

getEntireRow(): Excel.Range;

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

getIntersection(anotherRange)

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

getIntersection(anotherRange: Range | string): Excel.Range;

Paramètres

anotherRange: Excel.Range | string

Objet de plage ou adresse de plage utilisé pour déterminer l’intersection des plages.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

getLastCell()

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

getLastCell(): Excel.Range;

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

getLastColumn()

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

getLastColumn(): Excel.Range;

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

getLastRow()

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

getLastRow(): Excel.Range;

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

getOffsetRange(rowOffset, columnOffset)

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 à cette plage. Si la plage obtenue se retrouve en dehors des limites de grille de la feuille de calcul, une erreur est déclenchée.

getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;

Paramètres

rowOffset: number

Nombre 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.

columnOffset: number

Nombre 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.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

getResizedRange(deltaRows, deltaColumns)

Obtient un Range objet similaire à l’objet actuel Range , mais avec son coin inférieur droit développé (ou contracté) par un certain nombre de lignes et de colonnes.

getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;

Paramètres

deltaRows: number

Nombre de lignes par lequel développer le coin inférieur droit, par rapport à la plage actuelle. Utilisez un nombre positif pour étendre la plage ou un nombre négatif pour la réduire.

deltaColumns: number

Nombre de colonnes par lesquelles développer le coin inférieur droit, par rapport à la plage actuelle. Utilisez un nombre positif pour étendre la plage ou un nombre négatif pour la réduire.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getRow(row)

Obtient une ligne contenue dans la plage.

getRow(row: number): Excel.Range;

Paramètres

row: number

Numéro de ligne de la plage à récupérer. Avec indice zéro.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

getRowsAbove(count)

Obtient un certain nombre de lignes au-dessus de l’objet actuel Range .

getRowsAbove(count?: number): Excel.Range;

Paramètres

count: number

Optional. Nombre de lignes à inclure dans la plage obtenue. En règle générale, utilisez un nombre positif pour créer une plage en dehors de la plage actuelle. Vous pouvez également utiliser un nombre négatif pour créer une plage à l’intérieur de la plage actuelle. La valeur par défaut est 1.

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getRowsBelow(count)

Obtient un certain nombre de lignes sous l’objet actuel Range .

getRowsBelow(count?: number): Excel.Range;

Paramètres

count: number

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getUsedRange(valuesOnly)

Renvoie la plage utilisée d’un objet de plage donné. Si aucune cellule n’est utilisée dans la plage, cette fonction génère une ItemNotFound erreur.

getUsedRange(valuesOnly?: boolean): Excel.Range;

Paramètres

valuesOnly: boolean

Prend uniquement en compte les cellules avec des valeurs sous forme de cellules utilisées. [Ensemble d’API : ExcelApi 1.2]

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

insert(shift)

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. Retourne un nouvel Range objet à l’espace maintenant vide.

insert(shift: Excel.InsertShiftDirection): Excel.Range;

Paramètres

shift: Excel.InsertShiftDirection

Indique la façon dont les cellules doivent être décalées. Pour plus d’informations, consultez Excel.InsertShiftDirection .

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

insert(shiftString)

insert(shiftString: "Down" | "Right"): Excel.Range;

Paramètres

shiftString: "Down" | "Right"

Indique la façon dont les cellules doivent être décalées. Pour plus d’informations, consultez Excel.InsertShiftDirection .

Retours

Excel.Range

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

load(options)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

Paramètres

options: Excel.Interfaces.RangeLoadOptions

Fournit des options pour les propriétés de l’objet à charger.

Retours

Excel.Range

load(propertyNames)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNames?: string | string[]): Excel.Range;

Paramètres

propertyNames: string | string[]

Chaîne délimitée par des virgules ou tableau de chaînes qui spécifient les propriétés à charger.

Retours

Excel.Range

Exemples

// Use the range address to get the range object.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8"; 
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

load(propertyNamesAndPaths)

Files d’attente de la commande pour charger les propriétés de l’objet spécifié. Vous devez contacter context.sync() avant de lire les propriétés.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Range;

Paramètres

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select est une chaîne délimitée par des virgules qui spécifie les propriétés à charger, et propertyNamesAndPaths.expand est une chaîne délimitée par des virgules qui spécifie les propriétés de navigation à charger.

Retours

Excel.Range

merge(across)

Fusionne la plage de cellules dans une zone de la feuille de calcul.

merge(across?: boolean): void;

Paramètres

across: boolean

Optional. Définissez true pour fusionner les cellules de chaque ligne de la plage spécifiée en tant que cellules fusionnées distinctes. La valeur par défaut est false.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.merge(true);
    await context.sync(); 
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

select()

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

select(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Exemples

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

set(properties, options)

Définit plusieurs propriétés d’un objet en même temps. Vous pouvez passer un objet brut avec les propriétés appropriées ou un autre objet API du même type.

set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;

Paramètres

properties: Excel.Interfaces.RangeUpdateData

Objet JavaScript avec des propriétés qui sont structurées isomorphes en fonction des propriétés de l’objet sur lequel la méthode est appelée.

options: OfficeExtension.UpdateOptions

Fournit une option permettant de supprimer les erreurs si l’objet properties tente de définir des propriétés en lecture seule.

Retours

void

set(properties)

Définit plusieurs propriétés sur l’objet en même temps, en fonction d’un objet chargé existant.

set(properties: Excel.Range): void;

Paramètres

properties: Excel.Range

Retours

void

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

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

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

toJSON()

Remplace la méthode JavaScript toJSON() afin de fournir une sortie plus utile lorsqu’un objet API est passé à JSON.stringify(). (JSON.stringifyappelle à son tour la toJSON méthode de l’objet qui lui est passé.) Alors que l’objet d’origine Excel.Range est un objet API, la toJSON méthode renvoie un objet JavaScript brut (typé en tant Excel.Interfaces.RangeDataque ) qui contient des copies superficielles de toutes les propriétés enfants chargées de l’objet d’origine.

toJSON(): Excel.Interfaces.RangeData;

Retours

Excel.Interfaces.RangeData

track()

Effectuer le suivi de l’objet pour l’ajustement automatique en fonction environnant des modifications dans le document. Cet appel est un raccourci pour context.trackedObjects.add(thisObject). Si vous utilisez cet objet sur des .sync appels et en dehors de l’exécution séquentielle d’un lot « .run », et que vous obtenez une erreur « InvalidObjectPath » lors de la définition d’une propriété ou de l’appel d’une méthode sur l’objet, vous devez ajouter l’objet à la collection d’objets suivie lors de la première création de l’objet.

track(): Excel.Range;

Retours

Excel.Range

unmerge()

Annule la fusion de la plage de cellules.

unmerge(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

Exemples

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.unmerge();
    await context.sync(); 
});

untrack()

Publication mémoire associée à cet objet si elle a été précédemment suivie. Cet appel est abrégé pour context.trackedObjects.remove(thisObject). Vous rencontrez de nombreux objets suivies ralentit l’application hôte, donc n’oubliez pas de libérer les objets que l'on ajoute, une fois que vous avez terminé à les utiliser. Vous devez appeler context.sync() avant que la libération de la mémoire ne prenne effet.

untrack(): Excel.Range;

Retours

Excel.Range

Exemples

await Excel.run(async (context) => {
    const largeRange = context.workbook.getSelectedRange();
    largeRange.load(["rowCount", "columnCount"]);
    await context.sync();

    for (let i = 0; i < largeRange.rowCount; i++) {
        for (let j = 0; j < largeRange.columnCount; j++) {
            const cell = largeRange.getCell(i, j);
            cell.values = [[i *j]];

            // Call untrack() to release the range from memory.
            cell.untrack();
        }
    }

    await context.sync();
});

Partager via

Excel.Range class

Remarques

Exemples

Propriétés

Méthodes

Détails de la propriété

address

Valeur de propriété

Remarques

addressLocal

Valeur de propriété

Remarques

cellCount

Valeur de propriété

Remarques

columnCount

Valeur de propriété

Remarques

columnHidden

Valeur de propriété

Remarques

columnIndex

Valeur de propriété

Remarques

context

Valeur de propriété

format

Valeur de propriété

Remarques

formulas

Valeur de propriété

Remarques

formulasLocal

Valeur de propriété

Remarques

formulasR1C1

Valeur de propriété

Remarques

hidden

Valeur de propriété

Remarques

numberFormat

Valeur de propriété

Remarques

Exemples

rowCount

Valeur de propriété

Remarques

rowHidden

Valeur de propriété

Remarques

rowIndex

Valeur de propriété

Remarques

sort

Valeur de propriété

Remarques

Exemples

text

Valeur de propriété

Remarques

values

Valeur de propriété

Remarques

valueTypes

Valeur de propriété

Remarques

worksheet

Valeur de propriété

Remarques

Détails de la méthode

clear(applyTo)

Paramètres

Retours

Remarques

Exemples

clear(applyToString)

Paramètres

Retours