Compartilhar via

XML da faixa de opções

  • Artigo

O item Faixa de Opções (XML) permite que você personalize uma faixa de opções usando XML. Use o item Faixa de Opções (XML) se quiser personalizar a faixa de opções de uma maneira que não seja compatível com o 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 no nível do documento e projetos do suplemento VSTO para os seguintes aplicativos: Excel, InfoPath 2013 e InfoPath 2010, Outlook, PowerPoint, Project, Visio, Word. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

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

Você pode adicionar um item Faixa de Opções (XML) a qualquer projeto do Office na caixa de diálogo Adicionar Novo Item. O 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 (IU) da Faixa de Opções. Use esse arquivo para adicionar elementos de 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 da Faixa de Opções. Essa classe tem o nome que você especificou para o item 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 Faixa de Opções (XML) ao seu projeto, você deve adicionar código à classe ThisAddin, ThisWorkbook ou ThisDocument que substitui o método CreateRibbonExtensibilityObject e retorna a classe XML da Faixa de Opções para o aplicativo do Office.

O exemplo de código a seguir substitui o método CreateRibbonExtensibilityObject 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 de interface do usuário. Escreva métodos na classe Faixa de Opções para que um controle chame 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 identifica um método de retorno de chamada em seu código.

  • Defina o método de retorno de chamada na classe Faixa de Opções.

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 um passo a passo que demonstra como automatizar um aplicativo da faixa de opções, consulte Passo a passo: criar uma guia personalizada usando o 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 onActionOnToggleButton1.

<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 definido 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 Faixa de Opções no arquivo de código 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 da Faixa de Opções associado.

    Para obter uma lista completa das assinaturas de 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). O Visual Studio não fornece suporte ao 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 corresponda 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 parâmetro IRibbonControl 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 do controle em que 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 de 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 XML a seguir.

<?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
customUI Representa a faixa de opções personalizada no projeto do suplemento VSTO.
faixa de opções 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 customUI 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 Faixa de Opções no arquivo de código 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. Observação: GetCustomUI deve ser implementado apenas para retornar o conteúdo do arquivo XML da Faixa de Opções. Não deve ser usado para inicializar o suplemento VSTO. Em particular, você não deve tentar exibir caixas de diálogo ou outras janelas em sua implementação GetCustomUI. 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 manipulador de eventos ThisAddIn_Startup.
OnLoad Atribui o parâmetro IRibbonControl ao campo Ribbon. 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 método GetCustomUI para obter o conteúdo do arquivo XML da Faixa de Opções.

Conteúdo relacionado