Office.Bindings interface

Obtém um objeto Office.Document que representa o documento associado a esse conjunto de associações.

document: Document;

Valor da propriedade

Office.Document

Cria uma associação com um objeto nomeado no documento.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

itemName: string

Nome do objeto associável no documento. Por exemplo, a tabela 'MyExpenses' no Excel."

bindingType: Office.BindingType

O Office.BindingType para os dados. O método retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

options: Office.AddBindingFromNamedItemOptions

Fornece opções para configurar a associação criada.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa o item nomeado especificado.

Retornos

void

Comentários

Conjuntos de requisitos:

Para o Excel, o parâmetro itemName pode se referir a um intervalo nomeado ou a uma tabela.

Por padrão, a adição de uma tabela no Excel atribui o nome "Tabela1" à primeira tabela que você adicionar, "Tabela2" para a segunda tabela adicionada e assim por diante. Para atribuir um nome significativo para uma tabela na interface do usuário do Excel, use a propriedade Nome da Tabela nas Ferramentas de Tabela | Guia design da faixa de opções.

Observação: no Excel, ao especificar uma tabela como um item nomeado, você deve qualificar totalmente o nome para incluir o nome da planilha no nome da tabela neste formato: "Folha1! Table1"

Para o Word, o parâmetro itemName refere-se à propriedade Title de um controle de conteúdo rich text. (Você não pode associar-se a controles de conteúdo que não sejam o controle de conteúdo rich text).

Por padrão, um controle de conteúdo não tem nenhum valor de título atribuído. Para atribuir um nome significativo na interface do usuário do Word, depois de inserir um controle de conteúdo Rich Text do grupo Controles na guia Desenvolvedor da faixa de opções, use o comando Propriedades no grupo Controles para exibir a caixa de diálogo Propriedades de Controle de Conteúdo. Em seguida, defina a propriedade Title do controle de conteúdo para o nome ao qual você deseja fazer referência por meio do seu código.

Observação: no Word, se houver vários controles de conteúdo rich text com o mesmo valor de propriedade Title (nome) e você tentar associar a um desses controles de conteúdo com esse método (especificando seu nome como o parâmetro itemName), a operação falhará.

Exemplos

// The following example adds a binding to the myRange named item in Excel as a "matrix" binding,
// and assigns the binding's id as myMatrix.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// The following example adds a binding to the Table1 named item in Excel as a "table" binding,
// and assigns the binding's id as myTable.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "Table1", "table", {id:'myTable'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// The following example creates a text binding in Word to a rich text content control named "FirstName",
// assigns the id "firstName", and then displays that information.
function bindContentControl() {
    Office.context.document.bindings.addFromNamedItemAsync('FirstName', 
        Office.BindingType.Text, {id:'firstName'},
        function (result) {
            if (result.status === Office.AsyncResultStatus.Succeeded) {
                write('Control bound. Binding.id: '
                    + result.value.id + ' Binding.type: ' + result.value.type);
            } else {
                write('Error:', result.error.message);
            }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Cria uma associação com um objeto nomeado no documento.

addFromNamedItemAsync(itemName: string, bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

itemName: string

Nome do objeto associável no documento. Por exemplo, a tabela 'MyExpenses' no Excel."

bindingType: Office.BindingType

O Office.BindingType para os dados. O método retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa o item nomeado especificado.

Retornos

void

Comentários

MatrixBindings, TableBindings, TextBindings

Para o Excel, o parâmetro itemName pode se referir a um intervalo nomeado ou a uma tabela.

Por padrão, a adição de uma tabela no Excel atribui o nome "Tabela1" à primeira tabela que você adicionar, "Tabela2" para a segunda tabela adicionada e assim por diante. Para atribuir um nome significativo para uma tabela na interface do usuário do Excel, use a propriedade Nome da Tabela nas Ferramentas de Tabela | Guia design da faixa de opções.

Observação: no Excel, ao especificar uma tabela como um item nomeado, você deve qualificar totalmente o nome para incluir o nome da planilha no nome da tabela neste formato: "Folha1! Table1"

Para o Word, o parâmetro itemName refere-se à propriedade Title de um controle de conteúdo rich text. (Você não pode associar-se a controles de conteúdo que não sejam o controle de conteúdo rich text).

Por padrão, um controle de conteúdo não tem nenhum valor de título atribuído. Para atribuir um nome significativo na interface do usuário do Word, depois de inserir um controle de conteúdo Rich Text do grupo Controles na guia Desenvolvedor da faixa de opções, use o comando Propriedades no grupo Controles para exibir a caixa de diálogo Propriedades de Controle de Conteúdo. Em seguida, defina a propriedade Title do controle de conteúdo para o nome ao qual você deseja fazer referência por meio do seu código.

Observação: no Word, se houver vários controles de conteúdo rich text com o mesmo valor de propriedade Title (nome) e você tentar associar a um desses controles de conteúdo com esse método (especificando seu nome como o parâmetro itemName), a operação falhará.

Crie uma associação solicitando que o usuário faça uma seleção no documento.

addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

bindingType: Office.BindingType

Especifica o tipo do objeto de associação a ser criado. Obrigatório. Retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

options: Office.AddBindingFromPromptOptions

Fornece opções para configurar o prompt e identificar a associação criada.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa a seleção especificada pelo usuário.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Adiciona um objeto de associação do tipo especificado à coleção Bindings, que será identificada com a ID fornecida. O método falhará se a seleção especificada não puder ser vinculada.

Exemplos

function addBindingFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(
        Office.BindingType.Text, 
        { id: 'MyBinding', promptText: 'Select text to bind to.' },
        function (asyncResult) {
            write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Crie uma associação solicitando que o usuário faça uma seleção no documento.

addFromPromptAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

bindingType: Office.BindingType

Especifica o tipo do objeto de associação a ser criado. Obrigatório. Retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa a seleção especificada pelo usuário.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Adiciona um objeto de associação do tipo especificado à coleção Bindings, que será identificada com a ID fornecida. O método falhará se a seleção especificada não puder ser vinculada.

Crie uma associação com base na seleção atual do usuário.

addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

bindingType: Office.BindingType

Especifica o tipo do objeto de associação a ser criado. Obrigatório. Retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

options: Office.AddBindingFromSelectionOptions

Fornece opções para identificar a associação criada.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa a seleção especificada pelo usuário.

Retornos

void

Comentários

Conjuntos de requisitos:

Adiciona o tipo especificado de objeto de associação à coleção Bindings, que será identificada com a ID fornecida.

Observação No Excel, se você chamar o método addFromSelectionAsync passando o Binding.id de uma associação existente, o binding.type dessa associação será usado e seu tipo não poderá ser alterado especificando um valor diferente para o parâmetro bindingType. Se você precisar usar uma ID existente e alterar o bindingType, chame o método Bindings.releaseByIdAsync primeiro para liberar a associação e chame o método addFromSelectionAsync para restabelecer a associação com um novo tipo.

Exemplos

function addBindingFromSelection() {
    Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'MyBinding' }, 
        function (asyncResult) {
        write('Added new binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
        }
    );
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Crie uma associação com base na seleção atual do usuário.

addFromSelectionAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

bindingType: Office.BindingType

Especifica o tipo do objeto de associação a ser criado. Obrigatório. Retornará nulo se o objeto selecionado não puder ser coagido para o tipo especificado.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding que representa a seleção especificada pelo usuário.

Retornos

void

Comentários

Conjuntos de requisitos:

Adiciona o tipo especificado de objeto de associação à coleção Bindings, que será identificada com a ID fornecida.

Observação No Excel, se você chamar o método addFromSelectionAsync passando o Binding.id de uma associação existente, o binding.type dessa associação será usado e seu tipo não poderá ser alterado especificando um valor diferente para o parâmetro bindingType. Se você precisar usar uma ID existente e alterar o bindingType, chame o método Bindings.releaseByIdAsync primeiro para liberar a associação e chame o método addFromSelectionAsync para restabelecer a associação com um novo tipo.

Obtém todas as associações criadas anteriormente.

getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding[]>) => void): void;

Parâmetros

options: Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para uso em um retorno de chamada.

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é uma matriz que contém cada associação criada para o objeto Bindings referenciado.

Retornos

void

Comentários

Conjuntos de requisitos:

Obtém todas as associações criadas anteriormente.

getAllAsync(callback?: (result: AsyncResult<Binding[]>) => void): void;

Parâmetros

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é uma matriz que contém cada associação criada para o objeto Bindings referenciado.

Retornos

void

Comentários

Conjuntos de requisitos:

Exemplos

function displayAllBindingNames() {
    Office.context.document.bindings.getAllAsync(function (asyncResult) {
        let bindingString = '';
        for (let i in asyncResult.value) {
            bindingString += asyncResult.value[i].id + '\n';
        }
        write('Existing bindings: ' + bindingString);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Recupera uma associação com base em seu Nome

getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

id: string

Especifica o nome exclusivo do objeto de associação. Obrigatório.

options: Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para uso em um retorno de chamada.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding especificado pela ID na chamada.

Retornos

void

Comentários

Conjuntos de requisitos:

Falhará se a ID especificada não existir.

Recupera uma associação com base em seu Nome

getByIdAsync(id: string, callback?: (result: AsyncResult<Binding>) => void): void;

Parâmetros

id: string

Especifica o nome exclusivo do objeto de associação. Obrigatório.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é o objeto Binding especificado pela ID na chamada.

Retornos

void

Comentários

Conjuntos de requisitos:

Falhará se a ID especificada não existir.

Exemplos

function displayBindingType() {
    Office.context.document.bindings.getByIdAsync('MyBinding', function (asyncResult) {
        write('Retrieved binding with type: ' + asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Remove a associação do documento

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

Parâmetros

id: string

Especifica o nome exclusivo a ser usado para identificar o objeto de associação. Obrigatório.

options: Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para uso em um retorno de chamada.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjuntos de requisitos:

Falhará se a ID especificada não existir.

Remove a associação do documento

releaseByIdAsync(id: string, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

id: string

Especifica o nome exclusivo a ser usado para identificar o objeto de associação. Obrigatório.

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjuntos de requisitos:

Falhará se a ID especificada não existir.

Exemplos

Office.context.document.bindings.releaseByIdAsync("MyBinding", function (asyncResult) { 
    write("Released MyBinding!"); 
}); 
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message;  
}

addFromNamedItemAsync(itemName, bindingType, options, callback)	Cria uma associação com um objeto nomeado no documento.
addFromNamedItemAsync(itemName, bindingType, callback)	Cria uma associação com um objeto nomeado no documento.
addFromPromptAsync(bindingType, options, callback)	Crie uma associação solicitando que o usuário faça uma seleção no documento.
addFromPromptAsync(bindingType, callback)	Crie uma associação solicitando que o usuário faça uma seleção no documento.
addFromSelectionAsync(bindingType, options, callback)	Crie uma associação com base na seleção atual do usuário.
addFromSelectionAsync(bindingType, callback)	Crie uma associação com base na seleção atual do usuário.
getAllAsync(options, callback)	Obtém todas as associações criadas anteriormente.
getAllAsync(callback)	Obtém todas as associações criadas anteriormente.
getByIdAsync(id, options, callback)	Recupera uma associação com base em seu Nome
getByIdAsync(id, callback)	Recupera uma associação com base em seu Nome
releaseByIdAsync(id, options, callback)	Remove a associação do documento
releaseByIdAsync(id, callback)	Remove a associação do documento

Compartilhar via

Propriedades

Métodos

Detalhes da propriedade

document

Valor da propriedade

Detalhes do método

addFromNamedItemAsync(itemName, bindingType, options, callback)

Parâmetros

Retornos

Comentários

Exemplos

addFromNamedItemAsync(itemName, bindingType, callback)

Parâmetros

Retornos

Comentários

addFromPromptAsync(bindingType, options, callback)

Parâmetros

Retornos

Comentários

Exemplos

addFromPromptAsync(bindingType, callback)

Parâmetros

Retornos

Comentários

addFromSelectionAsync(bindingType, options, callback)

Parâmetros

Retornos

Comentários

Exemplos

addFromSelectionAsync(bindingType, callback)

Parâmetros

Retornos

Comentários

getAllAsync(options, callback)

Parâmetros

Retornos

Comentários

getAllAsync(callback)

Parâmetros

Retornos

Comentários

Exemplos

getByIdAsync(id, options, callback)

Parâmetros

Retornos

Comentários

getByIdAsync(id, callback)

Parâmetros

Retornos

Comentários

Exemplos

releaseByIdAsync(id, options, callback)

Parâmetros

Retornos

Comentários

releaseByIdAsync(id, callback)

Parâmetros

Retornos

Comentários

Exemplos

Recursos adicionais