Compartilhar via

Adicionar controles aos documentos do Office em tempo de execução

Você pode adicionar controles a um documento do Microsoft Office Word e à pasta de trabalho do Microsoft Office Excel em tempo de execução. Você também pode removê-los durante a execução. Os controles que você adiciona ou remove em tempo de execução são chamados de controles dinâmicos.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de suplemento VSTO para Excel e Word. Para obter mais informações, consulte Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Este tópico descreve o seguinte:

Gerenciar controles em tempo de execução usando coleções de controle

Para adicionar, obter ou remover controles em tempo de execução, use os métodos auxiliares dos objetos ControlCollection e ControlCollection.

A maneira como você acessa esses objetos depende do tipo de projeto que você está desenvolvendo:

Adicionar controles

Os tipos ControlCollection e ControlCollection incluem métodos auxiliares que você pode usar para adicionar controles de host e controles comuns do Windows Forms a documentos e planilhas. Cada nome de método tem a Add de formato, em que a classe de controle é o nome da classe do controle que você deseja adicionar. Por exemplo, para adicionar um NamedRange controle ao seu documento, use o AddNamedRange método.

O exemplo de código a seguir adiciona um NamedRange a Sheet1 em um projeto de nível de documento do Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Controles de acesso e exclusão

Você pode usar a Controls propriedade de um Worksheet ou Document para percorrer todos os controles em seu documento, incluindo os controles adicionados em tempo de design. Os controles que você adiciona em tempo de design também são chamados de controles estáticos.

Você pode remover controles dinâmicos chamando o Delete método do controle ou chamando o Remove método de cada coleção Controls. O exemplo de código a seguir usa o método Remove para remover NamedRange de Sheet1 em um projeto de nível de documento para Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Não é possível remover controles estáticos em tempo de execução. Se você tentar usar o método Delete ou Remove para remover um controle estático, um CannotRemoveControlException será gerado.

Observação

Não remova os controles programaticamente no Shutdown manipulador de eventos do documento. Os elementos de interface do usuário do documento não estão mais disponíveis quando o Shutdown evento é acionado. Se você quiser remover os controles antes do fechamento do documento, adicione seu código ao manipulador de eventos para outro evento, como BeforeClose ou BeforeSave para o Word, ou BeforeClosepara BeforeSave o Excel.

Adicionar controles de host a documentos

Ao adicionar programaticamente controles de host a documentos, você deve fornecer um nome que identifique exclusivamente o controle e especifique onde adicionar o controle no documento. Para obter instruções específicas, consulte os seguintes tópicos:

Para obter mais informações sobre controles de host, consulte a visão geral de itens de host e controles de host.

Quando um documento é salvo e fechado, todos os controles de host criados dinamicamente são desconectados de seus eventos e perdem a funcionalidade de associação de dados. Você pode adicionar código à sua solução para recriar os controles de host quando o documento for reaberto. Para obter mais informações, consulte Persistência de controles dinâmicos em documentos do Office.

Observação

Os métodos auxiliares não são fornecidos para os seguintes controles de host, pois esses controles não podem ser adicionados programaticamente a documentos: XmlMappedRange, XMLNodee XMLNodes.

Adicionar controles do Windows Forms a documentos

Ao adicionar programaticamente um controle do Windows Forms a um documento, você deve fornecer o local do controle e um nome que identifique exclusivamente o controle. O runtime das Ferramentas do Visual Studio para Office fornece métodos auxiliares para cada controle. Esses métodos são sobrecarregados para que você possa fornecer um intervalo ou coordenadas específicas para a posição do controle.

Quando um documento é salvo e fechado, todos os controles do Windows Forms criados dinamicamente são removidos do documento. Você pode adicionar código à sua solução para recriar os controles quando o documento for reaberto. Se você criar controles dinâmicos do Windows Forms usando um Suplemento VSTO, os wrappers ActiveX para os controles serão deixados no documento. Para obter mais informações, consulte Persistência de controles dinâmicos em documentos do Office.

Observação

Os controles do Windows Forms não podem ser adicionados programaticamente a documentos protegidos. Se você desproteger programaticamente um documento do Word ou uma planilha do Excel para adicionar um controle, deverá escrever um código adicional para remover o wrapper ActiveX do controle quando o documento for fechado. O wrapper ActiveX do controle não é excluído automaticamente de documentos protegidos.

Adicionar controles personalizados

Se você quiser adicionar um Control que não tenha suporte pelos métodos auxiliares disponíveis, como um controle de usuário personalizado, use os seguintes métodos:

  • Para o Excel, use um dos AddControl métodos de um ControlCollection objeto.

  • Para Word, use um dos AddControl métodos de um ControlCollection objeto.

    Para adicionar o controle, passe o Control, um local para o controle e um nome que identifique exclusivamente o controle ao método AddControl. O AddControl método retorna um objeto que define como o controle interage com a planilha ou o documento. O AddControl método retorna um ControlSite (para Excel) ou um ControlSite objeto (para o Word).

    O exemplo de código a seguir demonstra como usar o AddControl método para adicionar dinamicamente um controle de usuário personalizado a uma planilha em um projeto do Excel no nível do documento. Neste exemplo, o controle de usuário é nomeado UserControl1, e o Range é nomeado range1. Para usar este exemplo, execute-o a partir de uma classe Sheetn no projeto.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Usar membros de controles personalizados

Depois de usar um dos AddControl métodos para adicionar um controle a uma planilha ou documento, agora você tem dois objetos de controle diferentes:

  • O Control que representa o controle personalizado.

  • O ControlSite, OLEObject ou OLEControl objeto que representa o controle depois que foi adicionado à planilha ou documento.

    Muitas propriedades e métodos são compartilhados entre esses controles. É importante que você acesse esses membros por meio do controle apropriado:

  • Para acessar membros que pertencem apenas ao controle personalizado, use o Control.

  • Para acessar membros que são compartilhados pelos controles, use o ControlSite, OLEObject ou OLEControl objeto.

    Se você acessar um membro compartilhado do Control, ele poderá falhar sem aviso ou notificação ou pode produzir resultados inválidos. Sempre use métodos ou propriedades de ControlSite, OLEObjectou OLEControl objeto, a menos que o método ou propriedade necessária não esteja disponível; somente então você deve referenciar o Control.

    Por exemplo, a ControlSite classe e a Control classe têm uma Top propriedade. Para obter ou definir a distância entre a parte superior do controle e a parte superior do documento, use a Top propriedade do ControlSite, não a Top propriedade do Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Conteúdo relacionado

  • Last updated on