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

  • Artigo

Você pode adicionar controles a um documento do Microsoft Office Word e a uma pasta de trabalho do Microsoft Office Excel em tempo de execução. Você também pode removê-los em tempo de 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 Recursos disponíveis por aplicativo e tipo de projeto do Office.

Este tópico descreve os seguintes itens:

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

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

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

  • Em um projeto de nível de documento para Excel, use a ControlsSheet1propriedade das classes , Sheet2e Sheet3 . Para obter mais informações sobre essas classes, consulte Item de host de planilha.

  • Em um projeto de nível de documento para o Word, use a ControlsThisDocument propriedade da classe. Para obter mais informações sobre essa classe, consulte Item de host do documento.

  • Em um projeto de suplemento VSTO para Excel ou Word, use a Controls propriedade de um Worksheet ou Document que você gera em tempo de execução. Para obter mais informações sobre como gerar esses objetos em tempo de execução, consulte Estender documentos do Word e pastas de trabalho do Excel em suplementos VSTO em tempo de execução.

Adicionar controles

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

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

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

Acessar e excluir controles

Você pode usar a Controls propriedade de um Worksheet ou Document para iterar por 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 Remove método para remover um de em um NamedRange projeto de nível de Sheet1 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 Delete método or Remove para remover um controle estático, um CannotRemoveControlException será lançado.

Observação

Não remova programaticamente controles Shutdown no manipulador de eventos do documento. Os elementos da interface do usuário do documento não estão mais disponíveis quando o Shutdown evento é gerado. Se você quiser remover controles antes que o documento seja fechado, adicione seu código ao manipulador de eventos para outro evento, como BeforeClose ou para o Word, ou , ou BeforeSaveBeforeSaveBeforeClosepara 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 especificar 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 Visão geral sobre itens de host e controles de host.

Quando um documento é salvo e, em seguida, fechado, todos os controles de host criados dinamicamente são desconectados de seus eventos e perdem sua funcionalidade de vinculaçã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 Persistir controles dinâmicos em documentos do Office.

Observação

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

Adicionar controles do Windows Forms a documentos

Quando você adiciona programaticamente um controle do Windows Forms a um documento, você deve fornecer o local do controle e um nome que identifica exclusivamente o controle. O Visual Studio Tools for Office runtime fornece métodos auxiliares para cada controle. Esses métodos são sobrecarregados para que você possa passar um intervalo ou coordenadas específicas para o local do controle.

Quando um documento é salvo e, em seguida, 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 Persistir 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 planilha do Excel para adicionar um controle, você deve escrever código adicional para remover o wrapper ActiveX do controle quando o documento é fechado. O wrapper ActiveX do controle não é excluído automaticamente dos documentos protegidos.

Adicionar controles personalizados

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

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

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

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

    O exemplo de código a seguir demonstra como usar o método para adicionar dinamicamente um controle de usuário personalizado a AddControl uma planilha em um projeto do Excel em nível de documento. Neste exemplo, o controle de usuário é chamado e o Range é chamado .range1UserControl1 Para usar este exemplo, execute-o a partir de uma Sheetclasse n 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, OLEObjectou objeto que representa o controle depois que ele foi adicionado à planilha ou OLEControl documento.

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

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

  • Para acessar membros que são compartilhados pelos controles, use o ControlSiteobjeto , OLEObjectou OLEControl .

    Se você acessar um membro compartilhado a Controlpartir do , ele poderá falhar sem aviso ou notificação, ou poderá produzir resultados inválidos. Sempre use métodos ou propriedades do ControlSiteobjeto , ou , a menos que o método ou a OLEControl propriedade necessária não esteja disponível, OLEObjectsó então você deve fazer referência ao Control.

    Por exemplo, a classe e a ControlSiteControl 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 TopControlSitepropriedade do , 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