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

  • Artigo

Você pode adicionar controles a um documento Microsoft Office Word e 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ê adicionar ou remover em tempo de execução são chamados 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 2013 e Excel 2010; Word 2013 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

este tópico descreve o seguinte:

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

  • Adicionando controles host para documentos.

  • Adicionando controles de formulários do windows para documentos.

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

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

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

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

x97a5x3s.collapse_all(pt-br,VS.110).gifAdicionar Controles

Os tipos de Microsoft.Office.Tools.Excel.ControlCollection e de Microsoft.Office.Tools.Word.ControlCollection incluem os métodos auxiliares que você pode usar para adicionar controles host e controles comuns de formulários do windows para documentos e a planilhas.Cada nome do método tem o formato Addclasse de controleclasse de controle , onde é o nome da classe do controle que você deseja adicionar.Por exemplo, para adicionar NamedRange controle para o documento, use o método de AddNamedRange .

O exemplo de código a seguir adiciona NamedRange a Sheet1 em um projeto da nível do 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");

x97a5x3s.collapse_all(pt-br,VS.110).gifAcessando controles e excluindo

Você pode usar a propriedade de Controls de Microsoft.Office.Tools.Excel.Worksheet ou de Microsoft.Office.Tools.Word.Document para iterar por todos os controles em seu documento, incluindo controles que você adicionou em tempo de design.Os controles que você adicionar em tempo de design são chamados também controles.

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

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

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

você não pode remover os controles estáticos em tempo de execução.Se você tentar usar o método de Delete ou de Remove para remover um controle estático, CannotRemoveControlException será apresentada.

ObservaçãoObservação

Não remover programaticamente os controles no manipulador de eventos de Shutdown do documento.Os elementos de interface de usuário do documento não estão mais disponíveis quando o evento de Shutdown é gerado.Se você deseja remover os controles antes do documento fechar, adicione o código ao manipulador de eventos para outro evento, como Document.BeforeClose ou Document.BeforeSave por palavras, ou Workbook.BeforeClose, ou Workbook.BeforeSave para o excel.

Adicionando controles host para documentos

Quando você adiciona controles por meio de host para documentos, você deve fornecer um nome que identifica unicamente o controle, e você deve especificar onde adicionar o controle no documento.Para instruções específicas, consulte os seguintes tópicos:

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

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

ObservaçãoObservação

Os métodos auxiliares não são fornecidos para os seguintes controles host, porque esses controles não podem ser adicionados por meio para documentos: XmlMappedRange, XMLNode, e XMLNodes.

Adicionando controles de formulários do windows para documentos

Quando você adiciona programaticamente um controle de formulários do windows a um documento, você deve fornecer o controle local e um nome que identifica unicamente o controle.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ífico para o local do controle.

Quando um documento é salvo e fechado em seguida, todos os controles de formulários do windows criados dinamicamente são removidos do documento.Você pode adicionar código à sua solução para recriar controles quando o documento é reaberta.Se você criar controles dinâmicos de formulários do windows usando um suplemento ao aplicativo, os wrappers ActiveX para os controles são deixados no documento.Para obter mais informações, consulte Persisting controles dinâmicos em documentos do Office.

ObservaçãoObservação

Os controles de formulários do windows por meio não podem ser adicionados aos documentos protegidos.Se você programaticamente unprotect um documento do word ou uma planilha do excel para adicionar um controle, você deve escrever código adicional para remover o wrapper ActiveX de controle quando o documento está fechado.O wrapper do controle ActiveX não são excluídos automaticamente documentos protegidos.

x97a5x3s.collapse_all(pt-br,VS.110).gifadicionando controles personalizados

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

Para adicionar o controle, passe System.Windows.Forms.Control, um local para o controle, e um nome que identifica unicamente o controle para o método de AddControl .O método de AddControl retorna um objeto que define como o controle interage com a planilha ou documento.O método de AddControl retorna Microsoft.Office.Tools.Excel.ControlSite para o excel () ou um objeto de Microsoft.Office.Tools.Word.ControlSite para palavra ().

O exemplo de código demonstra como usar o método de AddControl(Control, Range, String) para adicionar dinamicamente um controle de usuário personalizados a uma planilha do excel em um projeto de um documento nível.Em esse exemplo, o controle de usuário é chamado UserControl1, e Range é chamado range1. Para usar este exemplo, ele execução de uma classe de Sheetem 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");

x97a5x3s.collapse_all(pt-br,VS.110).gifusando membros de controles personalizados

Após usado um dos métodos de AddControl para adicionar um controle a uma planilha ou a um documento, agora você tem dois objetos diferentes do controle:

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

  • ControlSite, OLEObject, ou objeto de OLEControl 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ê acessar esses membros através do controle apropriado:

  • Para acessar somente os membros que pertencem ao controle personalizado, use System.Windows.Forms.Control.

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

Se você acessar um membro compartilhado de System.Windows.Forms.Control, pode falhar sem aviso ou notificação, ou pode produzir resultados inválidos.Sempre use métodos ou propriedades de ControlSite, de OLEObject, ou do objeto de OLEControl a menos que o método ou propriedade necessário; eles não estão disponíveis somente em se você fazer referência System.Windows.Forms.Control.

Por exemplo, tanto a classe de ControlSite e a classe de System.Windows.Forms.Control possuem uma propriedade de Top .Para obter ou definir a distância entre a parte superior do controle e a parte superior do documento, use a propriedade de ControlSite, não a propriedade de Top de Top de 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 às planilhas

Como: adicionar controles de gráfico para planilhas

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

Como: adicionar controles de indicador aos documentos do Word

Como: adicionar controles do Windows Forms a documentos do Office

Conceitos

Persisting controles dinâmicos em documentos do Office

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

Outros recursos

Controles em documentos do Office