XML da faixa de opções

Artigo
08/08/2011

O item de faixa de opções (XML) permite que você personalize uma faixa de opções usando XML. Use o item de faixa de opções (XML), se você quiser personalizar a faixa de opções de forma que não é suportada pelo item da 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.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de nível de aplicativo para os seguintes aplicativos: Excel 2007 e Excel 2010; InfoPath 2010; Outlook 2007 e Outlook 2010; PowerPoint 2007 e PowerPoint 2010; Project 2010; Visio 2010; Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Adicionando um Item de faixa de opções (XML) em um projeto

Você pode adicionar um Da faixa de opções (XML) item a qualquer projeto de Office a partir de Add New Item caixa de diálogo. Visual Studio adiciona automaticamente os seguintes arquivos ao seu projeto:

Um arquivo XML de faixa de opções. Esse arquivo define o Ribbon user interface (UI). Use este arquivo para adicionar elementos de interface do usuário como, por exemplo, guias, grupos e controles. Para obter detalhes, consulte Referência de arquivo XML de faixa de opções posteriormente neste tópico.
Um arquivo de código da faixa de opções. Este arquivo contém o classe Ribbon. Essa classe tem o nome que você especificou para o Da faixa de opções (XML) item no Add New Item caixa de diálogo. Aplicativos de 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 posteriormente neste tópico.

Por padrão, esses arquivos adicionar um grupo personalizado para o Add-Ins guia na faixa de opções.

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

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

O seguinte código exemplo substitui o CreateRibbonExtensibilityObject método e retorna uma classe de XML da faixa de opções denominada MyRibbon.

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

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

Definindo o comportamento da faixa de opções personalizada

Você pode responder a ações do usuário, como, por exemplo, clicando em um botão na faixa de opções, criando métodos de retorno de chamada. Métodos de retorno de chamada semelhantes aos eventos nos controles do Windows Forms, mas são identificadas por um atributo no XML do elemento de interface do usuário. Você escrever métodos na classe da faixa de opções 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 é chamado quando um usuário clica em um botão na faixa de opções. São necessárias duas etapas para criar um método de retorno de chamada:

Atribua um atributo a um controle no arquivo XML de faixa de opções que identifica um método de retorno de chamada no seu código.
Defina o método de retorno de chamada na classe da faixa de opções.

Observação
O Outlook requer uma etapa adicional. For more information, see Personalização para Outlook.

Para uma explicação passo a passo que demonstra como automatizar um aplicativo a partir da faixa de opções, consulte Demonstra Passo a passo: A criação de uma guia personalizado usando o XML da faixa de opções.

A atribuição de métodos de retorno de chamada para controles

Para atribuir um método de retorno de chamada para um controle no arquivo XML de faixa de opções, adicione um atributo que especifica o tipo do método de retorno de chamada e o nome do método. Por exemplo, o seguinte elemento define um botão de alternância que tem um onAction método de retorno de chamada chamado OnToggleButton1.

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

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

O método que você especificar no atributo pode ter qualquer nome. No entanto, ele deve corresponder ao nome do método que você definir 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 de métodos de retorno de chamada disponíveis para cada controle, consulte o artigo técnico a personalização do Office (2007) Ribbon User Interface para desenvolvedores (parte 3 de 3).

Definindo métodos de retorno de chamada

Defina seus métodos de retorno de chamada na classe da faixa de opções no arquivo de código da faixa de opções. Um método de retorno de chamada possui diversos requisitos:

Deve ser declarado como 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 de 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 associado da faixa de opções.

Para obter uma lista completa de assinaturas de método de retorno de chamada para controles da faixa de opções, consulte o artigo técnico a personalização do Office (2007) Ribbon User Interface para desenvolvedores (parte 3 de 3). Visual Studio não oferece suporte de IntelliSense para métodos de retorno de chamada que você criar no arquivo de código da faixa de opções. Se você criar um método de retorno de chamada que não correspondam a uma assinatura válida, o código será compilado, mas nada ocorrerá quando o usuário clica no controle.

Todos os métodos de retorno de chamada têm um Microsoft.Office.Core.IRibbonControl parâmetro que representa o controle que chama 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 onAction método de retorno de chamada que executa diferentes tarefas dependendo de qual controle a cliques do usuário.

Public Sub OnActionCallback(ByVal control As Office.IRibbonControl, _
    ByVal isPressed As Boolean)

    If (control.Id = "checkBox1") Then
        MessageBox.Show("You clicked " + control.Id)
    Else
        MessageBox.Show("You clicked a different control.")
    End If

End Sub

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 de faixa de opções

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

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="https://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 de faixa de opções.

Element	Description
customUI	Representa a faixa de opções personalizada no projeto do suplemento.
ribbon	Representa a faixa de opções.
tabs	Representa um conjunto de guias da faixa de opções.
tab	Representa uma única guia de faixa de opções.
group	Representa um grupo de controles na guia da faixa de opções.

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

Attribute	Elemento pai	Description
onLoad	customUI	Identifica um método que é chamado quando o aplicativo carrega a faixa de opções.
idMso	tab	Identifica uma guia interna para exibir na faixa de opções.
id	group	Identifica o grupo.
label	group	Especifica o texto que aparece no grupo.

Os elementos padrão e os atributos no arquivo XML de faixa de opções são um subconjunto pequeno de elementos e atributos que estão disponíveis. Para obter uma lista completa dos atributos e elementos disponíveis, consulte o artigo técnico a personalização do Office (2007) Ribbon User Interface para desenvolvedores (parte 2 de 3).

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

Visual Studio gera a classe da faixa de opções no arquivo de código da faixa de opções. Adicione os métodos de retorno de chamada para controles da faixa de opções para esta classe. Essa classe implementa o Microsoft.Office.Core.IRibbonExtensibility interface.

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

Method	Description
GetCustomUI	Retorna o conteúdo do arquivo XML de faixa de opções. Os aplicativos de Microsoft Office de chamar esse método para obter uma cadeia XML que define a interface de usuário de sua faixa de opções personalizada. Esse método implementa o IRibbonExtensibility.GetCustomUI(String) método. Observação GetCustomUIdeve ser implementada somente para retornar o conteúdo do arquivo XML de faixa de opções. ele não deve ser usado para inicializar o add-in.Em particular, você não deve tentar exibir caixas de diálogo ou outras janelas do seu GetCustomUI de implementação.Caso contrário, a faixa de opções personalizada pode não funcionar corretamente.Se você tiver executado o código que inicializa o add-in, adicione o código para o ThisAddIn_Startup manipulador de eventos.
OnLoad	Atribui o Microsoft.Office.Core.IRibbonControl parâmetro para o ribbon campo. Aplicativos de Microsoft Office de chamam esse método quando eles 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 a personalização do Office (2007) Ribbon User Interface para desenvolvedores (parte 1 de 3).
GetResourceText	Chamado pelo GetCustomUI método para obter o conteúdo do arquivo XML de faixa de opções.

Consulte também

Tarefas

Demonstra Passo a passo: A criação de uma guia personalizado usando o XML da faixa de opções

Outros recursos

Visão geral da faixa de opções

Personalização de interface do usuário do Office

Compartilhar via