Compartilhar via

XML da faixa de opções

  • Artigo

O item Faixa de Opções (XML) permite personalizar uma faixa de opções usando XML. Use o item Faixa de Opções (XML) se desejar personalizar a faixa de opções de uma maneira que não seja suportada pelo item Faixa de Opções (Visual Designer). Para obter uma comparação do que você pode fazer com cada item, consulte Visão geral da faixa de opções.

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.

Adicionar um item da Faixa de Opções (XML) a um projeto

Você pode adicionar um item da Faixa de Opções (XML) a qualquer projeto do Office na caixa de diálogo Adicionar Novo Item . Visual Studio adiciona automaticamente os seguintes arquivos ao seu projeto:

  • Um arquivo XML da Faixa de Opções. Esse arquivo define a interface do usuário (UI) da Faixa de Opções. Use esse arquivo para adicionar elementos da interface do usuário, como guias, grupos e controles. Para obter detalhes, consulte Referência de arquivo XML da faixa de opções mais adiante neste tópico.

  • Um arquivo de código da Faixa de Opções. Esse arquivo contém a classe Ribbon. Essa classe tem o nome que você especificou para o item da Faixa de Opções (XML) na caixa de diálogo Adicionar Novo Item . Os aplicativos do Microsoft Office usam uma instância dessa classe para carregar a faixa de opções personalizada. Para obter detalhes, consulte Referência de classe da faixa de opções mais adiante neste tópico.

    Por padrão, esses arquivos adicionam um grupo personalizado à guia Suplementos na faixa de opções.

Exibir a faixa de opções personalizada em um aplicativo do Microsoft Office

Depois de adicionar um item da Faixa de Opções (XML) ao seu projeto, você deve adicionar código à classe ThisAddin, ThisWorkbook ou ThisDocument que substitui o método e retorna a classe XML da Faixa de Opções para o CreateRibbonExtensibilityObject aplicativo do Office.

O exemplo de código a seguir substitui o CreateRibbonExtensibilityObject método e retorna uma classe XML da Faixa de Opções chamada MyRibbon.

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Definir o comportamento da faixa de opções personalizada

Você pode responder às ações do usuário, como clicar em um botão na faixa de opções, criando métodos de retorno de chamada. Os métodos de retorno de chamada se assemelham a eventos em controles do Windows Forms, mas são identificados por um atributo no XML do elemento da interface do usuário. Você escreve métodos na classe Ribbon e um controle chama o método que tem o mesmo nome que o valor do atributo. Por exemplo, você pode criar um método de retorno de chamada que é chamado quando um usuário clica em um botão na faixa de opções. Duas etapas são necessárias para criar um método de retorno de chamada:

  • Atribua um atributo a um controle no arquivo XML da Faixa de Opções que identifique um método de retorno de chamada em seu código.

  • Defina o método de retorno de chamada na classe Ribbon.

Observação

O Outlook requer uma etapa adicional. Para obter mais informações, consulte Personalizar uma faixa de opções para o Outlook.

Para obter uma explicação passo a passo que demonstra como automatizar um aplicativo da faixa de opções, consulte Demonstra Passo a passo: Criar uma guia personalizada usando XML da Faixa de Opções.

Atribuir métodos de retorno de chamada a controles

Para atribuir um método de retorno de chamada a um controle no arquivo XML da Faixa de Opções, adicione um atributo que especifique o tipo do método de retorno de chamada e o nome do método. Por exemplo, o elemento a seguir define um botão de alternância que tem um método de retorno de chamada onAction chamado OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

onAction é chamado quando o usuário executa a tarefa principal associada a um controle específico. Por exemplo, o método de retorno de chamada onAction de um botão de alternância é chamado quando o usuário clica no botão.

O método especificado no atributo pode ter qualquer nome. No entanto, ele deve corresponder ao nome do método que você define no arquivo de código da Faixa de Opções.

Há muitos tipos diferentes de métodos de retorno de chamada que você pode atribuir aos controles da Faixa de Opções. Para obter uma lista completa dos métodos de retorno de chamada disponíveis para cada controle, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 3 de 3).

Definir métodos de retorno de chamada

Defina seus métodos de retorno de chamada na classe Ribbon no arquivo de código da Faixa de Opções. Um método de retorno de chamada tem vários requisitos:

  • Deve ser declarado público.

  • Seu nome deve corresponder ao nome de um método de retorno de chamada que você atribuiu a um controle no arquivo XML da Faixa de Opções.

  • Sua assinatura deve corresponder à assinatura de um tipo de método de retorno de chamada que está disponível para o controle Ribbon associado.

    Para obter uma lista completa das assinaturas do método de retorno de chamada para controles da Faixa de Opções, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 3 de 3). Visual Studio não fornece suporte IntelliSense para métodos de retorno de chamada que você cria no arquivo de código da faixa de opções. Se você criar um método de retorno de chamada que não corresponde a uma assinatura válida, o código será compilado, mas nada ocorrerá quando o usuário clicar no controle.

    Todos os métodos de retorno de chamada têm um IRibbonControl parâmetro que representa o controle que chamou o método. Você pode usar esse parâmetro para reutilizar o mesmo método de retorno de chamada para vários controles. O exemplo de código a seguir demonstra um método de retorno de chamada onAction que executa tarefas diferentes, dependendo de qual controle o usuário clica.

    public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
{
    if (control.Id == "checkBox1")
    {
        MessageBox.Show("You clicked " + control.Id);
    }
    else
    {
        MessageBox.Show("You clicked a different control.");
    }
}

Referência do arquivo XML da faixa de opções

Você pode definir sua faixa de opções personalizada adicionando elementos e atributos ao arquivo XML da Faixa de Opções. Por padrão, o arquivo XML da Faixa de Opções contém o seguinte XML.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

A tabela a seguir descreve os elementos padrão no arquivo XML da Faixa de Opções.

Element Descrição
interface do usuário personalizada Representa a faixa de opções personalizada no projeto Suplemento VSTO.
fita Representa a faixa de opções.
Guias Representa um conjunto de guias da Faixa de Opções.
tab Representa uma única guia da Faixa de Opções.
grupo Representa um grupo de controles na guia Faixa de Opções.

Esses elementos têm atributos que especificam a aparência e o comportamento da faixa de opções personalizada. A tabela a seguir descreve os atributos padrão no arquivo XML da Faixa de Opções.

Atributo Elemento pai Descrição
onLoad interface do usuário personalizada Identifica um método que é chamado quando o aplicativo carrega a faixa de opções.
idMso tab Identifica uma guia interna a ser exibida na faixa de opções.
id grupo Identifica o grupo.
label grupo Especifica o texto que aparece no grupo.

Os elementos e atributos padrão no arquivo XML da Faixa de Opções são um pequeno subconjunto dos elementos e atributos disponíveis. Para obter uma lista completa dos elementos e atributos disponíveis, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 2 de 3).

Referência de classe da faixa de opções

O Visual Studio gera a classe Ribbon no arquivo de código da Faixa de Opções. Adicione os métodos de retorno de chamada para controles na faixa de opções a essa classe. Essa classe implementa a interface IRibbonExtensibility.

A tabela a seguir descreve os métodos padrão nessa classe.

Método Descrição
GetCustomUI Retorna o conteúdo do arquivo XML da Faixa de Opções. Os aplicativos do Microsoft Office chamam esse método para obter uma cadeia de caracteres XML que define a interface do usuário da faixa de opções personalizada. Este método implementa o método GetCustomUI. Nota:GetCustomUI deve ser implementado apenas para retornar o conteúdo do arquivo XML da Faixa de Opções, ele não deve ser usado para inicializar seu suplemento VSTO. Em particular, você não deve tentar exibir caixas de diálogo ou outras janelas em sua GetCustomUI implementação. Caso contrário, a faixa de opções personalizada pode não se comportar corretamente. Se você precisar executar o código que inicializa o suplemento VSTO, adicione o código ao ThisAddIn_Startup manipulador de eventos.
OnLoad Atribui o IRibbonControl parâmetro ao Ribbon campo. Os aplicativos do Microsoft Office chamam esse método quando carregam a faixa de opções personalizada. Você pode usar esse campo para atualizar dinamicamente a faixa de opções personalizada. Para obter mais informações, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 1 de 3).
GetResourceText Chamado pelo GetCustomUI método para obter o conteúdo do arquivo XML da Faixa de Opções.

Conteúdo relacionado