Visão geral dos controles do Windows Forms em documentos do Office

Artigo
09/23/2023

Os controles do Windows Forms são objetos com os quais os usuários podem interagir para inserir ou manipular dados. Em projetos de nível de documento para Microsoft Office Excel e Microsoft Office Word, você pode adicionar controles do Windows Forms ao documento ou pasta de trabalho em seu projeto em tempo de design ou pode adicionar programaticamente esses controles em tempo de execução. Você pode adicionar programaticamente esses controles a qualquer documento ou planilha aberta em tempo de execução em um suplemento VSTO para Excel ou Word.

Para obter mais informações, consulte Como: Adicionar controles do Windows Forms a documentos do Office.

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.

Usar controles do Windows Forms

Você pode adicionar controles do Windows Forms a documentos e a elementos personalizáveis da interface do usuário, incluindo painéis de ações, painéis de tarefas personalizados e Windows Forms. Os controles do Windows Forms geralmente têm o mesmo comportamento em documentos que nesses outros elementos da interface do usuário, mas existem algumas diferenças. Para obter informações, consulte Limitações de controles do Windows Forms em documentos do Office.

A decisão de adicionar controles do Windows Forms a um documento ou a algum outro elemento da interface do usuário depende de vários fatores. Ao projetar a interface do usuário de sua solução, considere os usos de controles do Windows Forms, conforme descrito na tabela a seguir.

Em um documento.

Quando você deseja exibir os controles 100% do tempo.
Quando você deseja que os usuários insiram dados diretamente no documento, por exemplo, em documentos baseados em formulários em que a superfície de edição está bloqueada.
Quando você deseja que os controles sejam exibidos em linha com os dados no documento. Por exemplo, se você estiver adicionando botões a cada linha de um objeto de lista, você desejará que eles estejam alinhados com cada item de lista.

No painel de ações ou em um painel de tarefas personalizado.

Quando você deseja fornecer informações contextuais ao usuário.
Quando você deseja que apenas os resultados apareçam no documento, e não os controles e dados de consulta.
Quando você deseja garantir que os controles não sejam impressos com o documento.
Quando você deseja garantir que os controles não interfiram na exibição do documento.

Em um formulário do Windows.

Quando você deseja controlar o tamanho da interface do usuário.
Quando você deseja impedir que os usuários ocultem ou excluam os controles.
Quando você deseja obter entrada do usuário e impedir que o usuário faça qualquer coisa no documento até que a entrada seja recebida.

Adicionar controles do Windows Forms programaticamente

Você pode adicionar controles do Windows Forms a documentos do Word e planilhas do Excel em tempo de execução. O Visual Studio Tools for Office runtime fornece métodos auxiliares para adicionar os controles mais comuns do Windows Forms. Esses métodos auxiliares permitem que você adicione rapidamente controles ao seu documento do Office e acesse a funcionalidade de controle combinada do Windows Forms e a funcionalidade relacionada ao Office desses controles.

Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Usar controles do Windows Forms em projetos de nível de documento

Alguns aspectos do uso de controles do Windows Forms em documentos são exclusivos para projetos de nível de documento, que permitem que você crie a interface do usuário do documento usando o designer do Visual Studio.

Criar controles de usuário personalizados

Você pode adicionar um controle de usuário ao seu projeto e, em seguida, adicioná-lo à caixa de ferramentas. Em seguida, você pode arrastar o controle de usuário diretamente para o documento da mesma forma que adicionaria um controle do Windows Forms ao documento. Há algumas coisas a ter em mente ao criar controles de usuário:

Não crie um controle de usuário lacrado . Quando você arrasta o controle para o documento, o Visual Studio gera uma classe wrapper derivada do controle de usuário para estendê-lo e oferecer suporte ao seu uso no documento. Se o controle de usuário estiver lacrado, o Visual Studio não poderá gerar a classe wrapper.
Os controles de usuário devem ter o ComVisibleAttribute atributo definido como true. Os controles de usuário criados dentro de um projeto do Office têm esse atributo definido como true por padrão, mas os controles de usuário que fazem parte de projetos externos podem não ter esse atributo definido como true.
Depois de adicionar um controle de usuário ao documento, não renomeie ou exclua a UserControl classe do projeto. Se você precisar alterar o nome de um controle de usuário, primeiro exclua-o do documento e, em seguida, adicione-o novamente depois que o nome for alterado.

Organizar controles em tempo de design

Se você adicionar vários controles aos seus documentos do Word e do Excel em tempo de design, poderá definir rapidamente o alinhamento de todos os controles selecionados usando as barras de ferramentas do Microsoft Office Word e do Microsoft Office Excel no Visual Studio. Essas barras de ferramentas estão disponíveis somente quando um documento ou planilha está aberto no designer.

Ao selecionar vários controles no designer, você pode usar os seguintes botões nessas barras de ferramentas para organizar os controles:

Alinhar à esquerda
Alinhar Centros
Alinhar direitos
Alinhar Tops
Alinhar intermediários
Alinhar fundos
Igualar o espaçamento horizontal
Igualar o espaçamento vertical

Observação

Em projetos do Word, esses botões são habilitados somente se os controles selecionados não estiverem alinhados com o texto. Por padrão, os controles que você adiciona ao documento em tempo de design estão alinhados com o texto.

Impedir que dados antigos apareçam em pastas de trabalho do Excel durante o carregamento

Quando você adiciona controles do Windows Forms a documentos ou planilhas em tempo de design, os controles permanecem no documento quando o usuário fecha o documento. Os controles adicionados em tempo de design também são chamados de controles estáticos.

Quando uma pasta de trabalho do Excel que contém controles estáticos é aberta, a pasta de trabalho exibe um bitmap do controle em um controle ActiveX até que o código de personalização seja executado e carregue o controle real. O Excel cria esse bitmap e o armazena na pasta de trabalho sempre que a pasta de trabalho é salva. O bitmap mostra o controle como ele apareceu na última vez que a pasta de trabalho foi salva, incluindo todos os dados que o controle estava exibindo. Para obter mais informações sobre o controle ActiveX que contém controles e bitmaps do Windows Forms, consulte Limitações de controles do Windows Forms em documentos do Office.

Em determinadas condições, o código não é carregado e somente o bitmap é exibido, como quando o usuário abre a pasta de trabalho no modo de design. Além disso, se o usuário abrir a pasta de trabalho em um computador que não tenha o Visual Studio Tools for Office runtime instalado, a personalização não pode ser executada para carregar os controles e, portanto, somente o bitmap do controle é visível. Você deve sempre remover informações pessoais de controles em pastas de trabalho antes de salvar a pasta de trabalho e enviá-la a outro usuário para garantir que suas informações pessoais não sejam divulgadas acidentalmente.

Corresponder o tamanho do controle ao tamanho da célula em uma planilha do Excel

Você pode definir o controle para ser redimensionado automaticamente quando o tamanho da célula pai é alterado. Para obter mais informações, consulte Como: Redimensionar controles dentro de células da planilha.

Adicionar componentes que são compartilhados por todas as planilhas

Você pode adicionar componentes que deseja compartilhar entre todas as planilhas, como um DataSet, ao Designer de Pasta de Trabalho em vez de às planilhas. O componente aparecerá na bandeja do componente.

Fórmula para incorporar controles em uma planilha do Excel

Ao selecionar um controle no Excel, você verá =EMBED("WinForms.Control.Host","") na Barra de Fórmulas. Este texto é necessário e não deve ser suprimido.

Estilo de layout de controles em um documento do Word

Quando você adiciona um controle ao documento do Word em um projeto de nível de documento usando o designer do Visual Studio, o controle é adicionado em linha com o texto. Para alterar o estilo de layout do controle, clique com o botão direito do mouse no controle e clique em Formatar Controle. Selecione um estilo de quebra automática na página Layout da caixa de diálogo Formatar Objeto .

Quando você adiciona um controle a um documento do Word em tempo de execução, você pode especificar o estilo de layout do novo controle usando Add<diferentes sobrecargas de método de classe de controle da ControlCollection classe>:

Para adicionar o controle em linha com texto, use uma sobrecarga que aceita um Range que especifica o local do controle.
Para adicionar o controle como uma forma flutuante, use uma sobrecarga que aceite as coordenadas esquerda e superior do controle.

Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Se você abrir um modelo do Word no designer do Visual Studio, controles não embutidos no modelo podem não estar visíveis porque o Visual Studio abre o modelo no modo de exibição Normal . Para exibir os controles, altere o modo de exibição para Layout de Impressão.

Controles fora do corpo do documento principal

Não há suporte para controles do Windows Forms dentro de um cabeçalho ou rodapé ou dentro de um subdocumento.

Adicionar componentes em tempo de design

Determinados controles ou componentes não são visíveis no documento e, em vez disso, são exibidos em uma bandeja de componentes. Visual Studio fornece uma bandeja de componente para cada janela de documento. A bandeja de componentes aparecerá na tela somente se houver componentes no documento.