Visão geral do modelo de objeto da faixa de opções

O Visual Studio Tools for Office runtime expõe um modelo de objeto fortemente tipado que você pode usar para obter e definir as propriedades de controles da Faixa de Opções em tempo de execução. Por exemplo, você pode preencher dinamicamente controles de menu ou mostrar e ocultar controles contextualmente. Você também pode adicionar guias, grupos e controles a uma faixa de opções, mas somente antes que a faixa de opções seja carregada pelo aplicativo do Office. Para obter informações, consulte Definir propriedades que se tornam somente leitura.

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.

Esse modelo de objeto da Faixa de Opções consiste principalmente nas classes de controle Ribbon, Ribbon e Ribbon.

Classe da faixa de opções

Quando você adiciona um novo item da Faixa de Opções (Visual Designer) a um projeto, o Visual Studio adiciona uma classe da Faixa de Opções ao seu projeto. A classe Ribbon herda da RibbonBase classe.

Essa classe aparece como uma classe parcial que é dividida entre o arquivo de código da Faixa de Opções e o arquivo de código do Designer da Faixa de Opções.

Eventos da faixa de opções

A classe Ribbon contém os três eventos a seguir:

Controles da faixa de opções

O Microsoft.Office.Tools.Ribbon namespace contém um tipo para cada controle que você vê no grupo Controles da Faixa de Opções do Office da Caixa de Ferramentas.

A tabela a seguir mostra o tipo para cada Ribbon controle. Para obter uma descrição de cada controle, consulte Visão geral da faixa de opções.

O Microsoft.Office.Tools.Ribbon namespace usa o prefixo "Ribbon" para esses tipos para evitar uma colisão de nome com os nomes de classes de controle no System.Windows.Forms namespace.

Quando você adiciona um controle ao Designer da Faixa de Opções, o Designer da Faixa de Opções declara a classe desse controle como um campo no arquivo de código do Designer da Faixa de Opções.

Tarefas comuns usando as propriedades dos controles da Faixa de Opções

Cada Ribbon controle contém propriedades que você pode usar para executar várias tarefas, como atribuir um rótulo a um controle ou ocultar e mostrar controles.

Em alguns casos, as propriedades se tornam somente leitura depois que a Faixa de Opções é carregada ou depois que um controle é adicionado a um menu dinâmico. Para obter mais informações, consulte Definir propriedades que se tornam somente leitura.

A tabela a seguir descreve algumas das tarefas que você pode executar usando Ribbon propriedades de controle.

Definir propriedades que se tornam somente leitura

Algumas propriedades só podem ser definidas antes do carregamento da faixa de opções. Há três locais para definir essas propriedades:

• Na janela Propriedades do Visual Studio.

• No construtor da classe Ribbon .

• CreateRibbonExtensibilityObject No método do , ThisWorkbookou ThisDocument classe do ThisAddinseu projeto.

  Os menus dinâmicos fornecem algumas exceções. Você pode criar novos controles, definir suas propriedades e adicioná-los a um menu dinâmico em tempo de execução, mesmo depois que a faixa de opções que contém o menu for carregada.

  As propriedades dos controles que você adiciona a um menu dinâmico podem ser definidas a qualquer momento.

  Para obter mais informações, consulte Propriedades que se tornam somente leitura.

Definir propriedades no construtor da faixa de opções

Você pode definir as propriedades de um Ribbon controle no construtor da classe Ribbon . Esse código deve aparecer após a chamada para o InitializeComponent método. O exemplo a seguir adiciona um novo botão a um grupo se a hora atual for 17:00 Hora do Pacífico (UTC-8) ou posterior.

Adicione o código a seguir.

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

Em projetos do Visual C# que você atualizou do Visual Studio 2008, o construtor aparece no arquivo de código da faixa de opções.

Em projetos do Visual Basic ou em projetos do Visual C# que você criou no Visual Studio 2013, o construtor aparece no arquivo de código do Designer da Faixa de Opções. Esse arquivo é chamado YourRibbonItem. Designer.cs ou YourRibbonItem. Desenhista.vb. Para ver esse arquivo em projetos do Visual Basic, você deve primeiro clicar no botão Mostrar todos os arquivos no Gerenciador de Soluções.

Definir propriedades no método CreateRibbonExtensibilityObject

Você pode definir as propriedades de um Ribbon controle quando você substituir o CreateRibbonExtensibilityObject método na ThisAddinclasse , ThisWorkbookou ThisDocument do seu projeto. Para obter mais informações sobre o método, consulte Visão geral da CreateRibbonExtensibilityObject faixa de opções.

O exemplo a seguir define as CreateRibbonExtensibilityObject propriedades da Faixa de Opções no método da classe de um projeto de pasta de ThisWorkbook trabalho do Excel.

Adicione o código a seguir.

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

Propriedades que se tornam somente leitura

A tabela a seguir mostra propriedades que só podem ser definidas antes do carregamento da faixa de opções.

Definir propriedades para faixas de opções que aparecem em inspetores do Outlook

Uma nova instância da faixa de opções é criada sempre que um usuário abre um Inspetor no qual a faixa de opções aparece. No entanto, você pode definir as propriedades listadas na tabela acima somente antes que a primeira instância da faixa de opções seja criada. Depois que a primeira instância é criada, essas propriedades se tornam somente leitura porque a primeira instância define o arquivo XML que o Outlook usa para carregar a faixa de opções.

Se você tiver uma lógica condicional que defina qualquer uma dessas propriedades como um valor diferente quando outras instâncias da faixa de opções forem criadas, esse código não terá efeito.

Eventos de controle da faixa de opções

Cada classe de controle contém um ou mais eventos. A tabela a seguir descreve esses eventos.

Os manipuladores de eventos para esses eventos têm os dois parâmetros a seguir.

Conteúdo relacionado

• Acessar a faixa de opções em tempo de execução
• Visão geral da faixa de opções
• Como: Começar a personalizar a faixa de opções
• Designer da faixa de opções
• Demonstra Passo a passo: Criar uma guia personalizada usando o Designer da Faixa de Opções
• Demonstra Passo a passo: atualizar os controles em uma faixa de opções em tempo de execução
• Personalizar uma faixa de opções para o Outlook
• Como: Personalizar uma guia interna
• Como adicionar controles ao modo de exibição Backstage
• Como exportar uma faixa de opções do Designer da Faixa de Opções para o XML da Faixa de Opções
• Como: Mostrar erros de interface do usuário do suplemento