Compartir a través de

Cambiar la disponibilidad de los comandos de complemento

  • Artículo

Cuando algunas funciones del complemento solo deben estar disponibles en determinados contextos, puede configurar mediante programación los comandos de complemento personalizados para que solo estén disponibles en estos contextos. Por ejemplo, una función que cambia el encabezado de una tabla solo debe estar disponible cuando el cursor está en una tabla.

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).

Funciones admitidas

Puede cambiar mediante programación la disponibilidad de un comando de complemento para las siguientes funcionalidades.

  • Botones, menús y pestañas de la cinta de opciones.
  • Elementos del menú contextual.

Compatibilidad con aplicaciones y conjuntos de requisitos de Office

En la tabla siguiente se describen las aplicaciones de Office que admiten la configuración de la disponibilidad de los comandos de complemento. También se enumeran los conjuntos de requisitos necesarios para usar la API.

Funcionalidad de comandos de complemento Conjunto de requisitos Aplicaciones de Office compatibles
Botones, menús y pestañas de la cinta de opciones RibbonApi 1.1
  • Excel
  • PowerPoint
  • Word
Elementos de menú contextual ContextMenuApi 1.1
  • Excel
  • PowerPoint
  • Word

Sugerencia

Para obtener información sobre cómo probar la compatibilidad de la plataforma con conjuntos de requisitos, consulte Versiones y conjuntos de requisitos de Office.

Configuración de un entorno de ejecución compartido

Para cambiar la disponibilidad de un control o elemento de la cinta de opciones o del menú contextual, el manifiesto del complemento debe configurarse primero para usar un entorno de ejecución compartido. Para obtener instrucciones sobre cómo configurar un entorno de ejecución compartido, consulte Configuración del complemento de Office para usar un entorno de ejecución compartido.

Cambiar mediante programación la disponibilidad de un comando de complemento

Desactivación de controles de la cinta de opciones en el inicio

Nota:

Solo los controles de la cinta de opciones se pueden desactivar cuando se inicia la aplicación de Office. No se pueden desactivar los controles personalizados agregados a un menú contextual en el inicio.

De forma predeterminada, un botón personalizado o un elemento de menú de la cinta de opciones está disponible para su uso cuando se inicia la aplicación de Office. Para desactivarlo cuando se inicia Office, debe especificarlo en el manifiesto. El proceso depende del tipo de manifiesto que use el complemento.

Manifiesto unificado para Microsoft 365

Nota:

El manifiesto unificado para Microsoft 365 se puede usar en complementos de Outlook de producción. Solo está disponible como versión preliminar para excel, PowerPoint y complementos de Word.

Solo tiene que agregar una propiedad "enabled" con el valor false al objeto de elemento de control o de menú. A continuación se muestra la estructura básica.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Manifiesto de solo complemento

Solo tiene que agregar un elemento Enabled inmediatamente debajo (no dentro) del elemento Action del elemento de control. A continuación, establezca su valor en false.

A continuación se muestra la estructura básica de un manifiesto que configura el <elemento Enabled> .

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

Cambiar la disponibilidad de un control de cinta de opciones

Para actualizar la disponibilidad de un botón o elemento de menú en la cinta de opciones, realice los pasos siguientes.

  1. Cree un objeto RibbonUpdaterData que especifique lo siguiente:
    • Los identificadores del comando, incluidos su grupo primario y su pestaña. Los identificadores deben coincidir con los declarados en el manifiesto.
    • Estado de disponibilidad del comando.
  2. Pase el objeto RibbonUpdaterData al método Office.ribbon.requestUpdate().

A continuación puede ver un ejemplo simple. Tenga en cuenta que "MyButton", "OfficeAddinTab1" y "CustomGroup111" se copian del manifiesto.

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

Hay varias interfaces (tipos) para facilitar la construcción del objeto RibbonUpdateData .

El siguiente es el ejemplo equivalente de TypeScript y usa estos tipos.

const enableButton = async () => {
    const button: Control = { id: "MyButton", enabled: true };
    const parentGroup: Group = { id: "CustomGroup111", controls: [button] };
    const parentTab: Tab = { id: "OfficeAddinTab1", groups: [parentGroup] };
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

Sugerencia

Puede await llamar a requestUpdate() si la función primaria es asincrónica, pero tenga en cuenta que la aplicación de Office controla cuando actualiza el estado de la cinta de opciones. El método requestUpdate() coloca una solicitud en la cola de actualización. El método resolverá el objeto de promesa tan pronto como haya puesto en cola la solicitud, no cuando la cinta de opciones se actualice realmente.

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

El método requestUpdate también se usa para alternar la visibilidad de una pestaña contextual personalizada. Para obtener más información sobre este código y de ejemplo, vea Crear pestañas contextuales personalizadas en complementos de Office.

Cambiar el estado en respuesta a un evento

Un escenario común en el que el estado de una cinta de opciones o un control de menú contextual debe cambiar es cuando un evento iniciado por el usuario cambia el contexto del complemento. Considere un escenario en el que un botón debe estar disponible cuando y solo cuando se activa un gráfico. Aunque en el ejemplo siguiente se usan controles de cinta de opciones, se puede aplicar una implementación similar a los elementos personalizados de un menú contextual.

  1. En primer lugar, establezca el <elemento Enabled> del botón del manifiesto falseen . Para obtener instrucciones sobre cómo configurar esto, vea Desactivar controles de la cinta de opciones en el inicio.

  2. A continuación, asigne controladores. Esto suele hacerse en la función Office.onReady , como en el ejemplo siguiente. En el ejemplo, los controladores (creados en un paso posterior) se asignan a los eventos onActivated y onDeactivated de todos los gráficos de una hoja de cálculo de Excel.

    Office.onReady(async () => {
    await Excel.run((context) => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(enableChartFormat);
        charts.onDeactivated.add(disableChartFormat);
        return context.sync();
    });
});

  3. Defina el enableChartFormat controlador. A continuación puede ver un ejemplo simple. Para obtener una forma más sólida de cambiar el estado de un control, consulte Procedimiento recomendado: Prueba de errores de estado de control.

    function enableChartFormat() {
    const button =
        {
            id: "ChartFormatButton",
            enabled: true
        };
    const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
    const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

  4. Defina el disableChartFormat controlador. Es idéntico al enableChartFormat controlador, salvo que la propiedad enabled del objeto button está establecida en false.

Procedimiento recomendado: probar errores de estado de control

En algunas circunstancias, la cinta de opciones o el menú contextual no se vuelve a dibujar después requestUpdate de llamar a, por lo que el estado del control en el que se puede hacer clic no cambia. Por este motivo, se recomienda que el complemento realice un seguimiento del estado de sus controles. El complemento debe cumplir las reglas siguientes.

  • Siempre que se llama a requestUpdate, el código debe registrar el estado deseado de los botones personalizados y los elementos del menú.
  • Cuando se selecciona un control personalizado, el primer código del controlador debe comprobar si el botón debería estar disponible. Si no debería haber estado disponible, el código debe notificar o registrar un error e intentarlo de nuevo para establecer los botones en el estado previsto.

En el ejemplo siguiente se muestra una función que desactiva un botón de la cinta de opciones y registra el estado del botón. En este ejemplo, chartFormatButtonEnabled es una variable booleana global que se inicializa en el mismo valor que el elemento Enabled del botón del manifiesto del complemento. Aunque en el ejemplo se usa un botón de cinta de opciones, se puede aplicar una implementación similar a los elementos personalizados de un menú contextual.

function disableChartFormat() {
    const button =
    {
        id: "ChartFormatButton",
        enabled: false
    };
    const parentGroup =
    {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab =
    {
        id: "CustomChartTab",
        groups: [parentGroup]
    };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

En el ejemplo siguiente se muestra cómo comprueba el controlador del botón si el botón está en un estado incorrecto. Tenga en cuenta que reportError es una función que muestra o registra un error.

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here.

    } else {
        // Report the error and try to make the button unavailable again.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Control de errores

En algunos escenarios, Office no puede actualizar la cinta de opciones o el menú contextual 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 siguiente es un ejemplo de cómo controlar este error. En este caso, el método reportError muestra el error al usuario. Aunque en el ejemplo se usa un botón de cinta de opciones, se puede aplicar una implementación similar a los elementos personalizados de un menú contextual.

function disableChartFormat() {
    try {
        const button =
        {
            id: "ChartFormatButton",
            enabled: false
        };
        const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
        const ribbonUpdater = { tabs: [parentTab] };
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

Vea también