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

  • Artigo

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

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de nível de aplicativo para os seguintes aplicativos: Excel 2007 e Excel 2010; Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Este tópico fornece as seguintes informações:

  • Gerenciando os controles em tempo de execução usando as coleções de controle

  • Adicionar controles de host para documentos

  • Adicionando controles Windows Forms a documentos

link para vídeo Para uma demonstração de vídeo relacionada, consulte Fazer como i: Adicionar controles a uma superfície do documento em tempo de execução?.

Gerenciando os controles em tempo de execução usando as coleções de controle

Para adicionar, get ou remover controles em tempo de execução, use os métodos auxiliares de Microsoft.Office.Tools.Excel.ControlCollection e Microsoft.Office.Tools.Word.ControlCollection objetos.

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

Adding Controls

O Microsoft.Office.Tools.Excel.ControlCollection e Microsoft.Office.Tools.Word.ControlCollection os tipos incluem métodos auxiliares, você pode usar para adicionar controles de host e controles comuns do Windows Forms a documentos e planilhas. O nome de cada método tem o formato Add<a classe de controle>, onde a classe de controle é o nome da classe do controle que você deseja adicionar. Por exemplo, para adicionar um NamedRange o controle ao seu documento, use o AddNamedRange método. Para obter uma lista completa dos métodos auxiliares, consulte Métodos auxiliares para controles de Host e Métodos auxiliares para controles Windows Forms.

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

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

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

Acessando e exclusão de controles

Você pode usar o Controls propriedade de um Microsoft.Office.Tools.Excel.Worksheet ou Microsoft.Office.Tools.Word.Document para iterar em todos os controles em seu documento, incluindo os controles adicionados em tempo de design. Também são chamados de controles que podem ser adicionados em tempo de design controles estáticos.

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

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

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

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

ObservaçãoObservação

Não remova controles programaticamente o Shutdown o manipulador de eventos do documento. Os elementos da interface do documento não estão mais disponíveis quando o Shutdown evento é gerado. Se desejar remover os controles antes de ser fechado o documento, adicione seu código ao manipulador de eventos para um outro evento, tal como Document.BeforeClose ou Document.BeforeSave para o Word, ou Workbook.BeforeClose, ou Workbook.BeforeSave para o Excel.

Adicionar controles de Host para documentos

Quando você adiciona controles de host programaticamente a documentos, você deve fornecer um nome que identifica exclusivamente o controle e você deve 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 Itens de host e a visão geral sobre controles de Host.

Quando um documento é salvo e, em seguida, fechado, todos os controles de host criado dinamicamente são desconectados de seus eventos e perda de funcionalidade de ligação de dados. Você pode adicionar código à sua solução para recriar os controles de host quando o documento for reaberto. For more information, see Persistência de controles dinâmicos em documentos do Office.

ObservaçãoObservação

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, XMLNode, and XMLNodes.

Adicionando controles do Windows Forms a documentos

Quando você adiciona programaticamente um controle 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 estão sobrecarregados para que você pode passar um intervalo ou coordenadas específicas para o local do controle. Para obter instruções específicas, consulte Como: Adicionar controles do Windows Forms a documentos do Office.

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 recriar controles quando o documento for reaberto. Se você criar controles dinâmicos de Windows Forms usando um suplemento em nível de aplicativo, os invólucros de ActiveX para os controles são deixados no documento. For more information, see Persistência de controles dinâmicos em documentos do Office.

ObservaçãoObservação

Controles de formulários do Windows não podem ser adicionados programaticamente a documentos protegidos. Se você programaticamente Desproteger um documento do Word ou uma planilha do Excel para adicionar um controle, você deve escrever código adicional para remover o wrapper de ActiveX do controle quando o documento é fechado. Wrapper de ActiveX do controle não será excluído automaticamente de documentos protegidos.

Adicionando controles personalizados

Se você deseja adicionar um System.Windows.Forms.Control que não é suportada pelos métodos auxiliares disponíveis (por exemplo, um controle de usuário personalizada), use os seguintes métodos:

Para adicionar o controle, passe o System.Windows.Forms.Control, um local para o controle e um nome que identifica exclusivamente o controle para o AddControl método. O AddControl método retorna um objeto que define como o controle interage com a planilha ou documento. O tipo de objeto retornado depende do projeto:

O exemplo de código a seguir demonstra como usar o AddControl(Control, Range, String) método para adicionar dinamicamente um usuário personalizado controle a uma planilha em um projeto de nível de documento do Excel voltado para o .NET Framework 4. Neste exemplo, o controle de usuário é chamado UserControl1e o Range chamado range1. Para usar esse exemplo, executá-lo em um Sheetn classe no projeto.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

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

Usando membros de controles personalizados

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

  • O System.Windows.Forms.Control que representa o controle personalizado.

  • O ControlSite, OLEObject, ou OLEControl objeto que representa o controle depois que ele 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 os membros que pertencem somente para o controle personalizado, use o System.Windows.Forms.Control.

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

Se você acessar um membro compartilhado a partir de System.Windows.Forms.Control, ela pode falhar sem aviso ou notificação, ou pode produzir resultados inválidos. Sempre usar métodos ou propriedades da ControlSite, OLEObject, ou OLEControl objeto, a menos que o método ou propriedade necessária não está disponível; só então você deve consultar a System.Windows.Forms.Control.

Por exemplo, ambos os ControlSite classe e o System.Windows.Forms.Control classe tem um Top propriedade. Para obter ou definir a distância entre a parte superior do controle e a parte superior do documento, use o Top propriedade da ControlSite, e não o Top propriedade da System.Windows.Forms.Control.

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

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

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

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

Consulte também

Tarefas

Como: Adicionar controles de ListObject às planilhas

Como: Adicionar controles de NamedRange para planilhas

Como: Adicionar controles de gráfico para planilhas

Como: Adicionar controles de conteúdo para documentos do Word

Como: Adicionar controles de indicador para documentos do Word

Como: Adicionar controles do Windows Forms a documentos do Office

Conceitos

Persistência de controles dinâmicos em documentos do Office

Métodos auxiliares para controles de Host

Métodos auxiliares para controles Windows Forms

Controles do Windows Forms em Visão geral de documentos do Office

Outros recursos

Controles em documentos do Office