Compartir a través de

Creación de pestañas contextuales personalizadas en complementos de Office

  • Artículo

Una pestaña contextual es un control de pestaña oculto en la cinta de Opciones de Office que se muestra en la fila de tabulación cuando se produce un evento especificado en el documento de Office. Por ejemplo, la pestaña Diseño de tabla que aparece en la cinta de opciones de Excel cuando se selecciona una tabla. Incluya pestañas contextuales personalizadas en el complemento de Office y especifique cuándo están visibles u ocultas, mediante la creación de controladores de eventos que cambien la visibilidad. (Sin embargo, las pestañas contextuales personalizadas no responden a los cambios de foco).

Nota:

En este artículo se supone que está familiarizado con los conceptos básicos de los comandos de complemento. Revíselo si no ha trabajado recientemente con comandos de complemento (elementos de menú personalizados y botones de la cinta de opciones).

Requisitos previos

Actualmente, las pestañas contextuales personalizadas solo se admiten en Excel y solo en las siguientes plataformas y compilaciones.

  • Excel en la web
  • Excel en Windows: versión 2102 (compilación 13801.20294) y versiones posteriores.
  • Excel en Mac: versión 16.53 (21080600) y versiones posteriores.

Además, las pestañas contextuales personalizadas solo funcionan en plataformas que admiten los siguientes conjuntos de requisitos. Para obtener más información sobre los conjuntos de requisitos y cómo trabajar con ellos, vea Especificar aplicaciones de Office y requisitos de API.

Sugerencia

Use las comprobaciones en tiempo de ejecución en el código para comprobar si la combinación de host y plataforma del usuario admite estos conjuntos de requisitos, tal como se describe en Comprobaciones en tiempo de ejecución de compatibilidad con el método y el conjunto de requisitos. (La técnica de especificar los conjuntos de requisitos en el manifiesto, que también se describe en ese artículo, no funciona actualmente para RibbonApi 1.2). Como alternativa, puede implementar una experiencia de interfaz de usuario alternativa cuando no se admiten pestañas contextuales personalizadas.

Comportamiento de pestañas contextuales personalizadas

La experiencia del usuario para pestañas contextuales personalizadas sigue el patrón de pestañas contextuales integradas de Office. A continuación se muestran los principios básicos de las pestañas contextuales personalizadas de colocación.

  • Cuando una pestaña contextual personalizada está visible, aparece en el extremo derecho de la cinta de opciones.
  • Si una o varias pestañas contextuales integradas y una o varias pestañas contextuales personalizadas de los complementos están visibles al mismo tiempo, las pestañas contextuales personalizadas siempre están a la derecha de todas las pestañas contextuales integradas.
  • Si el complemento tiene más de una pestaña contextual y hay contextos en los que más de una es visible, aparecen en el orden en que se definen en el complemento. (La dirección es la misma dirección que el idioma de Office; es decir, es de izquierda a derecha en idiomas de izquierda a derecha, pero de derecha a izquierda en idiomas de derecha a izquierda). Consulte Definición de los grupos y controles que aparecen en la pestaña para obtener más información sobre cómo definirlos.
  • Si más de un complemento tiene una pestaña contextual visible en un contexto específico, aparecen en el orden en que se iniciaron los complementos.
  • Las pestañas contextuales personalizadas, a diferencia de las pestañas principales personalizadas, no se agregan permanentemente a la cinta de opciones de la aplicación de Office. Solo están presentes en documentos de Office en los que se ejecuta el complemento.

Advertencia

Actualmente, el uso de pestañas contextuales personalizadas puede impedir que el usuario deshaga sus acciones anteriores de Excel. Se trata de un problema conocido (consulte este subproceso de GitHub) y está bajo investigación activa.

Pasos principales para incluir una pestaña contextual en un complemento

Estos son los pasos principales para incluir una pestaña contextual personalizada en un complemento.

  1. Configure el complemento para usar un entorno de ejecución compartido.
  2. Especifique los iconos de la pestaña contextual.
  3. Defina los grupos y controles que aparecen en la pestaña.
  4. Registre la pestaña contextual con Office.
  5. Especifique las circunstancias en las que la pestaña estará visible.

Configuración del complemento para usar un entorno de ejecución compartido

Agregar pestañas contextuales personalizadas requiere que el complemento use el entorno de ejecución compartido. Para obtener más información, consulte Configuración de un complemento para usar un entorno de ejecución compartido.

Especificar los iconos de la pestaña contextual

Antes de personalizar la pestaña contextual, primero debe especificar los iconos que aparecerán en ella con un elemento Image en la sección Resources del manifiesto del complemento. Cada icono debe tener al menos tres tamaños: 16x16 px, 32x32 px y 80x80 px.

A continuación se muestra un ejemplo.

<Resources>
    <bt:Images>
        <bt:Image id="contextual-tab-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"/>
        <bt:Image id="contextual-tab-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"/>
        <bt:Image id="contextual-tab-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"/>
        <bt:Image id="contextual-button-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"/>
        <bt:Image id="contextual-button-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"/>
        <bt:Image id="contextual-button-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"/>
    </bt:Images>
    ...
</Resources>

Importante

Al mover el complemento de desarrollo a producción, recuerde actualizar las direcciones URL del manifiesto según sea necesario (como cambiar el dominio de localhost a contoso.com).

Definir los grupos y controles que aparecen en la pestaña

A diferencia de las pestañas principales personalizadas, que se definen con XML en el manifiesto, las pestañas contextuales personalizadas se definen en tiempo de ejecución con un blob JSON. El código analiza el blob en un objeto JavaScript y, a continuación, pasa el objeto al método Office.ribbon.requestCreateControls . Las pestañas contextuales personalizadas solo están presentes en los documentos en los que el complemento se está ejecutando actualmente. Esto es diferente de las pestañas principales personalizadas que se agregan a la cinta de opciones de la aplicación de Office cuando el complemento está instalado y permanece presente cuando se abre otro documento. Además, el requestCreateControls método solo se puede ejecutar una vez en una sesión del complemento. Si se vuelve a llamar, se produce un error.

Nota:

La estructura de las propiedades y subpropiedades del blob JSON (y los nombres de clave) es aproximadamente paralela a la estructura del elemento CustomTab y sus elementos descendientes en el XML del manifiesto.

Crearemos un ejemplo de un blob JSON de pestañas contextuales paso a paso. El esquema completo de la pestaña contextual JSON está en dynamic-ribbon.schema.json. Si trabaja en Visual Studio Code, puede usar este archivo para obtener IntelliSense y validar el archivo JSON. Para obtener más información, consulte Edición de JSON con Visual Studio Code: esquemas y configuraciones JSON.

  1. Empiece por crear una cadena JSON con dos propiedades de matriz denominadas actions y tabs. La actions matriz es una especificación de todas las funciones que pueden ejecutarse mediante controles en la pestaña contextual. La tabs matriz define una o varias pestañas contextuales, hasta un máximo de 20.

    '{
  "actions": [

  ],
  "tabs": [

  ]
}'

  2. Este sencillo ejemplo de una pestaña contextual solo tendrá un solo botón y, por lo tanto, solo una sola acción. Agregue lo siguiente como único miembro de la actions matriz. Sobre este marcado, tenga en cuenta lo siguiente:

    • Las id propiedades y type son obligatorias.
    • El valor de type puede ser "ExecuteFunction" o "ShowTaskpane".
    • La functionName propiedad solo se usa cuando el valor de type es ExecuteFunction. Es el nombre de una función definida en FunctionFile. Para obtener más información sobre FunctionFile, vea Conceptos básicos de los comandos de complemento.
    • En un paso posterior, asignará esta acción a un botón de la pestaña contextual.
    {
  "id": "executeWriteData",
  "type": "ExecuteFunction",
  "functionName": "writeData"
}

  3. Agregue lo siguiente como único miembro de la tabs matriz. Sobre este marcado, tenga en cuenta lo siguiente:

    • La propiedad id es obligatoria. Use un identificador breve y descriptivo que sea único entre todas las pestañas contextuales del complemento.
    • La propiedad label es obligatoria. Se trata de una cadena fácil de usar que sirve como etiqueta de la pestaña contextual.
    • La propiedad groups es obligatoria. Define los grupos de controles que aparecerán en la pestaña. Debe tener al menos un miembro y no más de 20. (También hay límites en el número de controles que puede tener en una pestaña contextual personalizada y que también restringirán el número de grupos que tiene. Consulte el paso siguiente para obtener más información).

    Nota:

    El objeto tab también puede tener una propiedad opcional visible que especifica si la pestaña está visible inmediatamente cuando se inicia el complemento. Dado que las pestañas contextuales se ocultan normalmente hasta que un evento de usuario desencadena su visibilidad (por ejemplo, el usuario que selecciona una entidad de algún tipo en el documento), la propiedad tiene como visible valor predeterminado false cuando no está presente. En una sección posterior, se muestra cómo establecer la propiedad true en respuesta a un evento.

    {
  "id": "CtxTab1",
  "label": "Contoso Data",
  "groups": [

  ]
}

  4. En el ejemplo en curso simple, la pestaña contextual solo tiene un único grupo. Agregue lo siguiente como único miembro de la groups matriz. Sobre este marcado, tenga en cuenta lo siguiente:

    • Todas las propiedades son necesarias.
    • La id propiedad debe ser única entre todos los grupos del manifiesto. Use un identificador breve y descriptivo, de hasta 125 caracteres.
    • label es una cadena fácil de usar que sirve como etiqueta del grupo.
    • El icon valor de la propiedad es una matriz de objetos que especifican los iconos que el grupo tendrá en la cinta de opciones en función del tamaño de la cinta de opciones y de la ventana de la aplicación de Office.
    • El controls valor de la propiedad es una matriz de objetos que especifican los botones y menús del grupo. Debe haber al menos uno.

    Importante

    El número total de controles de toda la pestaña no puede ser superior a 20. Por ejemplo, podría tener 3 grupos con 6 controles cada uno y un cuarto grupo con 2 controles, pero no puede tener 4 grupos con 6 controles cada uno.

    {
    "id": "CustomGroup111",
    "label": "Insertion",
    "icon": [

    ],
    "controls": [

    ]
}

  5. Cada grupo debe tener un icono de al menos tres tamaños: 16x16 px, 32x32 px y 80x80 px. Opcionalmente, también puedes tener iconos de tamaños de 20x20 px, 24x24 px, 40x40 px, 48x48 px y 64x64 px. Office decide qué icono usar en función del tamaño de la cinta de opciones y de la ventana de la aplicación de Office. Agregue los siguientes objetos a la matriz de iconos. (Si los tamaños de la ventana y la cinta de opciones son lo suficientemente grandes como para que aparezca al menos uno de los controles del grupo, no aparece ningún icono de grupo. Por ejemplo, watch el grupo Estilos de la cinta de opciones de Word a medida que reduce y expande la ventana Word). Sobre este marcado, tenga en cuenta lo siguiente:

    • Ambas propiedades son necesarias.
    • La size unidad de medida de propiedad es píxeles. Los iconos siempre son cuadrados, por lo que el número es tanto el alto como el ancho.
    • La sourceLocation propiedad especifica la dirección URL completa del icono. Su valor debe coincidir con la dirección URL especificada en el <elemento Image> de la <sección Resources> del manifiesto (vea Especificar los iconos de la pestaña contextual).

    Importante

    Del mismo modo que normalmente debe cambiar las direcciones URL del manifiesto del complemento al pasar del desarrollo a la producción, también debe cambiar las direcciones URL de las pestañas contextuales JSON.

    {
    "size": 16,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
},
{
    "size": 32,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
},
{
    "size": 80,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
}

  6. En nuestro sencillo ejemplo en curso, el grupo solo tiene un solo botón. Agregue el siguiente objeto como único miembro de la controls matriz. Sobre este marcado, tenga en cuenta lo siguiente:

    • Se requieren todas las propiedades, excepto enabled, .
    • type especifica el tipo de control. Los valores pueden ser "Button", "Menu" o "MobileButton".
    • id puede tener hasta 125 caracteres.
    • actionId debe ser el identificador de una acción definida en la actions matriz. (Consulte el paso 1 de esta sección).
    • label es una cadena fácil de usar que sirve como etiqueta del botón.
    • superTip representa una forma enriquecida de información sobre herramientas. Se requieren las title propiedades y description .
    • icon especifica los iconos del botón. Aquí también se aplican los comentarios anteriores sobre el icono de grupo.
    • enabled (opcional) especifica si el botón está habilitado cuando aparece la pestaña contextual. El valor predeterminado si no está presente es true.
    {
    "type": "Button",
    "id": "CtxBt112",
    "actionId": "executeWriteData",
    "enabled": false,
    "label": "Write Data",
    "superTip": {
        "title": "Data Insertion",
        "description": "Use this button to insert data into the document."
    },
    "icon": [
        {
            "size": 16,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
        },
        {
            "size": 32,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
        },
        {
            "size": 80,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
        }
    ]
}

A continuación se muestra el ejemplo completo del blob JSON.

`{
  "actions": [
    {
      "id": "executeWriteData",
      "type": "ExecuteFunction",
      "functionName": "writeData"
    }
  ],
  "tabs": [
    {
      "id": "CtxTab1",
      "label": "Contoso Data",
      "groups": [
        {
          "id": "CustomGroup111",
          "label": "Insertion",
          "icon": [
            {
                "size": 16,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
            },
            {
                "size": 32,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
            },
            {
                "size": 80,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
            }
          ],
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "executeWriteData",
                "enabled": false,
                "label": "Write Data",
                "superTip": {
                    "title": "Data Insertion",
                    "description": "Use this button to insert data into the document."
                },
                "icon": [
                    {
                        "size": 16,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
                    },
                    {
                        "size": 32,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
                    },
                    {
                        "size": 80,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
                    }
                ]
            }
          ]
        }
      ]
    }
  ]
}`

Registrar la pestaña contextual con Office con requestCreateControls

La pestaña contextual se registra con Office llamando al método Office.ribbon.requestCreateControls . Normalmente, esto se hace en la función asignada a Office.initialize o con la Office.onReady función . Para obtener más información sobre estas funciones e inicializar el complemento, vea Inicializar el complemento de Office. Sin embargo, puede llamar al método en cualquier momento después de la inicialización.

Importante

Solo requestCreateControls se puede llamar al método una vez en una sesión determinada de un complemento. Se produce un error si se vuelve a llamar.

A continuación se muestra un ejemplo. Tenga en cuenta que la cadena JSON debe convertirse en un objeto JavaScript con el JSON.parse método antes de que se pueda pasar a una función de JavaScript.

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string such as the one at the end of the preceding section.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);
});

Especificar los contextos cuando la pestaña estará visible con requestUpdate

Normalmente, debería aparecer una pestaña contextual personalizada cuando un evento iniciado por el usuario cambia el contexto del complemento. Considere un escenario en el que la pestaña debe ser visible cuando y solo cuando se activa un gráfico (en la hoja de cálculo predeterminada de un libro de Excel).

Empiece por asignar controladores. Esto suele hacerse en la Office.onReady función, como en el ejemplo siguiente, que asigna controladores (creados en un paso posterior) a los onActivated eventos y onDeactivated de todos los gráficos de la hoja de cálculo.

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);

    await Excel.run(context => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(showDataTab);
        charts.onDeactivated.add(hideDataTab);
        return context.sync();
    });
});

A continuación, defina los controladores. A continuación se muestra un ejemplo sencillo de , showDataTabpero consulte Control del error HostRestartNeeded más adelante en este artículo para obtener una versión más sólida de la función. Sobre este código, tenga en cuenta:

  • Office controla cuando actualiza el estado de la cinta de opciones. El método Office.ribbon.requestUpdate pone en cola una solicitud de actualización. El método resolverá el Promise objeto tan pronto como haya puesto en cola la solicitud, no cuando la cinta de opciones se actualice realmente.
  • El parámetro del requestUpdate método es un objeto RibbonUpdaterData que (1) especifica la pestaña por su identificador exactamente como se especifica en json y (2) especifica la visibilidad de la pestaña.
  • Si tiene más de una pestaña contextual personalizada que debe estar visible en el mismo contexto, basta con agregar objetos de tabulación adicionales a la tabs matriz.
async function showDataTab() {
    await Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            }
        ]});
}

El controlador para ocultar la pestaña es casi idéntico, salvo que vuelve a establecer la visible propiedad en false.

La biblioteca de JavaScript de Office también proporciona varias interfaces (tipos) para facilitar la construcción delRibbonUpdateData objeto. La siguiente es la showDataTab función de TypeScript y hace uso de estos tipos.

const showDataTab = async () => {
    const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
    const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
    await Office.ribbon.requestUpdate(ribbonUpdater);
}

Alternar la visibilidad de tabulación y el estado habilitado de un botón al mismo tiempo

El requestUpdate método también se usa para alternar el estado habilitado o deshabilitado de un botón personalizado en una pestaña contextual personalizada o en una pestaña principal personalizada. Para obtener más información sobre esto, vea Habilitar y deshabilitar comandos de complemento. Puede haber escenarios en los que quiera cambiar tanto la visibilidad de una pestaña como el estado habilitado de un botón al mismo tiempo. Haga esto con una sola llamada de requestUpdate. A continuación se muestra un ejemplo en el que se habilita un botón de una pestaña principal al mismo tiempo que se hace visible una pestaña contextual.

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            },
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                            }
                        ]
                    }
                ]
            ]}
        ]
    });
}

En el ejemplo siguiente, el botón habilitado se encuentra en la misma pestaña contextual que se está haciendo visible.

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true,
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                           }
                       ]
                   }
               ]
            }
        ]
    });
}

Abrir un panel de tareas desde pestañas contextuales

Para abrir el panel de tareas desde un botón de una pestaña contextual personalizada, cree una acción en json con un type de ShowTaskpane. A continuación, defina un botón con la actionId propiedad establecida en de id la acción. Se abre el panel de tareas predeterminado especificado por el elemento Runtime> en el< manifiesto.

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

Para abrir cualquier panel de tareas que no sea el panel de tareas predeterminado, especifique una sourceLocation propiedad en la definición de la acción. En el ejemplo siguiente, se abre un segundo panel de tareas desde un botón diferente.

Importante

  • Cuando se especifica un sourceLocation objeto para la acción, el panel de tareas no usa el entorno de ejecución compartido. Se ejecuta en un nuevo entorno de ejecución independiente.
  • No más de un panel de tareas puede usar el entorno de ejecución compartido, por lo que no se puede omitir la sourceLocation propiedad más de una acción de tipoShowTaskpane.
`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    },
    {
      "id": "openTablesTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Tables",
      "supportPinning": false
      "sourceLocation": "https://MyDomain.com/myPage.html"
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            },
            {
                "type": "Button",
                "id": "CtxBt113",
                "actionId": "openTablesTaskpane",
                "enabled": false,
                "label": "Open Tables Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

Localización del texto JSON

El blob JSON al requestCreateControls que se pasa no está localizado de la misma manera que el marcado de manifiesto para las pestañas principales personalizadas (que se describe en Localización de control desde el manifiesto). En su lugar, la localización debe producirse en tiempo de ejecución mediante blobs JSON distintos para cada configuración regional. Se recomienda usar una switch instrucción que pruebe la propiedad Office.context.displayLanguage . A continuación se muestra un ejemplo.

function GetContextualTabsJsonSupportedLocale () {
    const displayLanguage = Office.context.displayLanguage;

        switch (displayLanguage) {
            case 'en-US':
                return `{
                    "actions": [
                        // actions omitted
                     ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Data",
                          "groups": [
                              // groups omitted
                          ]
                        }
                    ]
                }`;

            case 'fr-FR':
                return `{
                    "actions": [
                        // actions omitted 
                    ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Données",
                          "groups": [
                              // groups omitted
                          ]
                       }
                    ]
               }`;

            // Other cases omitted
       }
}

A continuación, el código llama a la función para obtener el blob localizado que se pasa a requestCreateControls, como en el ejemplo siguiente.

const contextualTabJSON = GetContextualTabsJsonSupportedLocale();

Procedimientos recomendados para pestañas contextuales personalizadas

Implementación de una experiencia de interfaz de usuario alternativa cuando no se admiten pestañas contextuales personalizadas

Algunas combinaciones de plataforma, aplicación de Office y compilación de Office no admiten requestCreateControls. El complemento debe diseñarse para proporcionar una experiencia alternativa a los usuarios que ejecutan el complemento en una de esas combinaciones. En las secciones siguientes se describen dos maneras de proporcionar una experiencia de reserva.

Usar controles o pestañas nocontextuales

Hay un elemento de manifiesto, OverriddenByRibbonApi, diseñado para crear una experiencia de reserva en un complemento que implementa pestañas contextuales personalizadas cuando el complemento se ejecuta en una aplicación o plataforma que no admite pestañas contextuales personalizadas.

La estrategia más sencilla para usar este elemento es definir una pestaña principal personalizada (es decir, una pestaña personalizada nocontextual ) en el manifiesto que duplica las personalizaciones de la cinta de opciones de las pestañas contextuales personalizadas del complemento. Pero se agrega <OverriddenByRibbonApi>true</OverriddenByRibbonApi> como el primer elemento secundario de los elementos Group, Control y Item> de menú< duplicados en las pestañas principales personalizadas. El efecto de hacerlo es el siguiente:

  • Si el complemento se ejecuta en una aplicación y plataforma que admiten pestañas contextuales personalizadas, los grupos y controles principales personalizados no aparecerán en la cinta de opciones. En su lugar, se creará la pestaña contextual personalizada cuando el complemento llame al requestCreateControls método .
  • Si el complemento se ejecuta en una aplicación o plataforma que no admite requestCreateControls, los elementos aparecen en la pestaña núcleo personalizado.

A continuación se muestra un ejemplo. Tenga en cuenta que "MyButton" aparecerá en la pestaña principal personalizada solo cuando no se admitan pestañas contextuales personalizadas. Pero el grupo primario y la pestaña principal personalizada aparecerán independientemente de si se admiten pestañas contextuales personalizadas.

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>              
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton1">
                  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
                  ...
                  <Action ...>
...
</OfficeApp>

Para obtener más ejemplos, vea OverriddenByRibbonApi.

Cuando un grupo primario o menú está marcado con <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, no es visible y todo su marcado secundario se omite cuando no se admiten pestañas contextuales personalizadas. Por lo tanto, no importa si alguno de esos elementos secundarios tiene el <elemento OverriddenByRibbonApi> o cuál es su valor. La implicación de esto es que si un elemento o control de menú debe estar visible en todos los contextos, no solo no debe estar marcado con <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, sino que su menú y grupo antecesores tampoco deben marcarse de esta manera.

Importante

No marque todos los elementos secundarios de un grupo o menú con <OverriddenByRibbonApi>true</OverriddenByRibbonApi>. Esto no tiene sentido si el elemento primario se marca con <OverriddenByRibbonApi>true</OverriddenByRibbonApi> por motivos dados en el párrafo anterior. Además, si deja fuera overriddenByRibbonApi<> en el elemento primario (o lo falseestablece en ), el elemento primario aparecerá independientemente de si se admiten pestañas contextuales personalizadas, pero estará vacío cuando se admitan. Por lo tanto, si no deben aparecer todos los elementos secundarios cuando se admiten pestañas contextuales personalizadas, marque el elemento primario con <OverriddenByRibbonApi>true</OverriddenByRibbonApi>.

Uso de API que muestran u ocultan un panel de tareas en contextos especificados

Como alternativa a <OverriddenByRibbonApi>, el complemento puede definir un panel de tareas con controles de interfaz de usuario que duplican la funcionalidad de los controles en una pestaña contextual personalizada. A continuación, use los métodos Office.addin.showAsTaskpane y Office.addin.hide para mostrar el panel de tareas cuando se habría mostrado la pestaña contextual si se admitiera. Para obtener más información sobre cómo usar estos métodos, vea Mostrar u ocultar el panel de tareas del complemento de Office.

Controlar el error HostRestartNeeded

En algunas situaciones, Office no puede actualizar la cinta de opciones y devolverá un error. Por ejemplo, si el complemento se actualiza y el complemento actualizado tiene un conjunto de comandos de complemento personalizado distinto, la aplicación de Office tiene que cerrarse y volver a abrirse. Hasta que sea así, el método requestUpdate devolverá el error HostRestartNeeded. El código debe controlar este error. A continuación se muestra un ejemplo de cómo hacerlo. En este caso, el método reportError muestra el error al usuario.

function showDataTab() {
    try {
        Office.ribbon.requestUpdate({
            tabs: [
                {
                    id: "CtxTab1",
                    visible: true
                }
            ]});
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, then close and reopen the Office application.");
        }
    }
}

Recursos