Ribbon XML

  • Artículo

El elemento Cinta de opciones (XML) permite personalizar una cinta mediante XML. Use el elemento Ribbon (XML) si desea personalizar la cinta de opciones de una manera que no sea compatible con el elemento Ribbon (Visual Designer). Para obtener una comparación de lo que puede hacer con cada elemento, consulte Información general de la cinta de opciones.

Se aplica a: La información de este tema se aplica a proyectos de nivel de documento y proyectos de complementos de VSTO para las siguientes aplicaciones: Excel; InfoPath 2013 e InfoPath 2010; Outlook; Powerpoint; Proyecto; Visio; Palabra. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

Agregar un elemento de cinta de opciones (XML) a un proyecto

Puede agregar un elemento Cinta (XML) a cualquier proyecto de Office desde el cuadro de diálogo Agregar nuevo elemento . Visual Studio agrega automáticamente los siguientes archivos al proyecto:

  • Un archivo XML de la cinta de opciones. Este archivo define la interfaz de usuario de la cinta de opciones. Use este archivo para agregar elementos de la interfaz de usuario, como pestañas, grupos y controles. Para obtener más información, consulte Referencia de archivo XML de la cinta más adelante en este tema.

  • Un archivo de código de la cinta de opciones. Este archivo contiene la clase Ribbon. Esta clase tiene el nombre que especificó para el elemento Cinta (XML) en el cuadro de diálogo Agregar nuevo elemento . Microsoft aplicación de Office lications usa una instancia de esta clase para cargar la cinta de opciones personalizada. Para obtener más información, consulte Referencia de clase de cinta más adelante en este tema.

    De forma predeterminada, estos archivos agregan un grupo personalizado a la pestaña Complementos de la cinta de opciones.

Mostrar la cinta de opciones personalizada en una aplicación de Office lication de Microsoft

Después de agregar un elemento de cinta de opciones (XML) al proyecto, debe agregar código a la clase ThisAddin, ThisWorkbook o ThisDocument que invalida el CreateRibbonExtensibilityObject método y devuelve la clase XML ribbon a la aplicación de Office lication.

En el siguiente código de ejemplo se reemplaza el método CreateRibbonExtensibilityObject y devuelve una clase XML Ribbon llamada MyRibbon.

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

Definir el comportamiento de la cinta de opciones personalizada

Puede responder a acciones de usuario, como hacer clic en un botón de la cinta de opciones, creando métodos de devolución de llamada. Los métodos de devolución de llamada son similares a los eventos de los controles de Windows Forms, pero se identifican con un atributo en el código XML del elemento de la interfaz de usuario. Cuando escribe métodos en la clase Ribbon, un control llama al método que tiene el mismo nombre que el valor del atributo. Por ejemplo, puede crear un método de devolución de llamada al que se llama cuando un usuario hace clic en un botón de la cinta de opciones. Es necesario llevar a cabo dos pasos para crear un método de devolución de llamada:

  • Asigne a un control del archivo XML de la cinta de opciones un atributo que identifique un método de devolución de llamada en el código.

  • Defina el método de devolución de llamada en la clase Ribbon.

Nota:

Outlook requiere un paso adicional. Para obtener más información, vea Personalizar una cinta de opciones para Outlook.

Para ver un tutorial que muestra cómo automatizar una aplicación desde la cinta de opciones, consulte Tutorial: Creación de una pestaña personalizada mediante XML de la cinta de opciones.

Asignación de métodos de devolución de llamada a controles

Para asignar un método de devolución de llamada a un control en el archivo XML de la cinta de opciones, agregue un atributo que especifique el tipo del método de devolución de llamada y el nombre del método. Por ejemplo, el siguiente elemento define un botón de alternancia que tiene un método de devolución de llamada onAction llamado OnToggleButton1.

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

Se llama aonAction cuando el usuario efectúa la tarea principal asociada a un control determinado. Por ejemplo, se llama al método de devolución de llamada onAction de un botón de alternancia cuando el usuario hace clic en el botón.

El método que especifique en el atributo puede tener cualquier nombre. Sin embargo, debe coincidir con el nombre del método que defina en el archivo de código de la cinta de opciones.

Hay muchos tipos diferentes de métodos de devolución de llamada que se pueden asignar a los controles de la cinta de opciones. Para obtener una lista completa de los métodos de devolución de llamada disponibles para cada control, consulte el artículo técnico Personalizar la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 3 de 3).

Definición de métodos de devolución de llamada

Defina los métodos de devolución de llamada en la clase Ribbon en el archivo de código de la cinta de opciones. Un método de devolución de llamada tiene varios requisitos:

  • Debe declararse como público.

  • Su nombre debe coincidir con el nombre de un método de devolución de llamada asignado a un control en el archivo XML de la cinta de opciones.

  • Su firma debe coincidir con la de un tipo de método de devolución de llamada que esté disponible para el control de cinta de opciones asociado.

    Para obtener una lista completa de las firmas de método de devolución de llamada para los controles de la cinta de opciones, consulte el artículo técnico Personalizar la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 3 de 3). Visual Studio no proporciona compatibilidad con IntelliSense para los métodos de devolución de llamada que se crean en el archivo de código de la cinta de opciones. Si crea un método de devolución de llamada que no coincide con una firma válida, se compilará el código, pero no ocurrirá nada cuando el usuario haga clic en el control.

    Todos los métodos de devolución de llamada tienen un parámetro IRibbonControl que representa el control que llamó al método. Puede usar este parámetro para reutilizar el mismo método de devolución de llamada en varios controles. En el siguiente ejemplo de código se muestra un método de devolución de llamada onAction que efectúa diferentes tareas según el control en el que el usuario hace 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.");
    }
}

Referencia de archivo XML de la cinta

Puede definir la cinta personalizada agregando elementos y atributos al archivo XML de la cinta de opciones. De forma predeterminada, el archivo XML de la cinta de opciones contiene el siguiente código 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>

En la siguiente tabla se describen los elementos predeterminados del archivo XML de la cinta de opciones.

Elemento Descripción
customUI Representa la cinta de opciones personalizada en el proyecto de complemento de VSTO.
ribbon Representa la cinta de opciones.
Pestañas Representa un conjunto de pestañas de la cinta de opciones.
pestaña Representa una sola pestaña de la cinta de opciones.
group Representa un grupo de controles en la pestaña de la cinta de opciones.

Estos elementos tienen atributos que especifican la apariencia y el comportamiento de la cinta personalizada. En la siguiente tabla se describen los atributos predeterminados del archivo XML de la cinta de opciones.

Attribute Elemento primario Descripción
Onload customUI Identifica un método al que se llama cuando la aplicación carga la cinta de opciones.
idMso pestaña Identifica una pestaña integrada que se va a mostrar en la cinta de opciones.
id group Identifica el grupo.
label group Especifica el texto que aparece en el grupo.

Los elementos y atributos predeterminados del archivo XML de la cinta de opciones son un subconjunto pequeño de los elementos y atributos disponibles. Para obtener una lista completa de los elementos y atributos disponibles, consulte el artículo técnico Personalizar la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 2 de 3).

Referencia de clase de cinta de opciones

Visual Studio genera la clase Ribbon en el archivo de código de la cinta de opciones. Agregue los métodos de devolución de llamada para los controles de la cinta de opciones a esta clase. Esta clase implementa la interfaz IRibbonExtensibility .

En la siguiente tabla se describen los métodos predeterminados de esta clase.

Method Descripción
GetCustomUI Devuelve el contenido del archivo XML de la cinta de opciones. Microsoft aplicación de Office lications llama a este método para obtener una cadena XML que define la interfaz de usuario de la cinta de opciones personalizada. Este método implementa el método GetCustomUI . Nota:GetCustomUI solo debe implementarse para devolver el contenido del archivo XML de la cinta de opciones; no debe usarse para inicializar el complemento vsTO. En particular, no debe intentar mostrar cuadros de diálogo u otras ventanas en la implementación GetCustomUI . De lo contrario, es posible que la cinta personalizada no se comporte correctamente. Si tiene que ejecutar código que inicialice el complemento de VSTO, agréguelo al controlador de eventos ThisAddIn_Startup .
OnLoad Asigne el parámetro IRibbonControl al campo Ribbon . Microsoft aplicación de Office lications llama a este método cuando cargan la cinta personalizada. Puede usar este campo para actualizar dinámicamente la cinta de opciones personalizada. Para obtener más información, vea el artículo técnico Personalizar la interfaz de usuario de la cinta de Opciones de Office (2007) para desarrolladores (parte 1 de 3).
GetResourceText Lo llama el método GetCustomUI para obtener el contenido del archivo XML de la cinta de opciones.

Contenido relacionado