Partager via


Office.TableBinding interface

Représente une liaison à deux dimensions de lignes et de colonnes, avec éventuellement des en-têtes.

Extends

Remarques

L’objet TableBinding hérite de la propriété, type de la id propriété, getDataAsync de la méthode et setDataAsync de la méthode de l’objet Office.Binding.

Pour Excel, notez qu’une fois que vous avez établi une liaison de tableau, chaque nouvelle ligne qu’un utilisateur ajoute au tableau est automatiquement incluse dans la liaison et rowCount augmente.

Propriétés

columnCount

Obtient le nombre de colonnes dans tableBinding, sous la forme d’une valeur entière.

hasHeaders

True, si la table comporte des en-têtes ; sinon, false.

rowCount

Obtient le nombre de lignes dans TableBinding, sous la forme d’une valeur entière.

Méthodes

addColumnsAsync(tableData, options, callback)

Ajoute les données spécifiées à la table en tant que colonnes supplémentaires.

addColumnsAsync(tableData, callback)

Ajoute les données spécifiées à la table en tant que colonnes supplémentaires.

addRowsAsync(rows, options, callback)

Ajoute les données spécifiées à la table en tant que lignes supplémentaires.

addRowsAsync(rows, callback)

Ajoute les données spécifiées à la table en tant que lignes supplémentaires.

clearFormatsAsync(options, callback)

Efface la mise en forme du tableau lié.

clearFormatsAsync(callback)

Efface la mise en forme du tableau lié.

deleteAllDataValuesAsync(options, callback)

Supprime toutes les lignes non-en-tête et leurs valeurs dans la table, en les déplaçant de manière appropriée pour l’application Office.

deleteAllDataValuesAsync(callback)

Supprime toutes les lignes non-en-tête et leurs valeurs dans la table, en les déplaçant de manière appropriée pour l’application Office.

getFormatsAsync(cellReference, formats, options, callback)

Obtient la mise en forme sur les éléments spécifiés dans le tableau.

getFormatsAsync(cellReference, formats, callback)

Obtient la mise en forme sur les éléments spécifiés dans le tableau.

setFormatsAsync(cellFormat, options, callback)

Définit la mise en forme des éléments et des données spécifiés dans le tableau.

setFormatsAsync(cellFormat, callback)

Définit la mise en forme des éléments et des données spécifiés dans le tableau.

setTableOptionsAsync(tableOptions, options, callback)

Met à jour les options de mise en forme de tableau sur le tableau lié.

setTableOptionsAsync(tableOptions, callback)

Met à jour les options de mise en forme de tableau sur le tableau lié.

Détails de la propriété

columnCount

Obtient le nombre de colonnes dans tableBinding, sous la forme d’une valeur entière.

columnCount: number;

Valeur de propriété

number

Exemples

function showBindingColumnCount() {
    Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
        write("Column: " + asyncResult.value.columnCount);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

hasHeaders

True, si la table comporte des en-têtes ; sinon, false.

hasHeaders: boolean;

Valeur de propriété

boolean

Exemples

function showBindingHasHeaders() {
    Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
        write("Binding has headers: " + asyncResult.value.hasHeaders);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

rowCount

Obtient le nombre de lignes dans TableBinding, sous la forme d’une valeur entière.

rowCount: number;

Valeur de propriété

number

Remarques

Lorsque vous insérez un tableau vide en sélectionnant une seule ligne dans Excel sur le bureau et Excel sur le web (à l’aide du tableau sous l’onglet Insertion), les deux applications Office créent une seule ligne d’en-têtes suivie d’une seule ligne vide. Toutefois, si le script de votre complément crée une liaison pour ce tableau nouvellement inséré (par exemple, à l’aide de la méthode Office.Bindings.addFromSelectionAsync), puis vérifie la valeur de la propriété rowCount, la valeur renvoyée diffère selon que la feuille de calcul est ouverte dans Excel sur le bureau ou Excel sur le web.

  • Dans Excel sur le bureau (par exemple, Windows et Mac), rowCount retourne 0 (la ligne vide qui suit les en-têtes n’est pas comptée).

  • Dans Excel sur le web, rowCount retourne 1 (la ligne vide qui suit les en-têtes est comptée).

Vous pouvez contourner cette différence dans votre script en vérifiant si rowCount == 1 et, si tel est le cas, en vérifiant si la ligne contient toutes les chaînes vides.

Exemples

function showBindingRowCount() {
    Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
        write("Rows: " + asyncResult.value.rowCount);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Détails de la méthode

addColumnsAsync(tableData, options, callback)

Ajoute les données spécifiées à la table en tant que colonnes supplémentaires.

addColumnsAsync(tableData: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

tableData

Office.TableData | any[][]

Tableau de tableaux (« matrice ») ou objet TableData qui contient une ou plusieurs colonnes de données à ajouter à la table. Obligatoire.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Pour ajouter une ou plusieurs colonnes spécifiant les valeurs des données et des en-têtes, transmettez un objet TableData comme paramètre de données. Pour ajouter une ou plusieurs colonnes en spécifiant uniquement les données, transmettez un tableau de tableaux (matrice, « matrix ») pour le paramètre data.

La réussite ou l’échec d’une opération addColumnsAsync est atomique. En d’autres termes, l’ensemble de l’opération d’ajout de colonnes doit réussir ; sinon, l’opération est complètement restaurée (en outre, la propriété AsyncResult.status qui est renvoyée au rappel signale un échec) :

  • Chaque ligne du tableau que vous passez en tant qu’argument de données doit avoir le même nombre de lignes que la table mise à jour. Sinon, toute l’opération échoue.

  • Chaque ligne et cellule du tableau doit ajouter correctement cette ligne ou cellule au tableau dans les colonnes nouvellement ajoutées. S’il est impossible de définir une ligne ou une cellule pour une raison quelconque, toute l’opération échoue.

  • Si vous passez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table en cours de mise à jour.

Remarque supplémentaire pour Excel sur le web : Le nombre total de cellules dans l’objet TableData passé au paramètre de données ne peut pas dépasser 20 000 en un seul appel à cette méthode.

Exemples

// The following example adds a single column with three rows to a bound table with the id "myTable"
// by passing a TableData object as the data argument of the addColumnsAsync method. To succeed,
// the table being updated must have three rows.

// Add a column to a binding of type table by passing a TableData object.
function addColumns() {
    const myTable = new Office.TableData();
    myTable.headers = [["Cities"]];
    myTable.rows = [["Berlin"], ["Roma"], ["Tokyo"]];

    Office.context.document.bindings.getByIdAsync("myTable", function (result) {
        result.value.addColumnsAsync(myTable);
    });
}

// The following example adds a single column with three rows to a bound table with the id myTable
// by passing an array of arrays ("matrix") as the data argument of the addColumnsAsync method.
// To succeed, the table being updated must have three rows.

// Add a column to a binding of type table by passing an array of arrays.
function addColumns() {
    const myTable = [["Berlin"], ["Roma"], ["Tokyo"]];

    Office.context.document.bindings.getByIdAsync("myTable", function (result) {
        result.value.addColumnsAsync(myTable);
    });
}

addColumnsAsync(tableData, callback)

Ajoute les données spécifiées à la table en tant que colonnes supplémentaires.

addColumnsAsync(tableData: TableData | any[][], callback?: (result: AsyncResult<void>) => void): void;

Paramètres

tableData

Office.TableData | any[][]

Tableau de tableaux (« matrice ») ou objet TableData qui contient une ou plusieurs colonnes de données à ajouter à la table. Obligatoire.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Pour ajouter une ou plusieurs colonnes spécifiant les valeurs des données et des en-têtes, transmettez un objet TableData comme paramètre de données. Pour ajouter une ou plusieurs colonnes en spécifiant uniquement les données, transmettez un tableau de tableaux (matrice, « matrix ») pour le paramètre data.

La réussite ou l’échec d’une opération addColumnsAsync est atomique. En d’autres termes, l’ensemble de l’opération d’ajout de colonnes doit réussir ; sinon, l’opération est complètement restaurée (en outre, la propriété AsyncResult.status qui est renvoyée au rappel signale un échec) :

  • Chaque ligne du tableau que vous passez en tant qu’argument de données doit avoir le même nombre de lignes que la table mise à jour. Sinon, toute l’opération échoue.

  • Chaque ligne et cellule du tableau doit ajouter correctement cette ligne ou cellule au tableau dans les colonnes nouvellement ajoutées. S’il est impossible de définir une ligne ou une cellule pour une raison quelconque, toute l’opération échoue.

  • Si vous passez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table en cours de mise à jour.

Remarque supplémentaire pour Excel sur le web : Le nombre total de cellules dans l’objet TableData passé au paramètre de données ne peut pas dépasser 20 000 en un seul appel à cette méthode.

addRowsAsync(rows, options, callback)

Ajoute les données spécifiées à la table en tant que lignes supplémentaires.

addRowsAsync(rows: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

rows

Office.TableData | any[][]

Tableau de tableaux (« matrice ») ou objet TableData qui contient une ou plusieurs lignes de données à ajouter à la table. Obligatoire.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

La réussite ou l’échec d’une opération addRowsAsync est atomique. En d’autres termes, l’ensemble de l’opération d’ajout de colonnes doit réussir ; sinon, l’opération est complètement restaurée (en outre, la propriété AsyncResult.status qui est renvoyée au rappel signale un échec) :

  • Chaque ligne du tableau que vous passez en tant qu’argument de données doit avoir le même nombre de colonnes que la table mise à jour. Sinon, toute l’opération échoue.

  • Chaque colonne et cellule du tableau doit ajouter correctement cette colonne ou cellule au tableau dans les lignes nouvellement ajoutées. Si une colonne ou cellule ne parvient pas à être définie pour une raison quelconque, l’opération entière échoue.

  • Si vous passez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table en cours de mise à jour.

Remarque supplémentaire pour Excel sur le web : Le nombre total de cellules dans l’objet TableData passé au paramètre de données ne peut pas dépasser 20 000 en un seul appel à cette méthode.

Exemples

function addRowsToTable() {
    Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
        const binding = asyncResult.value;
        binding.addRowsAsync([["6", "k"], ["7", "j"]]);
    });
}

addRowsAsync(rows, callback)

Ajoute les données spécifiées à la table en tant que lignes supplémentaires.

addRowsAsync(rows: TableData | any[][], callback?: (result: AsyncResult<void>) => void): void;

Paramètres

rows

Office.TableData | any[][]

Tableau de tableaux (« matrice ») ou objet TableData qui contient une ou plusieurs lignes de données à ajouter à la table. Obligatoire.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

La réussite ou l’échec d’une opération addRowsAsync est atomique. En d’autres termes, l’ensemble de l’opération d’ajout de colonnes doit réussir ; sinon, l’opération est complètement restaurée (en outre, la propriété AsyncResult.status qui est renvoyée au rappel signale un échec) :

  • Chaque ligne du tableau que vous passez en tant qu’argument de données doit avoir le même nombre de colonnes que la table mise à jour. Sinon, toute l’opération échoue.

  • Chaque colonne et cellule du tableau doit ajouter correctement cette colonne ou cellule au tableau dans les lignes nouvellement ajoutées. Si une colonne ou cellule ne parvient pas à être définie pour une raison quelconque, l’opération entière échoue.

  • Si vous passez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table en cours de mise à jour.

Remarque supplémentaire pour Excel sur le web : Le nombre total de cellules dans l’objet TableData passé au paramètre de données ne peut pas dépasser 20 000 en un seul appel à cette méthode.

clearFormatsAsync(options, callback)

Efface la mise en forme du tableau lié.

clearFormatsAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Pour plus d’informations, voir Mettre en forme des tableaux dans des compléments pour Excel .

Exemples

// The following example shows how to clear the formatting of the bound table with an ID of "myBinding":
Office.select("bindings#myBinding").clearFormatsAsync();

clearFormatsAsync(callback)

Efface la mise en forme du tableau lié.

clearFormatsAsync(callback?: (result: AsyncResult<void>) => void): void;

Paramètres

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Pour plus d’informations, voir Mettre en forme des tableaux dans des compléments pour Excel .

deleteAllDataValuesAsync(options, callback)

Supprime toutes les lignes non-en-tête et leurs valeurs dans la table, en les déplaçant de manière appropriée pour l’application Office.

deleteAllDataValuesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Dans Excel, si le tableau n’a pas de ligne d’en-tête, cette méthode supprime le tableau proprement dit.

Exemples

function deleteAllRowsFromTable() {
    Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
        const binding = asyncResult.value;
        binding.deleteAllDataValuesAsync();
    });
}

deleteAllDataValuesAsync(callback)

Supprime toutes les lignes non-en-tête et leurs valeurs dans la table, en les déplaçant de manière appropriée pour l’application Office.

deleteAllDataValuesAsync(callback?: (result: AsyncResult<void>) => void): void;

Paramètres

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Dans Excel, si le tableau n’a pas de ligne d’en-tête, cette méthode supprime le tableau proprement dit.

getFormatsAsync(cellReference, formats, options, callback)

Obtient la mise en forme sur les éléments spécifiés dans le tableau.

getFormatsAsync(cellReference?: any, formats?: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult< Array<{ cells: any, format: any}>>) => void): void;

Paramètres

cellReference

any

Littéral d’objet contenant des paires nom-valeur qui spécifient la plage de cellules à partir de laquelle obtenir la mise en forme.

formats

any[]

Tableau spécifiant les propriétés de format à obtenir.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult< Array<{ cells: any, format: any}>>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est un tableau contenant un ou plusieurs objets JavaScript spécifiant la mise en forme de leurs cellules correspondantes.

Retours

void

Remarques

Structure de format retournée

Chaque objet JavaScript dans le tableau de valeurs de retour se présente sous la forme suivante : {cells:{ cell_range }, format:{ format_definition }}

La cells: propriété spécifie la plage que vous souhaitez mettre en forme à l’aide de l’une des valeurs suivantes.

Plages prises en charge dans la propriété cells

cells paramètres de plage Description
{row: n} Spécifie la plage qui correspond à la nième ligne de données de base zéro dans la table.
{column: n} Spécifie la plage qui correspond à la nième colonne de données de base zéro dans la table.
{row: i, column: j} Spécifie la cellule unique qui correspond à la ligne ith et à la colonne jth de la table.
Office.Table.All Spécifie le tableau entier, y compris les totaux, les données et les en-têtes de colonne (le cas échéant).
Office.Table.Data Spécifie uniquement les données du tableau (sans les en-têtes ni les totaux).
Office.Table.Headers Spécifie uniquement la ligne d’en-tête.

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format des cellules dans Excel (ouvrez le menu contextuel (cliquez avec le bouton droit ou sélectionnez de façon longue), puis sélectionnez Format des cellules ou Format accueil>>des cellules).

getFormatsAsync(cellReference, formats, callback)

Obtient la mise en forme sur les éléments spécifiés dans le tableau.

getFormatsAsync(cellReference?: any, formats?: any[], callback?: (result: AsyncResult< Array<{ cells: any, format: any}>>) => void): void;

Paramètres

cellReference

any

Littéral d’objet contenant des paires nom-valeur qui spécifient la plage de cellules à partir de laquelle obtenir la mise en forme.

formats

any[]

Tableau spécifiant les propriétés de format à obtenir.

callback

(result: Office.AsyncResult< Array<{ cells: any, format: any}>>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est un tableau contenant un ou plusieurs objets JavaScript spécifiant la mise en forme de leurs cellules correspondantes.

Retours

void

Remarques

Structure de format retournée

Chaque objet JavaScript dans le tableau de valeurs de retour se présente sous la forme suivante : {cells:{ cell_range }, format:{ format_definition }}

La cells: propriété spécifie la plage que vous souhaitez mettre en forme à l’aide de l’une des valeurs suivantes.

Plages prises en charge dans la propriété cells

cells paramètres de plage Description
{row: n} Spécifie la plage qui correspond à la nième ligne de données de base zéro dans la table.
{column: n} Spécifie la plage qui correspond à la nième colonne de données de base zéro dans la table.
{row: i, column: j} Spécifie la cellule unique qui correspond à la ligne ith et à la colonne jth de la table.
Office.Table.All Spécifie le tableau entier, y compris les totaux, les données et les en-têtes de colonne (le cas échéant).
Office.Table.Data Spécifie uniquement les données du tableau (sans les en-têtes ni les totaux).
Office.Table.Headers Spécifie uniquement la ligne d’en-tête.

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format des cellules dans Excel (ouvrez le menu contextuel (cliquez avec le bouton droit ou sélectionnez de façon longue), puis sélectionnez Format des cellules ou Format accueil>>des cellules).

setFormatsAsync(cellFormat, options, callback)

Définit la mise en forme des éléments et des données spécifiés dans le tableau.

setFormatsAsync(cellFormat: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

cellFormat

any[]

Tableau contenant des objets JavaScript indiquant les cellules à cibler et la mise en forme à leur appliquer.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Spécification du paramètre cellFormat

Utilisez le paramètre cellFormat pour définir ou modifier les valeurs de mise en forme des cellules, telles que la largeur, la hauteur, la police, l’arrière-plan, l’alignement, etc. La valeur que vous passez en tant que paramètre cellFormat est un tableau qui contient une liste d’un ou plusieurs objets JavaScript qui spécifient les cellules à cibler (cells:) et les formats (format:) à appliquer à ces cellules.

Chaque objet JavaScript du tableau cellFormat se présente sous la forme suivante : {cells:{ cell_range }, format:{ format_definition }}

La cells: propriété spécifie la plage que vous souhaitez mettre en forme à l’aide de l’une des valeurs suivantes.

Plages prises en charge dans la propriété cells

cells paramètres de plage Description
{row: n} Spécifie la plage qui correspond à la nième ligne de données de base zéro dans la table.
{column: n} Spécifie la plage qui correspond à la nième colonne de données de base zéro dans la table.
{row: i, column: j} Spécifie la cellule unique qui correspond à la ligne ith et à la colonne jth de la table.
Office.Table.All Spécifie le tableau entier, y compris les totaux, les données et les en-têtes de colonne (le cas échéant).
Office.Table.Data Spécifie uniquement les données du tableau (sans les en-têtes ni les totaux).
Office.Table.Headers Spécifie uniquement la ligne d’en-tête.

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format des cellules dans Excel (ouvrez le menu contextuel (cliquez avec le bouton droit ou sélectionnez de façon longue), puis sélectionnez Format des cellules ou Format accueil>>des cellules).

Vous spécifiez la valeur de la propriété sous la format: forme d’une liste d’une ou plusieurs paires nom-valeur de propriété dans un littéral d’objet JavaScript. Le nom de propriété indique le nom de la propriété de mise en forme à définir, tandis que la valeur spécifie la valeur de la propriété. Vous pouvez spécifier plusieurs valeurs pour un format donné, comme la couleur et la taille de la police.

Voici trois exemples de valeurs de la propriété format: :

//Set cells: font color to green and size to 15 points.

format: {fontColor : "green", fontSize : 15}

//Set cells: border to dotted blue.

format: {borderStyle: "dotted", borderColor: "blue"}

//Set cells: background to red and alignment to centered.

format: {backgroundColor: "red", alignHorizontal: "center"}

Vous pouvez spécifier des formats de nombre en spécifiant la chaîne « code » de mise en forme de nombre dans la numberFormat: propriété . Les chaînes de format numérique que vous pouvez spécifier correspondent à celles que vous pouvez définir dans Excel à l’aide de la catégorie Personnalisée sous l’onglet Nombre de la boîte de dialogue Format de cellule. L’exemple suivant montre comment mettre en forme un nombre en tant que pourcentage à deux décimales :

format: {numberFormat:"0.00%"}

Pour plus d’informations, consultez Créer un format de nombre personnalisé.

Pour définir la mise en forme des tables lors de l’écriture de données, utilisez les paramètres facultatifs tableOptions et cellFormat des Document.setSelectedDataAsync méthodes ou TableBinding.setDataAsync .

La définition de la mise en forme avec les paramètres facultatifs des Document.setSelectedDataAsync méthodes et TableBinding.setDataAsync ne fonctionne que pour définir la mise en forme lors de la première écriture de données. Pour apporter des modifications de mise en forme après l’écriture de données, utilisez les méthodes suivantes.

  • Pour mettre à jour la mise en forme des cellules, comme la couleur et le style de police, utilisez la TableBinding.setFormatsAsync méthode (cette méthode).

  • Pour mettre à jour les options de table, telles que les lignes à bandes et les boutons de filtre, utilisez la TableBinding.setTableOptions méthode .

  • Pour effacer la mise en forme, utilisez la TableBinding.clearFormats méthode .

Pour plus d’informations et d’exemples, voir Guide pratique pour mettre en forme des tableaux dans des compléments pour Excel.

Exemples

// Specifying a single target
// The following example shows a cellFormat value that sets the font color of the header row to red.
Office.select("bindings#myBinding").setFormatsAsync(
    [{cells: Office.Table.Headers, format: {fontColor: "red"}}], 
    function (asyncResult){});

// Specifying multiple targets
// The setFormatsAsync method can support formatting multiple targets within the bound table in a 
// single function call. To do that, you pass a list of objects in the cellFormat array 
// for each target that you want to format.
// For example, the following line of code will set the font color of the first row yellow, 
// and the fourth cell in the third row to have a white border and bold text.
Office.select("bindings#myBinding").setFormatsAsync(
    [{cells: {row: 1}, format: {fontColor: "yellow"}}, 
        {cells: {row: 3, column: 4}, format: {borderColor: "white", fontStyle: "bold"}}], 
    function (asyncResult){});

// Additional remarks for Excel Online
// The number of formatting groups passed to the cellFormat parameter can't exceed 100. 
// A single formatting group consists of a set of formatting applied to a specified range of cells. 
// For example, the following call passes two formatting groups to cellFormat.
Office.select("bindings#myBinding").setFormatsAsync(
    [{cells: {row: 1}, format: {fontColor: "yellow"}}, 
        {cells: {row: 3, column: 4}, format: {borderColor: "white", fontStyle: "bold"}}], 
    function (asyncResult){});

setFormatsAsync(cellFormat, callback)

Définit la mise en forme des éléments et des données spécifiés dans le tableau.

setFormatsAsync(cellFormat: any[], callback?: (result: AsyncResult<void>) => void): void;

Paramètres

cellFormat

any[]

Tableau contenant des objets JavaScript indiquant les cellules à cibler et la mise en forme à leur appliquer.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Spécification du paramètre cellFormat

Utilisez le paramètre cellFormat pour définir ou modifier les valeurs de mise en forme des cellules, telles que la largeur, la hauteur, la police, l’arrière-plan, l’alignement, etc. La valeur que vous passez en tant que paramètre cellFormat est un tableau qui contient une liste d’un ou plusieurs objets JavaScript qui spécifient les cellules à cibler (cells:) et les formats (format:) à appliquer à ces cellules.

Chaque objet JavaScript du tableau cellFormat se présente sous la forme suivante : {cells:{ cell_range }, format:{ format_definition }}

La cells: propriété spécifie la plage que vous souhaitez mettre en forme à l’aide de l’une des valeurs suivantes.

Plages prises en charge dans la propriété cells

cells paramètres de plage Description
{row: n} Spécifie la plage qui correspond à la nième ligne de données de base zéro dans la table.
{column: n} Spécifie la plage qui correspond à la nième colonne de données de base zéro dans la table.
{row: i, column: j} Spécifie la cellule unique qui correspond à la ligne ith et à la colonne jth de la table.
Office.Table.All Spécifie le tableau entier, y compris les totaux, les données et les en-têtes de colonne (le cas échéant).
Office.Table.Data Spécifie uniquement les données du tableau (sans les en-têtes ni les totaux).
Office.Table.Headers Spécifie uniquement la ligne d’en-tête.

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format des cellules dans Excel (ouvrez le menu contextuel (cliquez avec le bouton droit ou sélectionnez de façon longue), puis sélectionnez Format des cellules ou Format accueil>>des cellules).

Vous spécifiez la valeur de la propriété sous la format: forme d’une liste d’une ou plusieurs paires nom-valeur de propriété dans un littéral d’objet JavaScript. Le nom de propriété indique le nom de la propriété de mise en forme à définir, tandis que la valeur spécifie la valeur de la propriété. Vous pouvez spécifier plusieurs valeurs pour un format donné, comme la couleur et la taille de la police.

Voici trois exemples de valeurs de la propriété format: :

//Set cells: font color to green and size to 15 points.

format: {fontColor : "green", fontSize : 15}

//Set cells: border to dotted blue.

format: {borderStyle: "dotted", borderColor: "blue"}

//Set cells: background to red and alignment to centered.

format: {backgroundColor: "red", alignHorizontal: "center"}

Vous pouvez spécifier des formats de nombre en spécifiant la chaîne « code » de mise en forme de nombre dans la numberFormat: propriété . Les chaînes de format numérique que vous pouvez spécifier correspondent à celles que vous pouvez définir dans Excel à l’aide de la catégorie Personnalisée sous l’onglet Nombre de la boîte de dialogue Format de cellule. L’exemple suivant montre comment mettre en forme un nombre en tant que pourcentage à deux décimales :

format: {numberFormat:"0.00%"}

Pour plus d’informations, consultez Créer un format de nombre personnalisé.

Pour définir la mise en forme des tables lors de l’écriture de données, utilisez les paramètres facultatifs tableOptions et cellFormat des Document.setSelectedDataAsync méthodes ou TableBinding.setDataAsync .

La définition de la mise en forme avec les paramètres facultatifs des Document.setSelectedDataAsync méthodes et TableBinding.setDataAsync ne fonctionne que pour définir la mise en forme lors de la première écriture de données. Pour apporter des modifications de mise en forme après l’écriture de données, utilisez les méthodes suivantes.

  • Pour mettre à jour la mise en forme des cellules, comme la couleur et le style de police, utilisez la TableBinding.setFormatsAsync méthode (cette méthode).

  • Pour mettre à jour les options de table, telles que les lignes à bandes et les boutons de filtre, utilisez la TableBinding.setTableOptions méthode .

  • Pour effacer la mise en forme, utilisez la TableBinding.clearFormats méthode .

Pour plus d’informations et d’exemples, voir Guide pratique pour mettre en forme des tableaux dans des compléments pour Excel.

setTableOptionsAsync(tableOptions, options, callback)

Met à jour les options de mise en forme de tableau sur le tableau lié.

setTableOptionsAsync(tableOptions: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

tableOptions

any

Littéral d’objet contenant une liste de paires nom-valeur de propriété qui définissent les options de tableau à appliquer.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

Dans la fonction de rappel transmise à la méthode goToByIdAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Propriété Utilisation
AsyncResult.value Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de la définition des formats.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

Exemples

// The following example shows how to:
// 1. Create an object literal that specifies the table formatting options to update on the bound table.
// 2. Call setTableOptions on a previously bound table (with an id of myBinding) passing the object
//    with formatting setting as the tableOptions parameter.
function updateTableFormatting(){
    const tableOptions = {bandedRows: true, filterButton: false, style: "TableStyleMedium3"}; 

    Office.select("bindings#myBinding").setTableOptionsAsync(tableOptions, function(asyncResult){});
}

setTableOptionsAsync(tableOptions, callback)

Met à jour les options de mise en forme de tableau sur le tableau lié.

setTableOptionsAsync(tableOptions: any, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

tableOptions

any

Littéral d’objet contenant une liste de paires nom-valeur de propriété qui définissent les options de tableau à appliquer.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

Remarques

Ensemble de conditions requises : pas dans un ensemble

Dans la fonction de rappel transmise à la méthode goToByIdAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Propriété Utilisation
AsyncResult.value Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de la définition des formats.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.