Condividi tramite

Ribbon XML

  • Articolo

L'elemento della barra multifunzione (XML) consente di personalizzare una barra multifunzione tramite XML. Utilizzare l'elemento barra multifunzione (XML) se si desidera personalizzare la barra multifunzione in modo che non sia supportato dall'elemento Barra multifunzione (Progettazione visiva). Per un confronto delle operazioni che è possibile eseguire con ogni elemento, vedere Panoramica della barra multifunzione.

Si applica a: le informazioni contenute in questo argomento si applicano ai progetti a livello di documento e ai progetti di componente aggiuntivo VSTO per le applicazioni seguenti: Excel; InfoPath 2013 e InfoPath 2010; Prospettiva; PowerPoint; Progetto; Visio; Parola. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

Aggiungere un elemento barra multifunzione (XML) a un progetto

È possibile aggiungere un elemento Barra multifunzione (XML) a qualsiasi progetto di Office dalla finestra di dialogo Aggiungi nuovo elemento . Visual Studio aggiunge automaticamente i file seguenti al progetto:

  • Un file XML della barra multifunzione. Questo file definisce l'interfaccia utente della barra multifunzione. Usare questo file per aggiungere elementi dell'interfaccia utente, ad esempio schede, gruppi e controlli. Per informazioni dettagliate, vedere Informazioni di riferimento sui file XML della barra multifunzione più avanti in questo argomento.

  • Un file di codice della barra multifunzione. Questo file contiene la classe Ribbon. Il nome della classe corrisponde a quello specificato per l'elemento Barra multifunzione (XML) nella finestra di dialogo Aggiungi nuovo elemento . Microsoft app Office lications usa un'istanza di questa classe per caricare la barra multifunzione personalizzata. Per informazioni dettagliate, vedere Informazioni di riferimento sulla classe ribbon più avanti in questo argomento.

    Per impostazione predefinita, questi file aggiungono un gruppo personalizzato alla scheda Componenti aggiuntivi nella barra multifunzione.

Visualizzare la barra multifunzione personalizzata in un microsoft app Office lication

Dopo aver aggiunto un elemento della barra multifunzione (XML) al progetto, è necessario aggiungere codice alla classe ThisAddin, ThisWorkbook o ThisDocument che esegue l'override del CreateRibbonExtensibilityObject metodo e restituisce la classe XML della barra multifunzione alla app Office lication.

L'esempio di codice seguente esegue l'override del metodo CreateRibbonExtensibilityObject e restituisce una classe Ribbon XML denominata MyRibbon.

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

Definire il comportamento della barra multifunzione personalizzata

È possibile rispondere alle azioni dell'utente, ad esempio facendo clic su un pulsante sulla barra multifunzione, creando metodi di callback. I metodi di callback sono simili agli eventi nei controlli Windows Form, ma vengono identificati da un attributo nel codice XML dell'elemento dell'interfaccia utente. I metodi vengono scritti nella classe Ribbon e un controllo chiama il metodo con lo stesso nome del valore dell'attributo. Ad esempio, è possibile creare un metodo di callback chiamato quando un utente fa clic su un pulsante sulla barra multifunzione. Per creare un metodo di callback, sono necessari due passaggi:

  • Assegnare un attributo a un controllo nel file XML della barra multifunzione che identifica un metodo di callback nel codice.

  • Definire il metodo di callback nella classe Ribbon.

Nota

Outlook richiede un ulteriore passaggio. Per altre informazioni, vedere Personalizzare una barra multifunzione per Outlook.

Per una procedura dettagliata che illustra come automatizzare un'applicazione dalla barra multifunzione, vedere Procedura dettagliata: Creare una scheda personalizzata tramite XML della barra multifunzione.

Assegnare metodi di callback ai controlli

Per assegnare un metodo di callback a un controllo nel file XML della barra multifunzione, aggiungere un attributo che specifica il tipo del metodo di callback e il nome del metodo. Ad esempio, l'elemento seguente definisce un interruttore con un metodo di callback onAction denominato OnToggleButton1.

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

onAction viene chiamato quando l'utente esegue l'attività principale associata a un controllo specifico. Ad esempio, il metodo di callback onAction di un interruttore viene chiamato quanto l'utente fa clic sul pulsante.

Il metodo specificato nell'attributo può avere qualsiasi nome. Tuttavia, deve corrispondere al nome del metodo definito nel file di codice della barra multifunzione.

Ci sono molti tipi diversi di metodi di callback che è possibile assegnare ai controlli della barra multifunzione. Per un elenco completo dei metodi di callback disponibili per ogni controllo, vedere l'articolo tecnico Personalizzare l'interfaccia utente della barra multifunzione di Office (2007) per gli sviluppatori (parte 3 di 3).

Definire i metodi di callback

Definire i metodi di callback nella classe Ribbon nel file di codice della barra multifunzione. Un metodo di callback presenta diversi requisiti:

  • Deve essere dichiarato come pubblico.

  • Il nome deve corrispondere al nome di un metodo di callback assegnato a un controllo nel file XML della barra multifunzione.

  • La firma deve corrispondere alla firma di un tipo di metodo di callback disponibile per il controllo barra multifunzione associato.

    Per un elenco completo delle firme del metodo di callback per i controlli della barra multifunzione, vedere l'articolo tecnico Personalizzare l'interfaccia utente della barra multifunzione di Office (2007) per gli sviluppatori (parte 3 di 3). Visual Studio non fornisce supporto IntelliSense per i metodi di callback creati nel file di codice della barra multifunzione. Se si crea un metodo di callback che non corrisponde a una firma valida, il codice verrà compilato, ma non succederà niente quando l'utente fa clic sul controllo.

    Tutti i metodi di callback hanno un parametro IRibbonControl che rappresenta il controllo che ha chiamato il metodo. È possibile usare questo parametro per riutilizzare lo stesso metodo di callback per più controlli. L'esempio di codice seguente illustra un metodo di callback onAction che esegue attività diverse a seconda del controllo su cui l'utente fa clic.

    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.");
    }
}

Informazioni di riferimento sul file XML della barra multifunzione

È possibile definire la barra multifunzione personalizzata aggiungendo elementi e attributi al file XML della barra multifunzione. Per impostazione predefinita, il file XML della barra multifunzione contiene il codice XML seguente.

<?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>

La tabella seguente descrive gli elementi predefiniti del file XML della barra multifunzione:

Elemento Descrizione
customUI Rappresenta la barra multifunzione personalizzata nel progetto di componente aggiuntivo VSTO.
ribbon Rappresenta la barra multifunzione.
Schede Rappresenta un set di schede della barra multifunzione.
scheda Rappresenta una singola scheda della barra multifunzione.
group Rappresenta un gruppo di controlli nella scheda della barra multifunzione.

Questi elementi hanno attributi che specificano l'aspetto e il comportamento della barra multifunzione personalizzata. La tabella seguente descrive gli attributi predefiniti del file XML della barra multifunzione:

Attributo Elemento padre Descrizione
onLoad customUI Identifica un metodo chiamato quando l'applicazione carica la barra multifunzione.
idMso scheda Identifica una scheda predefinita da visualizzare nella barra multifunzione.
id group Identifica il gruppo.
label group Specifica il testo visualizzato nel gruppo.

Gli elementi e gli attributi predefiniti nel file XML della barra multifunzione sono un piccolo subset degli elementi e degli attributi disponibili. Per un elenco completo degli elementi e degli attributi disponibili, vedere l'articolo tecnico Personalizzare l'interfaccia utente della barra multifunzione di Office (2007) per gli sviluppatori (parte 2 di 3).

Informazioni di riferimento sulla classe della barra multifunzione

Visual Studio genera la classe Ribbon nel file di codice della barra multifunzione. Aggiungere i metodi di callback per i controlli sulla barra multifunzione a questa classe. La classe implementa l'interfaccia IRibbonExtensibility.

La tabella seguente descrive i metodi predefiniti della classe.

metodo Descrizione
GetCustomUI Restituisce il contenuto del file XML della barra multifunzione. Microsoft app Office lications chiama questo metodo per ottenere una stringa XML che definisce l'interfaccia utente della barra multifunzione personalizzata. Questo metodo implementa il metodo GetCustomUI . Nota: GetCustomUI deve essere implementato solo per restituire il contenuto del file XML della barra multifunzione. Non deve essere usato per inizializzare il componente aggiuntivo VSTO. In particolare, non tentare di visualizzare finestre di dialogo o altre finestre nell'implementazione di GetCustomUI . In caso contrario, la barra multifunzione personalizzata potrebbe non comportarsi correttamente. Se è necessario eseguire codice per l'inizializzazione del componente aggiuntivo VSTO, aggiungere il codice al gestore eventi ThisAddIn_Startup .
OnLoad Assegna il parametro IRibbonControl al campo Ribbon . Microsoft app Office lications chiama questo metodo quando caricano la barra multifunzione personalizzata. È possibile usare questo campo per aggiornare dinamicamente la barra multifunzione personalizzata. Per altre informazioni, vedere l'articolo tecnico Personalizzare l'interfaccia utente della barra multifunzione di Office (2007) per gli sviluppatori (parte 1 di 3).
GetResourceText Chiamato dal metodo GetCustomUI per ottenere il contenuto del file XML della barra multifunzione.

Contenuto correlato