Compartilhar via


Office.Bindings interface

Representa as associações que o suplemento tem no documento.

Propriedades

document

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

Métodos

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

Detalhes da propriedade

document

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

document: Document;

Valor da propriedade

Detalhes do método

addFromNamedItemAsync(itemName, bindingType, options, callback)

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

addFromNamedItemAsync(itemName, bindingType, callback)

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

addFromPromptAsync(bindingType, options, callback)

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

addFromPromptAsync(bindingType, callback)

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.

addFromSelectionAsync(bindingType, options, callback)

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

addFromSelectionAsync(bindingType, callback)

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.

getAllAsync(options, callback)

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:

getAllAsync(callback)

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

getByIdAsync(id, options, callback)

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.

getByIdAsync(id, callback)

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

releaseByIdAsync(id, options, callback)

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.

releaseByIdAsync(id, callback)

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