Demonstra Passo a passo: atualizar os controles em uma faixa de opções em tempo de execução

Artigo
10/10/2023

Este passo a passo demonstra como usar o modelo de objeto da Faixa de Opções para atualizar os controles em uma faixa de opções depois que a faixa de opções é carregada no aplicativo 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 os seguintes aplicativos: Excel; InfoPath 2013 e InfoPath 2010; Perspectiva; PowerPoint; Projeto; Visio; Palavra. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

O exemplo extrai dados do banco de dados de exemplo Northwind para preencher uma caixa de combinação e um menu no Microsoft Office Outlook. Os itens selecionados nesses controles preenchem automaticamente campos como Para e Assunto em uma mensagem de email.

Este passo a passo ilustra as seguintes tarefas:

Crie um novo projeto de suplemento VSTO do Outlook.
Crie um grupo personalizado da Faixa de Opções.
Adicione o grupo personalizado a uma guia interna.
Atualize os controles na faixa de opções em tempo de execução.

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 do Visual Studio.

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.
Microsoft Outlook

Criar um novo projeto de suplemento VSTO do Outlook

Primeiro, crie um projeto de suplemento VSTO do Outlook.

Para criar um novo projeto de suplemento VSTO do Outlook

No Visual Studio, crie um projeto de suplemento VSTO do Outlook com o nome Ribbon_Update_At_Runtime.
Na caixa de diálogo Novo Projeto, selecione Criar diretório para solução.
Salve o projeto no diretório de projeto padrão.

Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

Criar um grupo de Faixa de Opções personalizado

A faixa de opções deste exemplo aparecerá quando um usuário redigir uma nova mensagem de email. Para criar um grupo personalizado para a faixa de opções, primeiro adicione um item da Faixa de Opções ao seu projeto e, em seguida, crie o grupo no Designer da Faixa de Opções. Esse grupo personalizado ajudará você a gerar mensagens de email de acompanhamento para os clientes extraindo nomes e históricos de pedidos de um banco de dados.

Para criar um grupo personalizado

No menu Projeto , clique em Adicionar Novo Item.
Na caixa de diálogo Adicionar Novo Item, selecione Faixa de Opções (Visual Designer).
Altere o nome da nova Faixa de Opções para CustomerRibbon e clique em Adicionar.

O arquivo CustomerRibbon.cs ou CustomerRibbon.vb é aberto no Designer da Faixa de Opções e exibe uma guia e um grupo padrão.
Clique no Designer da Faixa de Opções para selecioná-lo.
Na janela Propriedades, clique na seta suspensa ao lado da propriedade RibbonType e clique em Microsoft.Outlook.Mail.Compose.

Isso permite que a faixa de opções apareça quando o usuário compõe uma nova mensagem de email no Outlook.
No Designer da Faixa de Opções, clique em Grupo1 para selecioná-lo.
Na janela Propriedades, defina Rótulo como Compras do cliente.
Na guia Controles da Faixa de Opções do Office da Caixa de Ferramentas, arraste uma ComboBox para o grupo Compras do Cliente.
Clique em ComboBox1 para selecioná-lo.
Na janela Propriedades, defina Rótulo como Clientes.
Na guia Controles da Faixa de Opções do Office da Caixa de Ferramentas, arraste um Menu para o grupo Compras do Cliente.
Na janela Propriedades, defina Rótulo como Produto Adquirido.
Defina Dinâmico como true.

Isso permite que você adicione e remova controles no menu em tempo de execução depois que a faixa de opções é carregada no aplicativo do Office.

Adicionar o grupo personalizado a uma guia interna

Uma guia interna é uma guia que já está na faixa de opções de um Outlook Explorer ou Inspector. Neste procedimento, você adicionará o grupo personalizado a uma guia interna e especificará a posição do grupo personalizado na guia.

Para adicionar o grupo personalizado a uma guia interna

Clique na guia TabAddins (Built-In) para selecioná-lo.
Na janela Propriedades, expanda a propriedade ControlId e defina OfficeId como TabNewMailMessage.

Isso adiciona o grupo Compras do Cliente à guia Mensagens da faixa de opções que aparece em uma nova mensagem de email.
Clique no grupo Compras do cliente para selecioná-lo.
Na janela Propriedades, expanda a propriedade Position, clique na seta suspensa ao lado da propriedade PositionType e clique em BeforeOfficeId.
Defina a propriedade OfficeId como GroupClipboard.

Isso posiciona o grupo Compras do Cliente antes do grupo Área de Transferência da guia Mensagens.

Criar a fonte de dados

Use a janela Fontes de Dados para adicionar um conjunto de dados digitado ao seu projeto.

Para criar a fonte de dados

No menu Dados, clique em Adicionar Nova Fonte de Dados.

Isso inicia o Assistente de Configuração da Fonte de Dados.
Selecione Banco de Dados e clique em Avançar.
Selecione Conjunto de Dados e clique em Avançar.
Selecione uma conexão de dados com o banco de dados de exemplo Northwind do Microsoft SQL Server Compact 4.0 ou adicione uma nova conexão usando o botão Nova Conexão .
Depois que uma conexão for selecionada ou criada, clique em Avançar.
Clique em Avançar para salvar a cadeia de conexão.
Na página Escolher Objetos de Banco de Dados , expanda Tabelas.
Marque a caixa de seleção ao lado de cada uma das tabelas a seguir:
1. Customers
2. Detalhes do pedido
3. Pedidos
4. Produtos
Clique em Concluir.

Atualizar controles no grupo personalizado em tempo de execução

Use o modelo de objeto da Faixa de Opções para executar as seguintes tarefas:

Adicione nomes de clientes à caixa de combinação Clientes .
Adicione controles de menu e botão ao menu Produtos comprados que representam ordens de venda e produtos vendidos.
Preencha os campos Para, Assunto e Corpo das novas mensagens de email usando dados da caixa de combinação Clientes e do menu Produtos Comprados.

Para atualizar controles no grupo personalizado usando o modelo de objeto da Faixa de Opções

No menu Projeto, clique em Adicionar Referência.
Na caixa de diálogo Adicionar Referência, clique na guia .NET, selecione o assembly System.Data.Linq e clique em OK.

Este assembly contém classes para usar consultas integradas à linguagem (LINQ). Você usará o LINQ para preencher controles no grupo personalizado com dados do banco de dados Northwind.
No Gerenciador de Soluções, clique em CustomerRibbon.cs ou CustomerRibbon.vb para selecioná-lo.
No menu Exibir , clique em Código.

O arquivo de código da Faixa de Opções é aberto no Editor de Códigos.

Adicione as instruções a seguir à parte superior do arquivo de código da Faixa de Opções. Essas instruções fornecem acesso fácil aos namespaces LINQ e ao namespace do PIA (assembly de interoperabilidade primária) do Outlook.

using System.Data.Linq;
using System.Data.Linq.Mapping;
using System.Linq.Expressions;
using Outlook = Microsoft.Office.Interop.Outlook;
using System.Data;
using System.IO;
using Ribbon_Update_At_Runtime.Northwind40DataSetTableAdapters;

Imports System.Data.Linq
Imports System.Linq
Imports System.Data.Linq.Mapping
Imports System.Linq.Expressions
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Ribbon_Update_At_Runtime.Northwind40DataSetTableAdapters

Adicione o seguinte código dentro da CustomerRibbon classe. Esse código declara a tabela de dados e os adaptadores de tabela que você usará para armazenar informações das tabelas Cliente, Pedidos, Detalhes do Pedido e Produto do banco de dados Northwind.

//Declare the Northwind dataset.
Northwind40DataSet nwDataSet = new Northwind40DataSet();

//Declare the data tables.

Northwind40DataSet.CustomersDataTable customerTable;
Northwind40DataSet.OrdersDataTable orderTable;
Northwind40DataSet.Order_DetailsDataTable orderDetailsTable;
Northwind40DataSet.ProductsDataTable productsTable;

//Declare the data table adapters for each table.

CustomersTableAdapter customerTableAdapter = new CustomersTableAdapter();
OrdersTableAdapter ordersTableAdapter = new OrdersTableAdapter();
Order_DetailsTableAdapter detailsTableAdapter = new Order_DetailsTableAdapter();
ProductsTableAdapter productsTableAdapter = new ProductsTableAdapter();

'Declare the Northwind data set.

Dim nwDataSet As Northwind40DataSet = New Northwind40DataSet()

'Declare the data tables.

Dim customerTable As Northwind40DataSet.CustomersDataTable
Dim orderTable As Northwind40DataSet.OrdersDataTable
Dim orderDetailsTable As Northwind40DataSet.Order_DetailsDataTable
Dim productsTable As Northwind40DataSet.ProductsDataTable

'Declare the data table adapters for each table.

Dim customersTableAdapter As CustomersTableAdapter = New CustomersTableAdapter()
Dim ordersTableAdapter As OrdersTableAdapter = New OrdersTableAdapter()
Dim detailsTableAdapter As Order_DetailsTableAdapter = New Order_DetailsTableAdapter()
Dim productsTableAdapter As ProductsTableAdapter = New ProductsTableAdapter()

Adicione o seguinte bloco de código à CustomerRibbon classe. Esse código adiciona três métodos auxiliares que criam controles para a faixa de opções em tempo de execução.

private RibbonDropDownItem CreateRibbonDropDownItem()
{
    return this.Factory.CreateRibbonDropDownItem();
}
private RibbonMenu CreateRibbonMenu()
{
    return this.Factory.CreateRibbonMenu();
}
private RibbonButton CreateRibbonButton()
{
    RibbonButton button = this.Factory.CreateRibbonButton();
    button.Click += new RibbonControlEventHandler(button_Click);
    return button;
}


Private Function CreateRibbonDropDownItem() As RibbonDropDownItem
    Return Me.Factory.CreateRibbonDropDownItem()
End Function

Private Function CreateRibbonMenu() As RibbonMenu
    Return Me.Factory.CreateRibbonMenu()
End Function

Private Function CreateRibbonButton() As RibbonButton
    Dim button As RibbonButton = Me.Factory.CreateRibbonButton()
    AddHandler (button.Click), AddressOf Button_Click
    Return button
End Function

Substitua o método do CustomerRibbon_Load manipulador de eventos pelo código a seguir. Esse código usa uma consulta LINQ para executar as seguintes tarefas:

Preencha a caixa de combinação Clientes usando a ID e o nome de 20 clientes no banco de dados Northwind.

Chama o PopulateSalesOrderInfo método auxiliar. Esse método atualiza o menu ProductsPurchased com números de ordem de venda que pertencem ao cliente selecionado no momento.

private void CustomerRibbon_Load(object sender, RibbonUIEventArgs e)
{
    customerTable = nwDataSet.Customers;
    customerTableAdapter.Fill(customerTable);

    var customerQuery = from customers in customerTable.AsEnumerable().Take(20)
                        select new
                        {
                            CustomerID = customers.Field<string>("Customer ID"),
                            CustomerName = customers.Field<string>("Contact Name")
                        };


    // Execute the query.
    foreach (var item in customerQuery)
    {
        this.comboBox1.Items.Add(CreateRibbonDropDownItem());
        this.comboBox1.Items.Last().Label =
        item.CustomerName + "|" + item.CustomerID.ToString();
    }
    this.comboBox1.Text = this.comboBox1.Items.First().Label;
    PopulateSalesOrderInfo();
}

 Private Sub CustomerRibbon_Load(ByVal sender As System.Object, _
ByVal e As Microsoft.Office.Tools.Ribbon.RibbonUIEventArgs) _
    Handles MyBase.Load

     customerTable = nwDataSet.Customers
     customersTableAdapter.Fill(customerTable)

     Dim customerQuery = From customers In customerTable.AsEnumerable.Take(20) _
             Select CustomerID = customers.Customer_ID, _
             CustomerName = customers.Contact_Name

     ' Execute the query.
     For Each item In customerQuery
         Me.ComboBox1.Items.Add(CreateRibbonDropDownItem())

         Me.ComboBox1.Items.Last().Label = item.CustomerID.ToString() _
             + "|" + item.CustomerName
     Next item

     Me.ComboBox1.Text = Me.ComboBox1.Items.First().Label
     PopulateSalesOrderInfo()
 End Sub

Adicione o código a seguir à classe CustomerRibbon . Esse código usa consultas LINQ para executar as seguintes tarefas:

Adiciona um submenu ao menu ProdutosComprados para cada ordem de venda relacionada ao cliente selecionado.
Adiciona botões a cada submenu para os produtos relacionados à ordem do cliente.

Adiciona manipuladores de eventos a cada botão.

private void PopulateSalesOrderInfo()
{
    String[] tempArray = comboBox1.Text.Split(new Char[] { '|' });
    menu1.Items.Clear();

    orderTable = nwDataSet.Orders;
    orderDetailsTable = nwDataSet.Order_Details;
    productsTable = nwDataSet.Products;

    ordersTableAdapter.Fill(orderTable);
    detailsTableAdapter.Fill(orderDetailsTable);
    productsTableAdapter.Fill(productsTable);

    var orderQuery = from orders in orderTable.AsEnumerable()
                     where orders.Field<string>("Customer ID") == tempArray[1]
                     select new { OrderID = orders.Field<int>("Order ID") };

    foreach (var orderItem in orderQuery)
    {
        menu1.Items.Add(CreateRibbonMenu());

        RibbonMenu orderMenu = (RibbonMenu)menu1.Items.Last();
        orderMenu.Dynamic = true;
        orderMenu.Label = orderItem.OrderID.ToString();
        orderMenu.Tag = orderItem.OrderID;

        var productQuery = from orderDetail in orderDetailsTable.AsEnumerable()
                           join product in productsTable.AsEnumerable() on
                               orderDetail.Field<int>("Product ID")
                           equals product.Field<int>("Product ID")
                           where orderDetail.Field<int>("Order ID") ==
                               orderItem.OrderID
                           select new { ProductName = product.Field<string>("Product Name") };

        foreach (var productItem in productQuery)
        {
            RibbonButton button = CreateRibbonButton();
            button.Label = productItem.ProductName;
            orderMenu.Items.Add(button);
        }
    }
}

Private Sub PopulateSalesOrderInfo()

    Dim tempArray As [String]() = comboBox1.Text.Split(New [Char]() {"|"c})
    Menu1.Items.Clear()

    orderTable = nwDataSet.Orders
    orderDetailsTable = nwDataSet.Order_Details
    productsTable = nwDataSet.Products

    ordersTableAdapter.Fill(orderTable)
    detailsTableAdapter.Fill(orderDetailsTable)
    productsTableAdapter.Fill(productsTable)

    Dim orderQuery = From order In orderTable.AsEnumerable() _
                     Where order.Customer_ID.ToString() = tempArray(0) _
                     Select New With {.SalesOrderID = order.Order_ID}

    For Each orderItem In orderQuery
        Me.Menu1.Items.Add(CreateRibbonMenu())

        Dim orderMenu As RibbonMenu = CType(Menu1.Items.Last(), RibbonMenu)
        orderMenu.Dynamic = True
        orderMenu.Label = orderItem.SalesOrderID.ToString()
        orderMenu.Tag = orderItem.SalesOrderID

        Dim productQuery = From orderDetail In orderDetailsTable.AsEnumerable(), _
                               product In productsTable.AsEnumerable() _
                           Where orderDetail.Product_ID = _
                               product.Product_ID _
                           And orderDetail.Order_ID = _
                           orderMenu.Tag _
        Select productName = product.Product_Name

        For Each productItem In productQuery
            Dim button As RibbonButton = CreateRibbonButton()
            button.Label = productItem
            orderMenu.Items.Add(button)
        Next productItem
    Next orderItem
End Sub

No Gerenciador de Soluções, clique duas vezes no arquivo de código da Faixa de Opções.

O Designer da Faixa de Opções é aberto.
No Designer da Faixa de Opções, clique duas vezes na caixa de combinação Clientes .

O arquivo de código da Faixa de Opções é aberto no Editor de Códigos e o ComboBox1_TextChanged manipulador de eventos é exibido.
Substitua o ComboBox1_TextChanged manipulador de eventos pelo código a seguir. Esse código executa as seguintes tarefas:
- Chama o PopulateSalesOrderInfo método auxiliar. Esse método atualiza o menu Produtos comprados com ordens de venda relacionadas ao cliente selecionado.
- Chama o método auxiliar e passa o texto atual, que é o PopulateMailItem nome do cliente selecionado. Esse método preenche os campos Para, Assunto e Corpo de novas mensagens de email.
  - C#
  - VB
```
private void comboBox1_TextChanged(object sender,
    RibbonControlEventArgs e)
{
    PopulateSalesOrderInfo();
    PopulateMailItem(comboBox1.Text);
}
```
```
Private Sub ComboBox1_TextChanged(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
        Handles ComboBox1.TextChanged
    PopulateSalesOrderInfo()
    PopulateMailItem(ComboBox1.Text)
End Sub
```

Adicione o seguinte Click manipulador de eventos à CustomerRibbon classe. Esse código adiciona o nome dos produtos selecionados ao campo Corpo das novas mensagens de email.

void button_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;
    RibbonButton myCheckBox = (RibbonButton)sender;
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = myMailItem.Body + "\n" + "* " + myCheckBox.Label;
}

Private Sub Button_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs)
    Dim application As Outlook.Application = Globals.ThisAddIn.Application
    Dim inspector As Outlook.Inspector = application.ActiveInspector()
    Dim myMailItem As Outlook.MailItem = CType(inspector.CurrentItem,  _
        Outlook.MailItem)
    Dim myButton As RibbonButton = CType(sender, RibbonButton)
    myMailItem.Subject = "Following up on your order"
    myMailItem.Body = myMailItem.Body + ControlChars.Lf + "* " _
        + myButton.Label
End Sub

Adicione o código a seguir à classe CustomerRibbon . Esse código executa as seguintes tarefas:

Preenche a linha Para de novas mensagens de email usando o endereço de email do cliente selecionado no momento.

Adiciona texto aos campos Assunto e Corpo de novas mensagens de email.

private void PopulateMailItem(string addressToLine)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;

    myMailItem.To = "";
    String[] tempArray = addressToLine.Split(new Char[] { '|' });
    myMailItem.To = tempArray[0] + "@example.com";
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = "Hello " + tempArray[0] + "," +
        "\n" + "We would like to get your feedback on the " +
        "following products that you recently ordered: ";
}

Private Sub PopulateMailItem(ByVal addressToLine As String)
    Dim application As Outlook.Application = Globals.ThisAddIn.Application
    Dim inspector As Outlook.Inspector = application.ActiveInspector()
    Dim myMailItem As Outlook.MailItem = _
        CType(inspector.CurrentItem, Outlook.MailItem)

    myMailItem.To = ""
    Dim tempArray As [String]() = addressToLine.Split(New [Char]() {"|"c})
    myMailItem.To = tempArray(1) + "@example.com"
    myMailItem.Subject = "Following up on your order"
    myMailItem.Body = "Hello " + tempArray(1) + "," _
        + ControlChars.Lf + "We would like to get your feedback" + _
        "on the following products that you recently ordered: "
End Sub

Testar os controles no grupo personalizado

Quando você abre um novo formulário de email no Outlook, um grupo personalizado chamado Compras do Cliente aparece na guia Mensagens da Faixa de Opções.

Para criar uma mensagem de email de acompanhamento do cliente, selecione um cliente e, em seguida, selecione os produtos comprados pelo cliente. Os controles no grupo Compras do cliente são atualizados em tempo de execução com dados do banco de dados Northwind.

Para testar os controles no grupo personalizado

Pressione F5 para executar o projeto.

O Outlook é iniciado.
No Outlook, no menu arquivo , aponte para novo e, em seguida, clique em mensagem de email .

As seguintes ações ocorrem:
- Uma nova janela do Inspetor de mensagens de email é exibida.
- Na guia Mensagem da faixa de opções, o grupo Compras do Cliente aparece antes do grupo Área de Transferência.
- A caixa de combinação Clientes no grupo é atualizada com os nomes dos clientes no banco de dados Northwind.
Na guia Mensagem da faixa de opções, no grupo Compras do Cliente, selecione um cliente na caixa de combinação Clientes.

As seguintes ações ocorrem:
- O menu Produtos comprados é atualizado para mostrar cada ordem de venda para o cliente selecionado.
- Cada submenu da ordem do cliente é atualizado para mostrar os produtos comprados nessa ordem.
- O endereço de email do cliente selecionado é adicionado à linha Para da mensagem de email, e o assunto e o corpo da mensagem de email são preenchidos com texto.
Clique no menu Compras de Produtos, aponte para qualquer ordem de venda e clique em um produto da ordem de venda.

O nome do produto é adicionado ao corpo da mensagem de email.

Próximas etapas

Você pode saber mais sobre como personalizar a interface do usuário do Office a partir destes tópicos:

Adicione a interface do usuário baseada em contexto a qualquer personalização em nível de documento. Para obter mais informações, consulte Visão geral do painel Ações.
Estender um formulário padrão ou personalizado do Microsoft Office Outlook. Para obter mais informações, consulte Demonstra Passo a passo: Criar uma região de formulário do Outlook.
Adicione um painel de tarefas personalizado ao Outlook. Para obter mais informações, consulte Painéis de tarefas personalizados.

Compartilhar via

Demonstra Passo a passo: atualizar os controles em uma faixa de opções em tempo de execução

Pré-requisitos

Criar um novo projeto de suplemento VSTO do Outlook

Para criar um novo projeto de suplemento VSTO do Outlook

Criar um grupo de Faixa de Opções personalizado

Para criar um grupo personalizado

Adicionar o grupo personalizado a uma guia interna

Para adicionar o grupo personalizado a uma guia interna

Criar a fonte de dados

Para criar a fonte de dados

Atualizar controles no grupo personalizado em tempo de execução

Para atualizar controles no grupo personalizado usando o modelo de objeto da Faixa de Opções

Testar os controles no grupo personalizado

Para testar os controles no grupo personalizado

Próximas etapas

Recursos adicionais

Compartilhar via

Demonstra Passo a passo: atualizar os controles em uma faixa de opções em tempo de execução

Pré-requisitos

Criar um novo projeto de suplemento VSTO do Outlook

Para criar um novo projeto de suplemento VSTO do Outlook

Criar um grupo de Faixa de Opções personalizado

Para criar um grupo personalizado

Adicionar o grupo personalizado a uma guia interna

Para adicionar o grupo personalizado a uma guia interna

Criar a fonte de dados

Para criar a fonte de dados

Atualizar controles no grupo personalizado em tempo de execução

Para atualizar controles no grupo personalizado usando o modelo de objeto da Faixa de Opções

Testar os controles no grupo personalizado

Para testar os controles no grupo personalizado

Próximas etapas

Conteúdo relacionado

Recursos adicionais