Partager via


Excel.Range class

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

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.

conditionalFormats

Collection de ConditionalFormats qui croise la plage.

context

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

control

Accède au contrôle de cellule appliqué à cette plage. Si la plage a plusieurs contrôles de cellule, cette propriété retourne EmptyCellControl.

dataValidation

Renvoie un objet de validation des données.

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.

hasSpill

Représente si toutes les cellules ont une bordure renversée. Renvoie true si toutes les cellules ont une bordure de déversement, ou false si toutes les cellules n’ont pas de bordure de déversement. Retourne null s’il existe des cellules avec et sans bordures de déversement dans la plage.

height

Retourne la distance en points, pour un zoom à 100 %, entre le bord supérieur de la plage et le bord inférieur de la plage.

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.

hyperlink

Représente le lien hypertexte pour la plage actuelle.

isEntireColumn

Représente si la plage active est une colonne entière.

isEntireRow

Représente si la plage active est une ligne entière.

left

Retourne la distance en points, pour un zoom à 100 %, entre le bord gauche de la feuille de calcul et le bord gauche de la plage.

linkedDataTypeState

Représente l’état du type de données de chaque cellule.

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.

numberFormatCategories

Représente la catégorie de format numérique de chaque cellule.

numberFormatLocal

Représente le code de format numérique d’Excel pour la plage donnée, en fonction des paramètres de langue de l’utilisateur. Excel n’effectue aucune contrainte de langage ou de mise en forme lors de l’obtention ou de la définition de la numberFormatLocal propriété. Tout texte retourné utilise les chaînes mises en forme localement en fonction de la langue spécifiée dans les paramètres système.

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.

savedAsArray

Représente si toutes les cellules doivent être enregistrées sous forme de formule matricielle. Retourne true si toutes les cellules sont enregistrées en tant que formule matricielle, ou false si toutes les cellules ne sont pas enregistrées en tant que formule matricielle. Renvoie null si certaines cellules sont enregistrées en tant que formule matricielle et que d’autres ne le sont pas.

sort

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

style

Représente le style de la plage actuelle. Si les styles des cellules sont incohérents, null est retourné. Pour les styles personnalisés, le nom du style est retourné. Pour les styles intégrés, une chaîne représentant une valeur dans l’énumération BuiltInStyle est retournée.

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.

top

Retourne la distance en points, pour un zoom à 100 %, entre le bord supérieur de la feuille de calcul et le bord supérieur de la plage.

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.

valuesAsJson

Représentation JSON des valeurs dans les cellules de cette plage. Contrairement à Range.values, Range.valuesAsJson prend en charge tous les types de données qui peuvent se trouver dans une cellule. Les exemples incluent les valeurs numériques mises en forme et les images web, en plus des valeurs booléennes, numériques et de chaînes standard. Les données retournées par cette API s’alignent toujours sur les paramètres régionaux en-US. Pour récupérer des données dans les paramètres régionaux d’affichage de l’utilisateur, utilisez Range.valuesAsJsonLocal.

valuesAsJsonLocal

Représentation JSON des valeurs dans les cellules de cette plage. Contrairement à Range.values, Range.valuesAsJsonLocal prend en charge tous les types de données qui peuvent se trouver dans une cellule. Les exemples incluent les valeurs numériques mises en forme et les images web, en plus des valeurs booléennes, numériques et de chaînes standard. Les données retournées par cette API s’alignent toujours sur les paramètres régionaux d’affichage de l’utilisateur. Pour récupérer des données indépendamment des paramètres régionaux, utilisez Range.valuesAsJson.

valueTypes

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

width

Retourne la distance en points, pour un zoom de 100 %, entre le bord gauche de la plage et le bord droit de la plage.

worksheet

Feuille de calcul contenant la plage.

Méthodes

autoFill(destinationRange, autoFillType)

Remplit une plage de la plage actuelle à la plage de destination à l’aide de la logique de remplissage automatique spécifiée. La plage de destination peut être null ou étendre la plage source horizontalement ou verticalement. Les plages discontiguées ne sont pas prises en charge.

Pour plus d’informations, consultez Utiliser le remplissage automatique et le remplissage instantané.

autoFill(destinationRange, autoFillTypeString)

Remplit une plage de la plage actuelle à la plage de destination à l’aide de la logique de remplissage automatique spécifiée. La plage de destination peut être null ou étendre la plage source horizontalement ou verticalement. Les plages discontiguées ne sont pas prises en charge.

Pour plus d’informations, consultez Utiliser le remplissage automatique et le remplissage instantané.

calculate()

Calcule une plage de cellules dans une feuille de calcul.

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.

clearOrResetContents()

Efface les valeurs des cellules de la plage, avec une attention particulière accordée aux cellules contenant des contrôles. Si la plage contient uniquement des valeurs vides et des contrôles définis sur leur valeur par défaut, les valeurs et la mise en forme des contrôles sont supprimées. Sinon, cela définit les cellules avec des contrôles sur leur valeur par défaut et efface les valeurs des autres cellules de la plage.

convertDataTypeToText()

Convertit les cellules de plage avec des types de données en texte.

convertToLinkedDataType(serviceID, languageCulture)

Convertit les cellules de plage en types de données liés dans la feuille de calcul.

copyFrom(sourceRange, copyType, skipBlanks, transpose)

Copie les données de cellule ou la mise en forme de la plage source ou RangeAreas vers la plage actuelle. La plage de destination peut avoir une taille différente de celle de la plage source ou RangeAreas. La destination est développée automatiquement si elle est plus petite que la source. Remarque : Comme la fonctionnalité de copie dans l’interface utilisateur Excel, si la plage de destination est un multiple exact supérieur à la plage source dans les lignes ou les colonnes, le contenu source est répliqué plusieurs fois. Par exemple, une copie de plage 2x2 dans une plage 2x6 entraîne 3 copies de la plage 2x2 d’origine.

copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)

Copie les données de cellule ou la mise en forme de la plage source ou RangeAreas vers la plage actuelle. La plage de destination peut avoir une taille différente de celle de la plage source ou RangeAreas. La destination est développée automatiquement si elle est plus petite que la source. Remarque : Comme la fonctionnalité de copie dans l’interface utilisateur Excel, si la plage de destination est un multiple exact supérieur à la plage source dans les lignes ou les colonnes, le contenu source est répliqué plusieurs fois. Par exemple, une copie de plage 2x2 dans une plage 2x6 entraîne 3 copies de la plage 2x2 d’origine.

delete(shift)

Supprime les cellules associées à la plage.

delete(shiftString)

Supprime les cellules associées à la plage.

find(text, criteria)

Recherche la chaîne donnée basée sur les critères spécifiés. Si la plage actuelle est supérieure à une seule cellule, la recherche est limitée à cette plage, sinon la recherche couvre la feuille entière à partir de cette cellule.

findOrNullObject(text, criteria)

Recherche la chaîne donnée basée sur les critères spécifiés. Si la plage actuelle est supérieure à une seule cellule, la recherche est limitée à cette plage, sinon la recherche couvre la feuille entière à partir de cette cellule. S’il n’existe aucune correspondance, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

flashFill()

Effectue un remplissage instantané sur la plage actuelle. Le remplissage instantané remplit automatiquement les données lorsqu’il détecte un modèle. La plage doit donc être une seule plage de colonnes et contenir des données autour de celle-ci pour trouver un modèle.

getAbsoluteResizedRange(numRows, numColumns)

Obtient un Range objet avec la même cellule en haut à gauche que l’objet actuel Range , mais avec le nombre spécifié de lignes et de colonnes.

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.

getCellProperties(cellPropertiesLoadOptions)

Renvoie une plage en 2D, qui comprend les propriétés de police, de remplissage, de bordures, d’alignement, etc. de la plage.

getColumn(column)

Obtient une colonne contenue dans la plage.

getColumnProperties(columnPropertiesLoadOptions)

Renvoie une plage à dimension unique, qui comprend les données de char colonne de police, de remplissage, de bordures, d’alignement, etc. de la plage. Pour les propriétés ne sont pas cohérentes au sein de chaque cellule dans une colonne donnée, null est renvoyé.

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 .

getDependents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules dépendantes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun dépendant n’est trouvé.

getDirectDependents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules dépendantes directes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun dépendant n’est trouvé.

getDirectPrecedents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules de précédent direct d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun précédent n’est trouvé.

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 »).

getExtendedRange(direction, activeCell)

Retourne un objet de plage qui inclut la plage actuelle et jusqu’au bord de la plage, en fonction de la direction fournie. Cela correspond au comportement Ctrl+Maj+Touche de direction dans l’interface utilisateur Excel sur Windows.

getExtendedRange(directionString, activeCell)

Retourne un objet de plage qui inclut la plage actuelle et jusqu’au bord de la plage, en fonction de la direction fournie. Cela correspond au comportement Ctrl+Maj+Touche de direction dans l’interface utilisateur Excel sur Windows.

getImage()

Restitue la plage sous la forme d’une image png encodée en Base64. Important* : cette API n’est actuellement pas prise en charge dans Excel pour Mac. Visitez OfficeDev/office-js Issue #235 pour connaître la status actuelle.

getIntersection(anotherRange)

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

getIntersectionOrNullObject(anotherRange)

Obtient l’objet de plage qui représente l’intersection rectangulaire des plages données. Si aucune intersection n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

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

getMergedAreasOrNullObject()

Renvoie un RangeAreas objet qui représente les zones fusionnées dans cette plage. Notez que si le nombre de zones fusionnées dans cette plage est supérieur à 512, cette méthode ne retourne pas le résultat. Si l’objet RangeAreas n’existe pas, cette fonction retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

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.

getPivotTables(fullyContained)

Obtient une collection délimitée de tableaux croisés dynamiques qui chevauchent la plage.

getPrecedents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules précédentes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun précédent n’est trouvé.

getRangeEdge(direction, activeCell)

Retourne un objet de plage qui est la cellule de bord de la région de données qui correspond à la direction fournie. Cela correspond au comportement ctrl+touche de direction dans l’interface utilisateur d’Excel sur Windows.

getRangeEdge(directionString, activeCell)

Retourne un objet de plage qui est la cellule de bord de la région de données qui correspond à la direction fournie. Cela correspond au comportement ctrl+touche de direction dans l’interface utilisateur d’Excel sur Windows.

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.

getRowProperties(rowPropertiesLoadOptions)

Renvoie une plage à dimension unique , qui comprend les données de police, de remplissage, de bordures, d’alignement, etc. de la plage. Pour les propriétés qui ne sont pas cohérentes dans chaque cellule d’une ligne donnée, null est retourné.

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 .

getSpecialCells(cellType, cellValueType)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages rectangulaires, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, une ItemNotFound erreur est générée.

getSpecialCells(cellTypeString, cellValueTypeString)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages rectangulaires, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, une ItemNotFound erreur est générée.

getSpecialCellsOrNullObject(cellType, cellValueType)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpillingToRange()

Obtient l’objet de la plage contenant la plage renversé lorsque appelée sur une cellule d’ancrage. Échoue si appliqué à une plage comportant plusieurs cellules.

getSpillingToRangeOrNullObject()

Obtient l’objet de la plage contenant la plage renversé lorsque appelée sur une cellule d’ancrage. Si la plage n’est pas une cellule d’ancre ou si la plage de déversement est introuvable, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpillParent()

Obtient l’objet de la plage contenant la cellule d’ancrage d’une cellule prise renversée dans. Échoue si appliqué à une plage comportant plusieurs cellules.

getSpillParentOrNullObject()

Obtient l’objet de plage contenant la cellule d’ancrage pour la cellule qui est renversée. S’il ne s’agit pas d’une cellule renversée ou si plusieurs cellules sont fournies, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSurroundingRegion()

Renvoie un Range objet qui représente la région environnante pour la cellule en haut à gauche de cette plage. Une région environnante est une plage délimitée par une combinaison de lignes et de colonnes vides par rapport à cette plage.

getTables(fullyContained)

Obtient une collection de tableaux qui se chevauchent avec la plage dans l’étendue.

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.

getUsedRangeOrNullObject(valuesOnly)

Renvoie la plage utilisée d’un objet de plage donné. Si aucune cellule n’est utilisée dans la plage, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getVisibleView()

Représente les lignes visibles de la plage en cours.

group(groupOption)

Groupes colonnes et lignes d’un plan.

group(groupOptionString)

Groupes colonnes et lignes d’un plan.

hideGroupDetails(groupOption)

Masque les détails du groupe de lignes ou de colonnes.

hideGroupDetails(groupOptionString)

Masque les détails du groupe de lignes ou de colonnes.

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.

moveTo(destinationRange)

Déplace les valeurs de cellule, la mise en forme et les formules de la plage actuelle vers la plage de destination, en remplaçant les anciennes informations dans ces cellules. La plage de destination est développée automatiquement si elle est plus petite que la plage actuelle. Les cellules de la plage de destination qui se trouvent en dehors de la zone de la plage d’origine ne sont pas modifiées.

removeDuplicates(columns, includesHeader)

Supprime les valeurs dupliquées de la plage spécifiée par les colonnes.

replaceAll(text, replacement, criteria)

Détecte et remplace la chaîne donnée basée sur les critères spécifiés dans la plage active.

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.

setCellProperties(cellPropertiesData)

Mises à jour la plage en fonction d’un tableau 2D de propriétés de cellule, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

setColumnProperties(columnPropertiesData)

Mises à jour la plage en fonction d’un tableau unidimensionnel de propriétés de colonne, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

setDirty()

Cette méthode désigne une plage qui doit être recalculée lorsque le recalcul suivant se produit.

setRowProperties(rowPropertiesData)

Mises à jour la plage en fonction d’un tableau unidimensionnel de propriétés de ligne, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

showCard()

Affiche la carte pour une cellule active si son contenu est riche en valeur.

showGroupDetails(groupOption)

Affiche les détails du groupe de lignes ou de colonnes.

showGroupDetails(groupOptionString)

Affiche les détails du groupe de lignes ou de colonnes.

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.

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.

ungroup(groupOption)

Dissocie les colonnes et les lignes d’un plan.

ungroup(groupOptionString)

Dissocie les colonnes et les lignes d’un plan.

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 ]

conditionalFormats

Collection de ConditionalFormats qui croise la plage.

readonly conditionalFormats: Excel.ConditionalFormatCollection;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

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é

control

Notes

Cet API est fourni en tant qu’aperçu pour les développeurs et peut être modifié en fonction des commentaires que nous avons reçus. N’utilisez pas cet API dans un environnement de production.

Accède au contrôle de cellule appliqué à cette plage. Si la plage a plusieurs contrôles de cellule, cette propriété retourne EmptyCellControl.

control: CellControl;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi BETA (PRÉVERSION UNIQUEMENT) ]

dataValidation

Renvoie un objet de validation des données.

readonly dataValidation: Excel.DataValidation;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.8 ]

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é

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 ]

hasSpill

Représente si toutes les cellules ont une bordure renversée. Renvoie true si toutes les cellules ont une bordure de déversement, ou false si toutes les cellules n’ont pas de bordure de déversement. Retourne null s’il existe des cellules avec et sans bordures de déversement dans la plage.

readonly hasSpill: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

height

Retourne la distance en points, pour un zoom à 100 %, entre le bord supérieur de la plage et le bord inférieur de la plage.

readonly height: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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 ]

Représente le lien hypertexte pour la plage actuelle.

hyperlink: Excel.RangeHyperlink;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

Exemples

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

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

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

isEntireColumn

Représente si la plage active est une colonne entière.

readonly isEntireColumn: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

isEntireRow

Représente si la plage active est une ligne entière.

readonly isEntireRow: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

left

Retourne la distance en points, pour un zoom à 100 %, entre le bord gauche de la feuille de calcul et le bord gauche de la plage.

readonly left: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

linkedDataTypeState

Représente l’état du type de données de chaque cellule.

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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);
});

numberFormatCategories

Représente la catégorie de format numérique de chaque cellule.

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

numberFormatLocal

Représente le code de format numérique d’Excel pour la plage donnée, en fonction des paramètres de langue de l’utilisateur. Excel n’effectue aucune contrainte de langage ou de mise en forme lors de l’obtention ou de la définition de la numberFormatLocal propriété. Tout texte retourné utilise les chaînes mises en forme localement en fonction de la langue spécifiée dans les paramètres système.

numberFormatLocal: any[][];

Valeur de propriété

any[][]

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

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 ]

savedAsArray

Représente si toutes les cellules doivent être enregistrées sous forme de formule matricielle. Retourne true si toutes les cellules sont enregistrées en tant que formule matricielle, ou false si toutes les cellules ne sont pas enregistrées en tant que formule matricielle. Renvoie null si certaines cellules sont enregistrées en tant que formule matricielle et que d’autres ne le sont pas.

readonly savedAsArray: boolean;

Valeur de propriété

boolean

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

sort

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

readonly sort: Excel.RangeSort;

Valeur de propriété

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();
    });
}

style

Représente le style de la plage actuelle. Si les styles des cellules sont incohérents, null est retourné. Pour les styles personnalisés, le nom du style est retourné. Pour les styles intégrés, une chaîne représentant une valeur dans l’énumération BuiltInStyle est retournée.

style: string;

Valeur de propriété

string

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

Exemples

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

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    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 ]

top

Retourne la distance en points, pour un zoom à 100 %, entre le bord supérieur de la feuille de calcul et le bord supérieur de la plage.

readonly top: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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 ]

valuesAsJson

Représentation JSON des valeurs dans les cellules de cette plage. Contrairement à Range.values, Range.valuesAsJson prend en charge tous les types de données qui peuvent se trouver dans une cellule. Les exemples incluent les valeurs numériques mises en forme et les images web, en plus des valeurs booléennes, numériques et de chaînes standard. Les données retournées par cette API s’alignent toujours sur les paramètres régionaux en-US. Pour récupérer des données dans les paramètres régionaux d’affichage de l’utilisateur, utilisez Range.valuesAsJsonLocal.

valuesAsJson: CellValue[][];

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.16 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a formatted number data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.formattedNumber,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

valuesAsJsonLocal

Représentation JSON des valeurs dans les cellules de cette plage. Contrairement à Range.values, Range.valuesAsJsonLocal prend en charge tous les types de données qui peuvent se trouver dans une cellule. Les exemples incluent les valeurs numériques mises en forme et les images web, en plus des valeurs booléennes, numériques et de chaînes standard. Les données retournées par cette API s’alignent toujours sur les paramètres régionaux d’affichage de l’utilisateur. Pour récupérer des données indépendamment des paramètres régionaux, utilisez Range.valuesAsJson.

valuesAsJsonLocal: CellValue[][];

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.16 ]

valueTypes

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

readonly valueTypes: Excel.RangeValueType[][];

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

width

Retourne la distance en points, pour un zoom de 100 %, entre le bord gauche de la plage et le bord droit de la plage.

readonly width: number;

Valeur de propriété

number

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

worksheet

Feuille de calcul contenant la plage.

readonly worksheet: Excel.Worksheet;

Valeur de propriété

Remarques

[ Ensemble d’API : ExcelApi 1.1 ]

Détails de la méthode

autoFill(destinationRange, autoFillType)

Remplit une plage de la plage actuelle à la plage de destination à l’aide de la logique de remplissage automatique spécifiée. La plage de destination peut être null ou étendre la plage source horizontalement ou verticalement. Les plages discontiguées ne sont pas prises en charge.

Pour plus d’informations, consultez Utiliser le remplissage automatique et le remplissage instantané.

autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;

Paramètres

destinationRange

Excel.Range | string

Plage de destination du remplissage automatique. Si la plage de destination est null, les données sont remplies en fonction des cellules environnantes (qui est le comportement lorsque vous double-cliquez sur la poignée de remplissage de plage de l’interface utilisateur).

autoFillType
Excel.AutoFillType

Type de remplissage automatique. Spécifie la façon dont la plage de destination doit être remplie, en fonction du contenu de la plage actuelle. La valeur par défaut est « FillDefault ».

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9, ExcelApi Preview pour null destinationRange ]

Exemples

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

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

autoFill(destinationRange, autoFillTypeString)

Remplit une plage de la plage actuelle à la plage de destination à l’aide de la logique de remplissage automatique spécifiée. La plage de destination peut être null ou étendre la plage source horizontalement ou verticalement. Les plages discontiguées ne sont pas prises en charge.

Pour plus d’informations, consultez Utiliser le remplissage automatique et le remplissage instantané.

autoFill(destinationRange?: Range | string, autoFillTypeString?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

Paramètres

destinationRange

Excel.Range | string

Plage de destination du remplissage automatique. Si la plage de destination est null, les données sont remplies en fonction des cellules environnantes (qui est le comportement lorsque vous double-cliquez sur la poignée de remplissage de plage de l’interface utilisateur).

autoFillTypeString

"FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"

Type de remplissage automatique. Spécifie la façon dont la plage de destination doit être remplie, en fonction du contenu de la plage actuelle. La valeur par défaut est « FillDefault ».

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9, ExcelApi Preview pour null destinationRange ]

calculate()

Calcule une plage de cellules dans une feuille de calcul.

calculate(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.6 ]

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" | "ResetContents"): void;

Paramètres

applyToString

"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"

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 ]

clearOrResetContents()

Notes

Cet API est fourni en tant qu’aperçu pour les développeurs et peut être modifié en fonction des commentaires que nous avons reçus. N’utilisez pas cet API dans un environnement de production.

Efface les valeurs des cellules de la plage, avec une attention particulière accordée aux cellules contenant des contrôles. Si la plage contient uniquement des valeurs vides et des contrôles définis sur leur valeur par défaut, les valeurs et la mise en forme des contrôles sont supprimées. Sinon, cela définit les cellules avec des contrôles sur leur valeur par défaut et efface les valeurs des autres cellules de la plage.

clearOrResetContents(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi BETA (PRÉVERSION UNIQUEMENT) ]

convertDataTypeToText()

Convertit les cellules de plage avec des types de données en texte.

convertDataTypeToText(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

convertToLinkedDataType(serviceID, languageCulture)

Convertit les cellules de plage en types de données liés dans la feuille de calcul.

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

Paramètres

serviceID

number

ID de service qui sera utilisé pour interroger les données.

languageCulture

string

Culture de langage pour laquelle interroger le service.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

copyFrom(sourceRange, copyType, skipBlanks, transpose)

Copie les données de cellule ou la mise en forme de la plage source ou RangeAreas vers la plage actuelle. La plage de destination peut avoir une taille différente de celle de la plage source ou RangeAreas. La destination est développée automatiquement si elle est plus petite que la source. Remarque : Comme la fonctionnalité de copie dans l’interface utilisateur Excel, si la plage de destination est un multiple exact supérieur à la plage source dans les lignes ou les colonnes, le contenu source est répliqué plusieurs fois. Par exemple, une copie de plage 2x2 dans une plage 2x6 entraîne 3 copies de la plage 2x2 d’origine.

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

Paramètres

sourceRange

Excel.Range | Excel.RangeAreas | string

Plage source ou RangeAreas à partir de laquelle effectuer la copie. Lorsque la source RangeAreas a plusieurs plages, sa forme doit pouvoir être créée en supprimant des lignes ou des colonnes complètes d’une plage rectangulaire.

copyType
Excel.RangeCopyType

Type de données de cellule ou de mise en forme à copier. La valeur par défaut est « All ».

skipBlanks

boolean

True si pour ignorer les cellules vides dans la plage source. La valeur par défaut est False.

transpose

boolean

True si pour transposer les cellules dans la plage de destination. La valeur par défaut est False.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)

Copie les données de cellule ou la mise en forme de la plage source ou RangeAreas vers la plage actuelle. La plage de destination peut avoir une taille différente de celle de la plage source ou RangeAreas. La destination est développée automatiquement si elle est plus petite que la source. Remarque : Comme la fonctionnalité de copie dans l’interface utilisateur Excel, si la plage de destination est un multiple exact supérieur à la plage source dans les lignes ou les colonnes, le contenu source est répliqué plusieurs fois. Par exemple, une copie de plage 2x2 dans une plage 2x6 entraîne 3 copies de la plage 2x2 d’origine.

copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths", skipBlanks?: boolean, transpose?: boolean): void;

Paramètres

sourceRange

Excel.Range | Excel.RangeAreas | string

Plage source ou RangeAreas à partir de laquelle effectuer la copie. Lorsque la source RangeAreas a plusieurs plages, sa forme doit pouvoir être créée en supprimant des lignes ou des colonnes complètes d’une plage rectangulaire.

copyTypeString

"All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths"

Type de données de cellule ou de mise en forme à copier. La valeur par défaut est « All ».

skipBlanks

boolean

True si pour ignorer les cellules vides dans la plage source. La valeur par défaut est False.

transpose

boolean

True si pour transposer les cellules dans la plage de destination. La valeur par défaut est False.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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 ]

find(text, criteria)

Recherche la chaîne donnée basée sur les critères spécifiés. Si la plage actuelle est supérieure à une seule cellule, la recherche est limitée à cette plage, sinon la recherche couvre la feuille entière à partir de cette cellule.

find(text: string, criteria: Excel.SearchCriteria): Excel.Range;

Paramètres

text

string

Chaîne à rechercher.

criteria
Excel.SearchCriteria

Critères de recherche supplémentaires, notamment le sens de la recherche et si la recherche doit correspondre à la cellule entière ou respecter la casse.

Retours

Objet Range représentant la première cellule qui contient une valeur correspondant au texte et aux critères de recherche.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

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

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const foundRange = searchRange.find($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();


    console.log(foundRange.address);
});

findOrNullObject(text, criteria)

Recherche la chaîne donnée basée sur les critères spécifiés. Si la plage actuelle est supérieure à une seule cellule, la recherche est limitée à cette plage, sinon la recherche couvre la feuille entière à partir de cette cellule. S’il n’existe aucune correspondance, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

Paramètres

text

string

Chaîne à rechercher.

criteria
Excel.SearchCriteria

Critères de recherche supplémentaires, notamment le sens de la recherche et si la recherche doit correspondre à la cellule entière ou respecter la casse.

Retours

Range qui correspond aux critères de recherche.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const foundRange = searchRange.findOrNullObject($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

flashFill()

Effectue un remplissage instantané sur la plage actuelle. Le remplissage instantané remplit automatiquement les données lorsqu’il détecte un modèle. La plage doit donc être une seule plage de colonnes et contenir des données autour de celle-ci pour trouver un modèle.

flashFill(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

getAbsoluteResizedRange(numRows, numColumns)

Obtient un Range objet avec la même cellule en haut à gauche que l’objet actuel Range , mais avec le nombre spécifié de lignes et de colonnes.

getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;

Paramètres

numRows

number

Nombre de lignes de la nouvelle taille de plage.

numColumns

number

Nombre de colonnes de la nouvelle taille de plage.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

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

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

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);
});

getCellProperties(cellPropertiesLoadOptions)

Renvoie une plage en 2D, qui comprend les propriétés de police, de remplissage, de bordures, d’alignement, etc. de la plage.

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

Paramètres

cellPropertiesLoadOptions
Excel.CellPropertiesLoadOptions

Objet qui représente les propriétés de cellule à charger.

Retours

Tableau 2D où chaque élément représente les propriétés demandées de la cellule correspondante.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

await Excel.run(async (context) => {
    const cell = context.workbook.getActiveCell();

    // Define the cell properties to get by setting the matching LoadOptions to true.
    const propertiesToGet = cell.getCellProperties({
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                color: true
            }
        },
        style: true
    });

    // Sync to get the data from the workbook.
    await context.sync();
    const cellProperties = propertiesToGet.value[0][0];
    console.log(
        `Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
});

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

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
});

getColumnProperties(columnPropertiesLoadOptions)

Renvoie une plage à dimension unique, qui comprend les données de char colonne de police, de remplissage, de bordures, d’alignement, etc. de la plage. Pour les propriétés ne sont pas cohérentes au sein de chaque cellule dans une colonne donnée, null est renvoyé.

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

Paramètres

columnPropertiesLoadOptions
Excel.ColumnPropertiesLoadOptions

Objet qui représente les propriétés de colonne à charger.

Retours

Tableau dans lequel chaque élément représente les propriétés demandées de la colonne correspondante.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

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

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

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getDependents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules dépendantes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun dépendant n’est trouvé.

getDependents(): Excel.WorkbookRangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.15 ]

Exemples

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

// This function highlights all the dependent cells of the active cell.
// Dependent cells contain formulas that refer to other cells.
await Excel.run(async (context) => {
  // Get addresses of the active cell's dependent cells.
  const range = context.workbook.getActiveCell();
  const dependents = range.getDependents();
  range.load("address");
  dependents.areas.load("address");
  await context.sync();

  console.log(`All dependent cells of ${range.address}:`);

  // Use the dependents API to loop through dependents of the active cell.
  for (let i = 0; i < dependents.areas.items.length; i++) {
    // Highlight and print out the address of each dependent cell.
    dependents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${dependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectDependents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules dépendantes directes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun dépendant n’est trouvé.

getDirectDependents(): Excel.WorkbookRangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

Exemples

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

await Excel.run(async (context) => {
  // Direct dependents are cells that contain formulas that refer to other cells.
  let range = context.workbook.getActiveCell();
  let directDependents = range.getDirectDependents();
  range.load("address");
  directDependents.areas.load("address");
  await context.sync();
  
  console.log(`Direct dependent cells of ${range.address}:`);
  
  // Use the direct dependents API to loop through direct dependents of the active cell.
  for (let i = 0; i < directDependents.areas.items.length; i++) {
    // Highlight and print the address of each dependent cell.
    directDependents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directDependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectPrecedents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules de précédent direct d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun précédent n’est trouvé.

getDirectPrecedents(): Excel.WorkbookRangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

Exemples

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

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  // A "direct precedent" is a cell directly referenced by the selected formula.
  let range = context.workbook.getActiveCell();
  let directPrecedents = range.getDirectPrecedents();
  range.load("address");
  directPrecedents.areas.load("address");
  await context.sync();

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
  await context.sync();
});

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

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

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);
});

getExtendedRange(direction, activeCell)

Retourne un objet de plage qui inclut la plage actuelle et jusqu’au bord de la plage, en fonction de la direction fournie. Cela correspond au comportement Ctrl+Maj+Touche de direction dans l’interface utilisateur Excel sur Windows.

getExtendedRange(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

Paramètres

direction
Excel.KeyboardDirection

Direction à partir de la cellule active.

activeCell

Excel.Range | string

Cellule active de cette plage. Par défaut, la cellule active est la cellule supérieure gauche de la plage. Une erreur est générée si la cellule active ne se trouve pas dans cette plage.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

Exemples

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

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

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get all the cells from the currently selected range to the bottom-most edge of the used range.
  // This method acts like the Ctrl+Shift+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

getExtendedRange(directionString, activeCell)

Retourne un objet de plage qui inclut la plage actuelle et jusqu’au bord de la plage, en fonction de la direction fournie. Cela correspond au comportement Ctrl+Maj+Touche de direction dans l’interface utilisateur Excel sur Windows.

getExtendedRange(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Paramètres

directionString

"Left" | "Right" | "Up" | "Down"

Direction à partir de la cellule active.

activeCell

Excel.Range | string

Cellule active de cette plage. Par défaut, la cellule active est la cellule supérieure gauche de la plage. Une erreur est générée si la cellule active ne se trouve pas dans cette plage.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

getImage()

Restitue la plage sous la forme d’une image png encodée en Base64. Important* : cette API n’est actuellement pas prise en charge dans Excel pour Mac. Visitez OfficeDev/office-js Issue #235 pour connaître la status actuelle.

getImage(): OfficeExtension.ClientResult<string>;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

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

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
});

getIntersectionOrNullObject(anotherRange)

Obtient l’objet de plage qui représente l’intersection rectangulaire des plages données. Si aucune intersection n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getIntersectionOrNullObject(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

Remarques

[ Ensemble d’API : ExcelApi 1.4 ]

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();
});

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

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

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

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
});

getMergedAreasOrNullObject()

Renvoie un RangeAreas objet qui représente les zones fusionnées dans cette plage. Notez que si le nombre de zones fusionnées dans cette plage est supérieur à 512, cette méthode ne retourne pas le résultat. Si l’objet RangeAreas n’existe pas, cette fonction retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getMergedAreasOrNullObject(): Excel.RangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

Exemples

// 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");

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

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

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
});

getPivotTables(fullyContained)

Obtient une collection délimitée de tableaux croisés dynamiques qui chevauchent la plage.

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

Paramètres

fullyContained

boolean

Si truela valeur est , retourne uniquement les tableaux croisés dynamiques qui sont entièrement contenus dans les limites de plage. La valeur par défaut est false.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

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

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

getPrecedents()

Renvoie un WorkbookRangeAreas objet qui représente la plage contenant toutes les cellules précédentes d’une plage spécifiée dans la même feuille de calcul ou dans plusieurs feuilles de calcul. Remarque : cette API retourne une ItemNotFound erreur si aucun précédent n’est trouvé.

getPrecedents(): Excel.WorkbookRangeAreas;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.14 ]

Exemples

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

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  let range = context.workbook.getActiveCell();
  let precedents = range.getPrecedents();
  range.load("address");
  precedents.areas.load("address");
  await context.sync();

  console.log(`All precedent cells of ${range.address}:`);

  // Use the precedents API to loop through precedents of the active cell.
  for (let i = 0; i < precedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    precedents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${precedents.areas.items[i].address}`);
  }
  await context.sync();
});

getRangeEdge(direction, activeCell)

Retourne un objet de plage qui est la cellule de bord de la région de données qui correspond à la direction fournie. Cela correspond au comportement ctrl+touche de direction dans l’interface utilisateur d’Excel sur Windows.

getRangeEdge(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

Paramètres

direction
Excel.KeyboardDirection

Direction à partir de la cellule active.

activeCell

Excel.Range | string

Cellule active de cette plage. Par défaut, la cellule active est la cellule supérieure gauche de la plage. Une erreur est générée si la cellule active ne se trouve pas dans cette plage.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

Exemples

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

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

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

getRangeEdge(directionString, activeCell)

Retourne un objet de plage qui est la cellule de bord de la région de données qui correspond à la direction fournie. Cela correspond au comportement ctrl+touche de direction dans l’interface utilisateur d’Excel sur Windows.

getRangeEdge(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

Paramètres

directionString

"Left" | "Right" | "Up" | "Down"

Direction à partir de la cellule active.

activeCell

Excel.Range | string

Cellule active de cette plage. Par défaut, la cellule active est la cellule supérieure gauche de la plage. Une erreur est générée si la cellule active ne se trouve pas dans cette plage.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.13 ]

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

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

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
});

getRowProperties(rowPropertiesLoadOptions)

Renvoie une plage à dimension unique , qui comprend les données de police, de remplissage, de bordures, d’alignement, etc. de la plage. Pour les propriétés qui ne sont pas cohérentes dans chaque cellule d’une ligne donnée, null est retourné.

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

Paramètres

rowPropertiesLoadOptions
Excel.RowPropertiesLoadOptions

Objet qui représente les propriétés de ligne à charger.

Retours

Tableau dans lequel chaque élément représente les propriétés demandées de la ligne correspondante.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

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

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

Remarques

[ Ensemble d’API : ExcelApi 1.2 ]

getSpecialCells(cellType, cellValueType)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages rectangulaires, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, une ItemNotFound erreur est générée.

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

Paramètres

cellType
Excel.SpecialCellType

Type de cellules à inclure.

cellValueType
Excel.SpecialCellValueType

Si cellType est constants ou formulas, cet argument est utilisé pour déterminer les types de cellules à inclure dans le résultat. Ces valeurs peuvent être combinées pour retourner plusieurs types. Par défaut, toutes les constantes ou formules sont sélectionnées, quel qu'en soit le type.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

getSpecialCells(cellTypeString, cellValueTypeString)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages rectangulaires, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, une ItemNotFound erreur est générée.

getSpecialCells(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Paramètres

cellTypeString

"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

Type de cellules à inclure.

cellValueTypeString

"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

Si cellType est constants ou formulas, cet argument est utilisé pour déterminer les types de cellules à inclure dans le résultat. Ces valeurs peuvent être combinées pour retourner plusieurs types. Par défaut, toutes les constantes ou formules sont sélectionnées, quel qu'en soit le type.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

getSpecialCellsOrNullObject(cellType, cellValueType)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

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

Paramètres

cellType
Excel.SpecialCellType

Type de cellules à inclure.

cellValueType
Excel.SpecialCellValueType

Si cellType est constants ou formulas, cet argument est utilisé pour déterminer les types de cellules à inclure dans le résultat. Ces valeurs peuvent être combinées pour retourner plusieurs types. Par défaut, toutes les constantes ou formules sont sélectionnées, quel qu'en soit le type.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

Obtient l’objet RangeAreas , comprenant une ou plusieurs plages, qui représente toutes les cellules qui correspondent au type et à la valeur spécifiés. Si aucune cellule spéciale n’est trouvée, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

Paramètres

cellTypeString

"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

Type de cellules à inclure.

cellValueTypeString

"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

Si cellType est constants ou formulas, cet argument est utilisé pour déterminer les types de cellules à inclure dans le résultat. Ces valeurs peuvent être combinées pour retourner plusieurs types. Par défaut, toutes les constantes ou formules sont sélectionnées, quel qu'en soit le type.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

getSpillingToRange()

Obtient l’objet de la plage contenant la plage renversé lorsque appelée sur une cellule d’ancrage. Échoue si appliqué à une plage comportant plusieurs cellules.

getSpillingToRange(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

Exemples

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

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

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

getSpillingToRangeOrNullObject()

Obtient l’objet de la plage contenant la plage renversé lorsque appelée sur une cellule d’ancrage. Si la plage n’est pas une cellule d’ancre ou si la plage de déversement est introuvable, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpillingToRangeOrNullObject(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

getSpillParent()

Obtient l’objet de la plage contenant la cellule d’ancrage d’une cellule prise renversée dans. Échoue si appliqué à une plage comportant plusieurs cellules.

getSpillParent(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

getSpillParentOrNullObject()

Obtient l’objet de plage contenant la cellule d’ancrage pour la cellule qui est renversée. S’il ne s’agit pas d’une cellule renversée ou si plusieurs cellules sont fournies, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

getSpillParentOrNullObject(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.12 ]

getSurroundingRegion()

Renvoie un Range objet qui représente la région environnante pour la cellule en haut à gauche de cette plage. Une région environnante est une plage délimitée par une combinaison de lignes et de colonnes vides par rapport à cette plage.

getSurroundingRegion(): Excel.Range;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

getTables(fullyContained)

Obtient une collection de tableaux qui se chevauchent avec la plage dans l’étendue.

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

Paramètres

fullyContained

boolean

Si truela valeur est , retourne uniquement les tables qui sont entièrement contenues dans les limites de plage. La valeur par défaut est false.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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

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();
});

getUsedRangeOrNullObject(valuesOnly)

Renvoie la plage utilisée d’un objet de plage donné. Si aucune cellule n’est utilisée dans la plage, cette méthode retourne un objet avec sa isNullObject propriété définie sur true. Pour plus d’informations, consultez *Méthodes et propriétés OrNullObject.

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

Paramètres

valuesOnly

boolean

Prend uniquement en compte les cellules avec des valeurs sous forme de cellules utilisées.

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.4 ]

Exemples

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

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

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

getVisibleView()

Représente les lignes visibles de la plage en cours.

getVisibleView(): Excel.RangeView;

Retours

Remarques

[ Ensemble d’API : ExcelApi 1.3 ]

group(groupOption)

Groupes colonnes et lignes d’un plan.

group(groupOption: Excel.GroupOption): void;

Paramètres

groupOption
Excel.GroupOption

Spécifie comment la plage peut être regroupée par lignes ou colonnes. Une InvalidArgument erreur est générée lorsque l’option de groupe diffère de la propriété ou de isEntireColumnisEntireRow la plage (c’est-à-dire que range.isEntireRow a la valeur true et groupOption est « ByColumns » ou range.isEntireColumn est true et groupOption « ByRows »).

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

Exemples

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

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

group(groupOptionString)

Groupes colonnes et lignes d’un plan.

group(groupOptionString: "ByRows" | "ByColumns"): void;

Paramètres

groupOptionString

"ByRows" | "ByColumns"

Spécifie comment la plage peut être regroupée par lignes ou colonnes. Une InvalidArgument erreur est générée lorsque l’option de groupe diffère de la propriété ou de isEntireColumnisEntireRow la plage (c’est-à-dire que range.isEntireRow a la valeur true et groupOption est « ByColumns » ou range.isEntireColumn est true et groupOption « ByRows »).

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

hideGroupDetails(groupOption)

Masque les détails du groupe de lignes ou de colonnes.

hideGroupDetails(groupOption: Excel.GroupOption): void;

Paramètres

groupOption
Excel.GroupOption

Spécifie s’il faut masquer les détails des lignes groupées ou des colonnes groupées.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

hideGroupDetails(groupOptionString)

Masque les détails du groupe de lignes ou de colonnes.

hideGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

Paramètres

groupOptionString

"ByRows" | "ByColumns"

Spécifie s’il faut masquer les détails des lignes groupées ou des colonnes groupées.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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

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)

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: "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

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

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

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

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();
});

moveTo(destinationRange)

Déplace les valeurs de cellule, la mise en forme et les formules de la plage actuelle vers la plage de destination, en remplaçant les anciennes informations dans ces cellules. La plage de destination est développée automatiquement si elle est plus petite que la plage actuelle. Les cellules de la plage de destination qui se trouvent en dehors de la zone de la plage d’origine ne sont pas modifiées.

moveTo(destinationRange: Range | string): void;

Paramètres

destinationRange

Excel.Range | string

destinationRange Spécifie la plage vers laquelle les informations de cette plage seront déplacées.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.11 ]

Exemples

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

removeDuplicates(columns, includesHeader)

Supprime les valeurs dupliquées de la plage spécifiée par les colonnes.

removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;

Paramètres

columns

number[]

Colonnes à l’intérieur de la plage qui peuvent contenir des doublons. Au moins une colonne doit être spécifiée. Avec indice zéro.

includesHeader

boolean

True si les données d’entrée contiennent un en-tête. La valeur par défaut est False.

Retours

Objet résultant qui contient le nombre de lignes supprimées et le nombre de lignes uniques restantes.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

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

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

replaceAll(text, replacement, criteria)

Détecte et remplace la chaîne donnée basée sur les critères spécifiés dans la plage active.

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

Paramètres

text

string

Chaîne à rechercher.

replacement

string

Chaîne qui remplace la chaîne d’origine.

criteria
Excel.ReplaceCriteria

Critères de remplacement supplémentaires.

Retours

Nombre de remplacements effectués.

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

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();
});

setCellProperties(cellPropertiesData)

Mises à jour la plage en fonction d’un tableau 2D de propriétés de cellule, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

Paramètres

cellPropertiesData

Excel.SettableCellProperties[][]

Tableau 2D qui représente les propriétés à définir dans chaque cellule.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

Exemples

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

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

    // Creating the SettableCellProperties objects to use for the range.
    // In your add-in, these should be created once, outside the function.
    const topHeaderProps: Excel.SettableCellProperties = {
        // The style property takes a string matching the name of an Excel style.
        // Built-in style names are listed in the `BuiltInStyle` enum.
        // Note that a style will overwrite any formatting,
        // so do not use the format property with the style property.
        style: "Heading1"
    };

    const headerProps: Excel.SettableCellProperties = {
        // Any subproperties of format that are not set will not be changed when these cell properties are set.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            }
        }
    };

    const range = sheet.getRange("A1:E5");

    // You can use empty JSON objects to avoid changing a cell's properties.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

setColumnProperties(columnPropertiesData)

Mises à jour la plage en fonction d’un tableau unidimensionnel de propriétés de colonne, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

Paramètres

columnPropertiesData

Excel.SettableColumnProperties[]

Tableau qui représente les propriétés à définir dans chaque colonne.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

setDirty()

Cette méthode désigne une plage qui doit être recalculée lorsque le recalcul suivant se produit.

setDirty(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

setRowProperties(rowPropertiesData)

Mises à jour la plage en fonction d’un tableau unidimensionnel de propriétés de ligne, encapsulant des éléments tels que la police, le remplissage, les bordures et l’alignement.

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

Paramètres

rowPropertiesData

Excel.SettableRowProperties[]

Tableau qui représente les propriétés à définir dans chaque ligne.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.9 ]

showCard()

Affiche la carte pour une cellule active si son contenu est riche en valeur.

showCard(): void;

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.7 ]

showGroupDetails(groupOption)

Affiche les détails du groupe de lignes ou de colonnes.

showGroupDetails(groupOption: Excel.GroupOption): void;

Paramètres

groupOption
Excel.GroupOption

Spécifie s’il faut afficher les détails des lignes groupées ou des colonnes groupées.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

showGroupDetails(groupOptionString)

Affiche les détails du groupe de lignes ou de colonnes.

showGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

Paramètres

groupOptionString

"ByRows" | "ByColumns"

Spécifie s’il faut afficher les détails des lignes groupées ou des colonnes groupées.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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

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

ungroup(groupOption)

Dissocie les colonnes et les lignes d’un plan.

ungroup(groupOption: Excel.GroupOption): void;

Paramètres

groupOption
Excel.GroupOption

Spécifie comment la plage peut être dissociée par lignes ou colonnes.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

Exemples

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

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // This removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

ungroup(groupOptionString)

Dissocie les colonnes et les lignes d’un plan.

ungroup(groupOptionString: "ByRows" | "ByColumns"): void;

Paramètres

groupOptionString

"ByRows" | "ByColumns"

Spécifie comment la plage peut être dissociée par lignes ou colonnes.

Retours

void

Remarques

[ Ensemble d’API : ExcelApi 1.10 ]

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

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();
});