Compartir a través de

Ribbon XML

  • Artículo

El elemento Cinta de opciones (XML) le permite personalizar una cinta de opciones mediante XML. Use el elemento Cinta de opciones (XML) si desea personalizar la cinta de opciones de un modo que el elemento Cinta de opciones (diseñador visual) no admite. Para comparar lo que puede hacer con cada elemento, consulte Información general de la cinta de opciones.

Aplicación: la información de este tema se aplica a los proyectos de nivel de documento y los proyectos de complemento de VSTO para las siguientes aplicaciones: Excel; InfoPath 2013 e InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto de Office.

Adición de un elemento 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 información detallada, consulte Referencia de archivo XML de la cinta de opciones 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 . Las aplicaciones de Microsoft Office usan una instancia de esta clase para cargar la cinta de opciones personalizada. Para obtener información detallada, consulte Referencia de la clase de cinta de opciones más adelante en este tema.

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

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

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

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();
}

Definición del comportamiento de la cinta de opciones personalizada

Puede responder a las acciones del 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, consulte Personalización de una cinta de opciones para Outlook.

Para ver un tutorial en el que se muestra cómo se automatiza una aplicación desde la cinta de opciones, consulte Tutorial: Creación de una pestaña personalizada con el XML de 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 Personalización de 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étodos de devolución de llamada para los controles de la cinta de opciones, consulte el artículo técnico Personalización de 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 de opciones

Puede definir su cinta de opciones 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 de opciones 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 muestra 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 Personalización de la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 2 de 3).

Referencia de la clase de cinta de opciones

Visual Studio genera la clase Ribbon en el archivo de código de la cinta de opciones. Agregue a esta clase los métodos de devolución de llamada para los controles de la cinta de opciones. 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. Las aplicaciones de Microsoft Office llaman a este método para obtener una cadena XML que define la interfaz de usuario de la cinta 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, puede que el comportamiento de la cinta de opciones personalizada no sea correcto. 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 . Las aplicaciones de Microsoft Office llaman a este método cuando cargan la cinta de opciones personalizada. Puede usar este campo para actualizar dinámicamente la cinta personalizada. Para obtener más información, consulte el artículo técnico Personalización de 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