Office.TableBinding interface

Obtient le nombre de colonnes dans TableBinding, sous forme de valeur entière.

columnCount: number;

Valeur de propriété

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

Vrai, si le tableau a des en-têtes ; sinon faux.

hasHeaders: boolean;

Valeur de propriété

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

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

rowCount: number;

Valeur de propriété

Remarques

Lorsque vous insérez un tableau vide en sélectionnant une seule ligne dans Excel sur la version de bureau et dans Excel sur le Web (à l’aide du tableau de 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 cette table nouvellement insérée (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 dans Excel sur le Web.

• Dans Excel sur le bureau (c’est-à-dire Windows et Mac), rowCount retourne 0 (la ligne vide qui suit les en-têtes n’est pas comptabilisé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;
}

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

Retours

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 data 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 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 transmettez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table mise à jour.

Remarque supplémentaire pour Excel sur le Web : Le nombre total de cellules de l’objet TableData transmises au paramètre data ne peut pas dépasser 20 000 lors d’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);
    });
}

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

Retours

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 data 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 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 transmettez un objet TableData comme argument de données, le nombre de lignes d’en-tête doit correspondre à celui de la table mise à jour.

Remarque supplémentaire pour Excel sur le Web : Le nombre total de cellules de l’objet TableData transmises au paramètre data ne peut pas dépasser 20 000 lors d’un seul appel à cette méthode.

Ajoute les données spécifiées à la table sous forme de lignes supplémentaires.

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

Paramètres

Retours

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 transmettez en tant qu’argument de données doit avoir le même nombre de colonnes que le tableau mis à jour. Sinon, toute l’opération échoue.

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

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

Remarque supplémentaire pour Excel sur le Web : Le nombre total de cellules de l’objet TableData transmises au paramètre data ne peut pas dépasser 20 000 lors d’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"]]);
    });
}

Ajoute les données spécifiées à la table sous forme de lignes supplémentaires.

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

Paramètres

Retours

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 transmettez en tant qu’argument de données doit avoir le même nombre de colonnes que le tableau mis à jour. Sinon, toute l’opération échoue.

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

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

Remarque supplémentaire pour Excel sur le Web : Le nombre total de cellules de l’objet TableData transmises au paramètre data ne peut pas dépasser 20 000 lors d’un seul appel à cette méthode.

Efface la mise en forme du tableau lié.

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

Paramètres

Retours

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

Efface la mise en forme du tableau lié.

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

Paramètres

Retours

Remarques

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

Supprime toutes les lignes non en-tête et leurs valeurs dans le tableau, en effectuant un décalage approprié pour l’application Office.

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

Paramètres

Retours

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

Supprime toutes les lignes non en-tête et leurs valeurs dans le tableau, en effectuant un décalage approprié pour l’application Office.

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

Paramètres

Retours

Remarques

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

Obtient la mise en forme des é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

Retours

Remarques

Structure de format renvoyée

Chaque objet JavaScript du tableau de valeur de retour a 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

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format de cellule d’Excel (ouvrir le menu contextuel (cliquer avec le bouton droit ou sélectionner et maintenir enfoncé), puis sélectionnez Format de cellule ouFormat>de cellule d’accueil>).

Obtient la mise en forme des é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

Retours

Remarques

Structure de format renvoyée

Chaque objet JavaScript du tableau de valeur de retour a 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

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format de cellule d’Excel (ouvrir le menu contextuel (cliquer avec le bouton droit ou sélectionner et maintenir enfoncé), puis sélectionnez Format de cellule ouFormat>de cellule d’accueil>).

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

Retours

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 transmettez en tant que paramètre cellFormat est un tableau contenant une liste d’un ou plusieurs objets JavaScript spécifiant les cellules à cibler (cells:) et les formats (format:) à leur appliquer.

Chaque objet JavaScript du tableau cellFormat a 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

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format de cellule d’Excel (ouvrir le menu contextuel (cliquer avec le bouton droit ou sélectionner et maintenir enfoncé), puis sélectionnez Format de cellule ouFormat>de cellule d’accueil>).

Vous spécifiez la valeur de la propriété sous la format: forme d’une liste d’une ou plusieurs paires nom-valeur 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 de mise en forme de nombre « code » 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, voir Comment créer un format de nombre personnalisé.

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

La définition de la mise en forme avec les paramètres facultatifs Document.setSelectedDataAsync des méthodes et TableBinding.setDataAsync fonctionne uniquement pour définir la mise en forme lors de la première écriture de données. Pour modifier la mise en forme après avoir écrit des données, appliquez les méthodes suivantes.

• Pour mettre à jour la mise en forme d’une cellule, tel que 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, consultez Comment 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){});

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

Retours

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 transmettez en tant que paramètre cellFormat est un tableau contenant une liste d’un ou plusieurs objets JavaScript spécifiant les cellules à cibler (cells:) et les formats (format:) à leur appliquer.

Chaque objet JavaScript du tableau cellFormat a 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

La format: propriété spécifie des valeurs qui correspondent à un sous-ensemble des paramètres disponibles dans la boîte de dialogue Format de cellule d’Excel (ouvrir le menu contextuel (cliquer avec le bouton droit ou sélectionner et maintenir enfoncé), puis sélectionnez Format de cellule ouFormat>de cellule d’accueil>).

Vous spécifiez la valeur de la propriété sous la format: forme d’une liste d’une ou plusieurs paires nom-valeur 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 de mise en forme de nombre « code » 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, voir Comment créer un format de nombre personnalisé.

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

La définition de la mise en forme avec les paramètres facultatifs Document.setSelectedDataAsync des méthodes et TableBinding.setDataAsync fonctionne uniquement pour définir la mise en forme lors de la première écriture de données. Pour modifier la mise en forme après avoir écrit des données, appliquez les méthodes suivantes.

• Pour mettre à jour la mise en forme d’une cellule, tel que 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, consultez Comment mettre en forme des tableaux dans des compléments pour Excel.

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

Retours

Remarques

Jeu de conditions requises : Pas dans un jeu

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.

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

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

Retours

Remarques

Jeu de conditions requises : Pas dans un jeu

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.