Demonstra Passo a passo: Adicionar controles a uma planilha em tempo de execução no projeto de suplemento VSTO

Você pode adicionar controles a qualquer planilha aberta usando um suplemento VSTO do Excel. Este passo a passo demonstra como usar a Faixa de Opções para permitir que os usuários adicionem um , a e um ButtonListObject a a NamedRangeuma planilha. Para obter informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Aplica-se a: As informações neste tópico se aplicam a projetos de suplemento VSTO para Excel. Para obter mais informações, confira Features Available by Office Application and Project Type (Funcionalidades disponibilizadas pelo aplicativo do Office e pelo tipo de projeto).

Este passo a passo ilustra as seguintes tarefas:

• Fornecendo uma interface do usuário (UI) para adicionar controles à planilha.

• Adicionando controles à planilha.

• Removendo controles da planilha.

  Observação

  Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, confira Personalizar o IDE.

Pré-requisitos

Você precisará dos seguintes componentes para concluir este passo a passo:

• Uma edição do Visual Studio que inclui o Microsoft Office Developer Tools. Para obter mais informações, consulte Configurar um computador para desenvolver soluções do Office.

• Excel

Criar um novo projeto de suplemento VSTO do Excel

Comece criando um projeto de suplemento VSTO do Excel.

Para criar um novo projeto de suplemento VSTO do Excel

1. No Visual Studio, crie um projeto de suplemento VSTO do Excel com o nome ExcelDynamicControls. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

2. Adicione uma referência ao assembly Microsoft.Office.Tools.Excel.v4.0.Utilities.dll Essa referência é necessária para adicionar programaticamente um controle do Windows Forms a uma planilha posteriormente nesta explicação passo a passo.

Fornecer uma interface do usuário para adicionar controles a uma planilha

Adicione uma guia personalizada à Faixa de Opções do Excel. Os usuários podem marcar caixas de seleção na guia para adicionar controles a uma planilha.

Para fornecer uma interface do usuário para adicionar controles a uma planilha

1. No menu Projeto , clique em Adicionar Novo Item.

2. Na caixa de diálogo Adicionar Novo Item, selecione Faixa de Opções (Visual Designer) e clique em Adicionar.

   Um arquivo chamado Faixa de Opções.cs ou Faixa de Opções1.vb é aberto no Designer da Faixa de Opções e exibe uma guia e um grupo padrão.

3. Na guia Controles da Faixa de Opções do Office da Caixa de Ferramentas, arraste um controle CheckBox para group1.

4. Clique em CheckBox1 para selecioná-lo.

5. Na janela Propriedades, altere as seguintes propriedades.

   Propriedade	Valor
   Nome	Botão
   Rótulo	Botão

6. Adicione uma segunda caixa de seleção ao group1 e altere as propriedades a seguir.

   Propriedade	Valor
   Nome	NomedRange
   Rótulo	NomedRange

7. Adicione uma terceira caixa de seleção ao group1 e altere as propriedades a seguir.

   Propriedade	Valor
   Nome	ListObject
   Rótulo	ListObject

Adicionar controles à planilha

Os controles gerenciados só podem ser adicionados a itens do host, que atuam como contêineres. Como os projetos do Suplemento VSTO funcionam com qualquer pasta de trabalho aberta, o Suplemento VSTO converte a planilha em um item de host ou obtém um item de host existente, antes de adicionar o controle. Adicione código aos manipuladores de eventos click de cada controle para gerar um Worksheet item de host baseado na planilha aberta. Em seguida, adicione um Button, a e a ListObject NamedRangena seleção atual na planilha.

Para adicionar controles a uma planilha

1. No Designer da Faixa de Opções, clique duas vezes em Botão.

   O Click manipulador de eventos da caixa de seleção Button é aberto no Editor de Códigos.

2. Substitua o Button_Click manipulador de eventos pelo código a seguir.

   Esse código usa o GetVstoObject método para obter um item de host que representa a primeira planilha na pasta de trabalho e, em seguida, adiciona um Button controle à célula selecionada no momento.

   C#

   private void Button_Click(object sender, RibbonControlEventArgs e)
   {
       Worksheet worksheet = Globals.Factory.GetVstoObject(
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets[1]);
   
       
       string buttonName = "MyButton";
   
       if (((RibbonCheckBox)sender).Checked)
       {
           Excel.Range selection = Globals.ThisAddIn.Application.Selection as Excel.Range;
           if (selection != null)
           {
               Microsoft.Office.Tools.Excel.Controls.Button button =
                   new Microsoft.Office.Tools.Excel.Controls.Button();
               worksheet.Controls.AddControl(button, selection, buttonName);
           }
       }
       else
       {
           worksheet.Controls.Remove(buttonName);
       }
   }
   

   VB

   Private Sub Button_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles Button.Click
   
       Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets(1)
   
       Dim worksheet As Microsoft.Office.Tools.Excel.Worksheet =
           Globals.Factory.GetVstoObject(NativeWorksheet)
   
   
       Dim buttonName As String = "MyButton"
   
       If CType(sender, RibbonCheckBox).Checked Then
           Dim selection As Excel.Range = Globals.ThisAddIn.Application.Selection
           If Not (selection Is Nothing) Then
               Dim button As New Microsoft.Office.Tools.Excel.Controls.Button()
               worksheet.Controls.AddControl(button, selection, buttonName)
           End If
       Else
           worksheet.Controls.Remove(buttonName)
       End If
   End Sub
   

3. No Gerenciador de Soluções, selecione Faixa de Opções1.cs ou Faixa de Opções1.vb.

4. No menu Exibir, clique em Designer.

5. No Designer da Faixa de Opções, clique duas vezes em NamedRange.

6. Substitua o NamedRange_Click manipulador de eventos pelo código a seguir.

   Esse código usa o GetVstoObject método para obter um item de host que representa a primeira planilha na pasta de trabalho e, em seguida, define um NamedRange controle para a célula ou células selecionadas no momento.

   C#

   private void NamedRange_Click(object sender, RibbonControlEventArgs e)
   {
       Worksheet worksheet = Globals.Factory.GetVstoObject(
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets[1]);
   
   
       string Name = "MyNamedRange";
   
       if (((RibbonCheckBox)sender).Checked)
       {
           Excel.Range selection = Globals.ThisAddIn.Application.Selection as Excel.Range;
           if (selection != null)
           {
               worksheet.Controls.AddNamedRange(selection, Name);
           }
       }
       else
       {
           worksheet.Controls.Remove(Name);
       }
   }
   

   VB

   Private Sub NamedRange_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles NamedRange.Click
   
       Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets(1)
   
       Dim worksheet As Microsoft.Office.Tools.Excel.Worksheet =
           Globals.Factory.GetVstoObject(NativeWorksheet)
   
       Dim rangeName As String = "MyNamedRange"
   
       If CType(sender, RibbonCheckBox).Checked Then
           Dim selection As Excel.Range = Globals.ThisAddIn.Application.Selection
           If Not (selection Is Nothing) Then
               Dim namedRange As NamedRange = _
                   worksheet.Controls.AddNamedRange(selection, rangeName)
           End If
       Else
           worksheet.Controls.Remove(rangeName)
       End If
   End Sub
   

7. No Designer da Faixa de Opções, clique duas vezes em ListObject.

8. Substitua o ListObject_Click manipulador de eventos pelo código a seguir.

   Esse código usa o GetVstoObject método para obter um item de host que representa a primeira planilha na pasta de trabalho e, em seguida, define um ListObject para a célula ou células selecionadas no momento.

   C#

   private void ListObject_Click(object sender, RibbonControlEventArgs e)
   {
       Worksheet worksheet = Globals.Factory.GetVstoObject(
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets[1]);
   
   
       string listObjectName = "MyListObject";
   
       if (((RibbonCheckBox)sender).Checked)
       {
           Excel.Range selection = Globals.ThisAddIn.Application.Selection as Excel.Range;
           if (selection != null)
           {
               worksheet.Controls.AddListObject(selection, listObjectName);
           }
       }
       else
       {
           worksheet.Controls.Remove(listObjectName);
       }
   }
   

   VB

   Private Sub ListObject_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles ListObject.Click
   
       Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
           Globals.ThisAddIn.Application.ActiveWorkbook.Worksheets(1)
   
       Dim worksheet As Microsoft.Office.Tools.Excel.Worksheet =
           Globals.Factory.GetVstoObject(NativeWorksheet)
   
   
       Dim listObjectName As String = "MyListObject"
   
       If CType(sender, RibbonCheckBox).Checked Then
           Dim selection As Excel.Range = _
               Globals.ThisAddIn.Application.Selection
           If Not (selection Is Nothing) Then
               worksheet.Controls.AddListObject(selection, listObjectName)
           End If
       Else
           worksheet.Controls.Remove(listObjectName)
       End If
   End Sub
   

9. Adicione as instruções a seguir à parte superior do arquivo de código da Faixa de Opções.

   C#

   using Excel = Microsoft.Office.Interop.Excel;
   using Microsoft.Office.Tools.Excel;
   using Microsoft.Office.Tools.Excel.Extensions;
   

   VB

   Imports Excel = Microsoft.Office.Interop.Excel
   Imports Microsoft.Office.Tools.Excel
   Imports Microsoft.Office.Tools.Excel.Extensions
   

Remover controles da planilha

Os controles não são persistentes quando a planilha é salva e fechada. Você deve remover programaticamente todos os controles gerados do Windows Forms antes que a planilha seja salva ou somente uma estrutura de tópicos do controle aparecerá quando a pasta de trabalho for aberta novamente. Adicione código ao WorkbookBeforeSave evento que remove controles do Windows Forms da coleção de controles do item de host gerado. Para obter mais informações, consulte Persistir controles dinâmicos em documentos do Office.

Para remover controles da planilha

1. No Gerenciador de Soluções, selecione ThisAddIn.cs ou ThisAddIn.vb.

2. No menu Exibir , clique em Código.

3. Adicione o método a seguir à classe ThisAddIn. Esse código obtém a primeira planilha na pasta de trabalho e, em seguida, usa o HasVstoObject método para verificar se a planilha tem um objeto de planilha gerado. Se o objeto de planilha gerado tiver controles, o código obterá esse objeto de planilha e iterará pela coleção de controle, removendo os controles.

   C#

          void Application_WorkbookBeforeSave(Microsoft.Office.Interop.Excel.Workbook workbook, 
              bool SaveAsUI, ref bool Cancel)
          {
              Excel.Worksheet worksheet =
                  workbook.Worksheets[1] as Excel.Worksheet;
              
              if (Globals.Factory.HasVstoObject(worksheet) && 
                  Globals.Factory.GetVstoObject(worksheet).Controls.Count > 0)
              {
                  Worksheet vstoWorksheet = Globals.Factory.GetVstoObject(worksheet);
              
             
                  
                  while (vstoWorksheet.Controls.Count > 0)
                  {
                      object vstoControl = vstoWorksheet.Controls[0];
                      vstoWorksheet.Controls.Remove(vstoControl);
                  }
   
              }
          }
   

   VB

   Sub Application_WorkbookBeforeSave _
       (ByVal workbook As Microsoft.Office.Interop.Excel.Workbook, _
        ByVal SaveAsUI As Boolean, ByRef Cancel As Boolean) _
        Handles Application.WorkbookBeforeSave
   
       Dim worksheet As Excel.Worksheet = workbook.Worksheets(1)
   
       If Globals.Factory.HasVstoObject(worksheet) And
           Globals.Factory.GetVstoObject(worksheet).Controls.Count > 0 Then
           Dim vstoWorksheet As Worksheet = Globals.Factory.GetVstoObject(worksheet)
   
           While vstoWorksheet.Controls.Count > 0
               Dim vstoControl As Object = vstoWorksheet.Controls(0)
               vstoWorksheet.Controls.Remove(vstoControl)
           End While
       End If
   End Sub
   

4. No C#, você deve criar um manipulador de eventos para o WorkbookBeforeSave evento. Você pode colocar esse código no ThisAddIn_Startup método. Para obter mais informações sobre como criar manipuladores de eventos, consulte Como: Criar manipuladores de eventos em projetos do Office. Substitua o método ThisAddIn_Startup pelo seguinte código.

   private void ThisAddIn_Startup(object sender, System.EventArgs e)
   {
       this.Application.WorkbookBeforeSave += 
           new Microsoft.Office.Interop.Excel.AppEvents_WorkbookBeforeSaveEventHandler
               (Application_WorkbookBeforeSave);
   }
   

Testar a solução

Adicione controles a uma planilha selecionando-os em uma guia personalizada na faixa de opções. Quando você salva a planilha, esses controles são removidos.

Para testar a solução.

1. Pressione F5 para executar o projeto.

2. Selecione qualquer célula em Sheet1.

3. Clique na guia Suplementos .

4. No grupo group1, clique em Botão.

   Um botão aparece na célula selecionada.

5. Selecione uma célula diferente em Sheet1.

6. No grupo group1, clique em NamedRange.

   Um intervalo nomeado é definido para a célula selecionada.

7. Selecione uma série de células em Sheet1.

8. No grupo group1, clique em ListObject.

   Um objeto de lista é adicionado para as células selecionadas.

9. Salve a planilha.

   Os controles que você adicionou a Sheet1 não aparecem mais.

Próximas etapas

Você pode saber mais sobre controles em projetos de suplemento VSTO do Excel neste tópico:

• Para saber mais sobre como salvar controles em uma planilha, consulte o Exemplo de controles dinâmicos do suplemento VSTO do Excel em Exemplos de desenvolvimento e instruções passo a passo do Office.

Conteúdo relacionado

• Soluções Excel
• Visão geral dos controles de formulários do Windows em documentos do Office
• Controlos de documentos do Office
• Controle NamedRange
• ListObject controle