Office.TableBinding interface

Obtém o número de colunas no TableBinding como um valor inteiro.

columnCount: number;

Valor da propriedade

Exemplos

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

Verdadeiro, se a tabela tiver cabeçalhos; caso contrário, falso.

hasHeaders: boolean;

Valor da propriedade

Exemplos

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

Obtém o número de linhas no TableBinding como um valor inteiro.

rowCount: number;

Valor da propriedade

Comentários

Quando insere uma tabela vazia ao selecionar uma única linha no Excel no ambiente de trabalho e no Excel na Web (utilizando a Tabela no separador Inserir), ambas as aplicações do Office criam uma única linha de cabeçalhos seguida de uma única linha em branco. No entanto, se o script do seu suplemento criar um enlace para esta tabela recentemente inserida (por exemplo, utilizando o método Office.Bindings.addFromSelectionAsync) e, em seguida, verificar o valor da propriedade rowCount, o valor devolvido será diferente consoante a folha de cálculo esteja aberta no Excel no ambiente de trabalho ou no Excel na Web.

• No Excel no ambiente de trabalho (ou seja, Windows e Mac), rowCount devolverá 0 (a linha em branco a seguir aos cabeçalhos não é contada).

• No Excel na Web, rowCount devolverá 1 (a linha em branco a seguir aos cabeçalhos é contada).

Pode contornar esta diferença no script ao verificar se rowCount == 1 e, em caso afirmativo, verifique se a linha contém todas as cadeias vazias.

Exemplos

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

Adiciona os dados especificados à tabela como colunas adicionais.

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

Parâmetros

Retornos

Comentários

Para adicionar uma ou mais colunas que especifiquem os valores dos dados e cabeçalhos, transmita um objeto TableData como o parâmetro de dados. Para adicionar uma ou mais colunas especificando somente os dados, passe uma matriz de matrizes ("matrix") como parâmetro data.

O êxito ou falha de uma operação addColumnsAsync é atómica. Ou seja, toda a operação de adição de colunas deve ter êxito ou ela será completamente revertida (e a propriedade AsyncResult.status retornada para o retorno de chamada relatará a falha):

• Cada linha na matriz que transmite como argumento de dados tem de ter o mesmo número de linhas que a tabela que está a ser atualizada. Caso contrário, toda a operação falhará.

• Cada linha e célula na matriz tem de adicionar com êxito essa linha ou célula à tabela nas colunas adicionadas recentemente. Se qualquer linha ou célula falhar em ser definida por qualquer motivo, toda a operação falhará.

• Se transmitir um objeto TableData como argumento de dados, o número de linhas de cabeçalho tem de corresponder ao da tabela que está a ser atualizada.

Observação adicional para o Excel na Web: o número total de células no objeto TableData transmitido para o parâmetro de dados não pode exceder 20 000 numa única chamada para este método.

Exemplos

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

Adiciona os dados especificados à tabela como colunas adicionais.

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

Parâmetros

Retornos

Comentários

Para adicionar uma ou mais colunas que especifiquem os valores dos dados e cabeçalhos, transmita um objeto TableData como o parâmetro de dados. Para adicionar uma ou mais colunas especificando somente os dados, passe uma matriz de matrizes ("matrix") como parâmetro data.

O êxito ou falha de uma operação addColumnsAsync é atómica. Ou seja, toda a operação de adição de colunas deve ter êxito ou ela será completamente revertida (e a propriedade AsyncResult.status retornada para o retorno de chamada relatará a falha):

• Cada linha na matriz que transmite como argumento de dados tem de ter o mesmo número de linhas que a tabela que está a ser atualizada. Caso contrário, toda a operação falhará.

• Cada linha e célula na matriz tem de adicionar com êxito essa linha ou célula à tabela nas colunas adicionadas recentemente. Se qualquer linha ou célula falhar em ser definida por qualquer motivo, toda a operação falhará.

• Se transmitir um objeto TableData como argumento de dados, o número de linhas de cabeçalho tem de corresponder ao da tabela que está a ser atualizada.

Observação adicional para o Excel na Web: o número total de células no objeto TableData transmitido para o parâmetro de dados não pode exceder 20 000 numa única chamada para este método.

Adiciona os dados especificados à tabela como linhas adicionais.

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

Parâmetros

Retornos

Comentários

O êxito ou falha de uma operação addRowsAsync é atómica. Ou seja, toda a operação de adição de colunas deve ter êxito ou ela será completamente revertida (e a propriedade AsyncResult.status retornada para o retorno de chamada relatará a falha):

• Cada linha na matriz que transmite como argumento de dados tem de ter o mesmo número de colunas que a tabela que está a ser atualizada. Caso contrário, toda a operação falhará.

• Cada coluna e célula na matriz tem de adicionar com êxito essa coluna ou célula à tabela nas linhas adicionadas recentemente. Se alguma coluna ou célula não for definida por qualquer motivo, toda a operação falhará.

• Se transmitir um objeto TableData como argumento de dados, o número de linhas de cabeçalho tem de corresponder ao da tabela que está a ser atualizada.

Observação adicional para o Excel na Web: o número total de células no objeto TableData transmitido para o parâmetro de dados não pode exceder 20 000 numa única chamada para este método.

Exemplos

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

Adiciona os dados especificados à tabela como linhas adicionais.

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

Parâmetros

Retornos

Comentários

O êxito ou falha de uma operação addRowsAsync é atómica. Ou seja, toda a operação de adição de colunas deve ter êxito ou ela será completamente revertida (e a propriedade AsyncResult.status retornada para o retorno de chamada relatará a falha):

• Cada linha na matriz que transmite como argumento de dados tem de ter o mesmo número de colunas que a tabela que está a ser atualizada. Caso contrário, toda a operação falhará.

• Cada coluna e célula na matriz tem de adicionar com êxito essa coluna ou célula à tabela nas linhas adicionadas recentemente. Se alguma coluna ou célula não for definida por qualquer motivo, toda a operação falhará.

• Se transmitir um objeto TableData como argumento de dados, o número de linhas de cabeçalho tem de corresponder ao da tabela que está a ser atualizada.

Observação adicional para o Excel na Web: o número total de células no objeto TableData transmitido para o parâmetro de dados não pode exceder 20 000 numa única chamada para este método.

Limpa a formatação na tabela associada.

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

Parâmetros

Retornos

Comentários

Consulte Formatar tabelas em suplementos para o Excel para obter mais informações.

Exemplos

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

Limpa a formatação na tabela associada.

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

Parâmetros

Retornos

Comentários

Consulte Formatar tabelas em suplementos para o Excel para obter mais informações.

Elimina todas as linhas sem cabeçalho e os respetivos valores na tabela, mudando adequadamente para a aplicação do Office.

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

Parâmetros

Retornos

Comentários

No Excel, se a tabela não tiver nenhuma linha de cabeçalho, esse método excluirá a tabela em si.

Exemplos

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

Elimina todas as linhas sem cabeçalho e os respetivos valores na tabela, mudando adequadamente para a aplicação do Office.

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

Parâmetros

Retornos

Comentários

No Excel, se a tabela não tiver nenhuma linha de cabeçalho, esse método excluirá a tabela em si.

Obtém a formatação em itens especificados na tabela.

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

Parâmetros

Retornos

Comentários

Estrutura de formato devolvido

Cada objeto JavaScript na matriz de valores devolvidos tem este formulário: {cells:{ cell_range }, format:{ format_definition }}

A cells: propriedade especifica o intervalo que pretende formatar com um dos seguintes valores.

Intervalos com suporte na propriedade das células

A format: propriedade especifica valores que correspondem a um subconjunto das definições disponíveis na caixa de diálogo Formatar Células no Excel (Abrir o menu de contexto (clique com o botão direito do rato ou selecione sem soltar) e, em seguida, selecione Formatar Célulasou>Formatar Células deFormato> base).

Obtém a formatação em itens especificados na tabela.

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

Parâmetros

Retornos

Comentários

Estrutura de formato devolvido

Cada objeto JavaScript na matriz de valores devolvidos tem este formulário: {cells:{ cell_range }, format:{ format_definition }}

A cells: propriedade especifica o intervalo que pretende formatar com um dos seguintes valores.

Intervalos com suporte na propriedade das células

A format: propriedade especifica valores que correspondem a um subconjunto das definições disponíveis na caixa de diálogo Formatar Células no Excel (Abrir o menu de contexto (clique com o botão direito do rato ou selecione sem soltar) e, em seguida, selecione Formatar Célulasou>Formatar Células deFormato> base).

Define a formatação em itens e dados especificados na tabela.

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

Parâmetros

Retornos

Comentários

Especificando o parâmetro cellFormat

Utilize o parâmetro cellFormat para definir ou alterar valores de formatação de células, como largura, altura, tipo de letra, fundo, alinhamento, etc. O valor que transmite como o parâmetro cellFormat é uma matriz que contém uma lista de um ou mais objetos JavaScript que especificam as células a atingir (cells:) e os formatos (format:) a aplicar aos mesmos.

Cada objeto JavaScript na matriz cellFormat tem este formulário: {cells:{ cell_range }, format:{ format_definition }}

A cells: propriedade especifica o intervalo que pretende formatar com um dos seguintes valores.

Intervalos com suporte na propriedade das células

A format: propriedade especifica valores que correspondem a um subconjunto das definições disponíveis na caixa de diálogo Formatar Células no Excel (Abrir o menu de contexto (clique com o botão direito do rato ou selecione sem soltar) e, em seguida, selecione Formatar Célulasou>Formatar Células deFormato> base).

Especifique o valor da format: propriedade como uma lista de um ou mais pares de propriedades - pares de valor num literal de objeto JavaScript. O nome da propriedade especifica o nome da propriedade de formatação para definir, e valor especifica o valor da propriedade. Você pode especificar vários valores para um determinado formato, como cor e tamanho da fonte.

Aqui estão três exemplos de valor da propriedade 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"}

Pode especificar formatos numéricos ao especificar a cadeia de "código" de formatação de números na numberFormat: propriedade . As cadeias de caracteres de formato de número que podem ser especificadas correspondem àquelas que você pode definir no Excel usando a categoria Personalizado na guia Número da caixa de diálogo Formatar Células. Este exemplo mostra como formatar um número como um percentual com duas casas decimais:

format: {numberFormat:"0.00%"}

Para obter mais detalhes, veja Como Criar um formato de número personalizado.

Para definir a formatação em tabelas ao escrever dados, utilize os parâmetros opcionais tableOptions e cellFormat dos Document.setSelectedDataAsync métodos ou TableBinding.setDataAsync .

Definir a formatação com os parâmetros opcionais dos Document.setSelectedDataAsync métodos e TableBinding.setDataAsync só funciona para definir a formatação ao escrever dados pela primeira vez. Para efetuar alterações de formatação depois de escrever dados, utilize os seguintes métodos.

• Para atualizar a formatação das células, como a cor e o estilo do tipo de letra, utilize o TableBinding.setFormatsAsync método (este método).

• Para atualizar as opções da tabela, como linhas listadas e botões de filtro, utilize o TableBinding.setTableOptions método .

• Para limpar a formatação, utilize o TableBinding.clearFormats método .

Para obter mais detalhes e exemplos, consulte How to format tables in add-ins for Excel (Como formatar tabelas em suplementos para Excel).

Exemplos

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

Define a formatação em itens e dados especificados na tabela.

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

Parâmetros

Retornos

Comentários

Especificando o parâmetro cellFormat

Utilize o parâmetro cellFormat para definir ou alterar valores de formatação de células, como largura, altura, tipo de letra, fundo, alinhamento, etc. O valor que transmite como o parâmetro cellFormat é uma matriz que contém uma lista de um ou mais objetos JavaScript que especificam as células a atingir (cells:) e os formatos (format:) a aplicar aos mesmos.

Cada objeto JavaScript na matriz cellFormat tem este formulário: {cells:{ cell_range }, format:{ format_definition }}

A cells: propriedade especifica o intervalo que pretende formatar com um dos seguintes valores.

Intervalos com suporte na propriedade das células

A format: propriedade especifica valores que correspondem a um subconjunto das definições disponíveis na caixa de diálogo Formatar Células no Excel (Abrir o menu de contexto (clique com o botão direito do rato ou selecione sem soltar) e, em seguida, selecione Formatar Célulasou>Formatar Células deFormato> base).

Especifique o valor da format: propriedade como uma lista de um ou mais pares de propriedades - pares de valor num literal de objeto JavaScript. O nome da propriedade especifica o nome da propriedade de formatação para definir, e valor especifica o valor da propriedade. Você pode especificar vários valores para um determinado formato, como cor e tamanho da fonte.

Aqui estão três exemplos de valor da propriedade 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"}

Pode especificar formatos numéricos ao especificar a cadeia de "código" de formatação de números na numberFormat: propriedade . As cadeias de caracteres de formato de número que podem ser especificadas correspondem àquelas que você pode definir no Excel usando a categoria Personalizado na guia Número da caixa de diálogo Formatar Células. Este exemplo mostra como formatar um número como um percentual com duas casas decimais:

format: {numberFormat:"0.00%"}

Para obter mais detalhes, veja Como Criar um formato de número personalizado.

Para definir a formatação em tabelas ao escrever dados, utilize os parâmetros opcionais tableOptions e cellFormat dos Document.setSelectedDataAsync métodos ou TableBinding.setDataAsync .

Definir a formatação com os parâmetros opcionais dos Document.setSelectedDataAsync métodos e TableBinding.setDataAsync só funciona para definir a formatação ao escrever dados pela primeira vez. Para efetuar alterações de formatação depois de escrever dados, utilize os seguintes métodos.

• Para atualizar a formatação das células, como a cor e o estilo do tipo de letra, utilize o TableBinding.setFormatsAsync método (este método).

• Para atualizar as opções da tabela, como linhas listadas e botões de filtro, utilize o TableBinding.setTableOptions método .

• Para limpar a formatação, utilize o TableBinding.clearFormats método .

Para obter mais detalhes e exemplos, consulte How to format tables in add-ins for Excel (Como formatar tabelas em suplementos para Excel).

Atualiza as opções de formatação de tabela na tabela associada.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: não está num conjunto

Na função de chamada de retorno transmitida para o método goToByIdAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

Exemplos

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

Atualiza as opções de formatação de tabela na tabela associada.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: não está num conjunto

Na função de chamada de retorno transmitida para o método goToByIdAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.