Mostrar u ocultar el panel de tareas de su complemento de Office

  • Artículo

Importante

El entorno de ejecución compartido solo se admite en algunas aplicaciones de Office. Para obtener más información, vea Conjuntos de requisitos de runtime compartido.

Puede mostrar el panel de tareas del complemento de Office llamando al Office.addin.showAsTaskpane() método .

function onCurrentQuarter() {
    Office.addin.showAsTaskpane()
    .then(function() {
        // Code that enables task pane UI elements for
        // working with the current quarter.
    });
}

El código anterior supone un escenario en el que hay una hoja de cálculo de Excel denominada CurrentQuarterSales. El complemento hará que el panel de tareas sea visible cada vez que se active esta hoja de cálculo. El método onCurrentQuarter es un controlador para el evento Office.Worksheet.onActivated que se ha registrado para la hoja de cálculo.

También puede ocultar el panel de tareas llamando al Office.addin.hide() método .

function onCurrentQuarterDeactivated() {
    Office.addin.hide();
}

El código anterior es un controlador registrado para el evento Office.Worksheet.onDeactivated .

Detalles adicionales sobre cómo mostrar el panel de tareas

Al llamar a Office.addin.showAsTaskpane(), Office mostrará en un panel de tareas el archivo que asignó como valor del identificador de recurso (resid) del panel de tareas. Este resid valor se puede asignar o cambiar abriendo el archivo manifest.xml y localizando <SourceLocation> dentro del <Action xsi:type="ShowTaskpane"> elemento. (Consulte Configuración del complemento de Office para usar un entorno de ejecución compartido para obtener más detalles).

Dado que Office.addin.showAsTaskpane() es un método asincrónico, el código seguirá ejecutándose hasta que se complete el método. Espere a que se complete con la await palabra clave o un then() método, en función de la sintaxis de JavaScript que use.

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

Para usar los showAsTaskpane() métodos y hide() , el complemento debe usar el entorno de ejecución compartido. Para obtener más información, vea Configurar el complemento de Office para usar un entorno de ejecución compartido.

Conservación de agentes de escucha de estado y eventos

Los hide() métodos y showAsTaskpane() solo cambian la visibilidad del panel de tareas. No lo descargan ni recargan (ni reinicializan su estado).

Tenga en cuenta el escenario siguiente: Un panel de tareas está diseñado con pestañas. La pestaña Inicio está abierta cuando se inicia el complemento por primera vez. Supongamos que un usuario abre la pestaña Configuración y, más adelante, el código del panel de tareas llama hide() en respuesta a algún evento. Llamadas de código posteriores showAsTaskpane() en respuesta a otro evento. El panel de tareas volverá a aparecer y la pestaña Configuración todavía está seleccionada.

Panel de tareas que tiene cuatro pestañas con las etiquetas Inicio, Configuración, Favoritos y Cuentas.

Además, los agentes de escucha de eventos registrados en el panel de tareas siguen ejecutándose incluso cuando el panel de tareas está oculto.

Tenga en cuenta el escenario siguiente: El panel de tareas tiene un controlador registrado para Excel Worksheet.onActivated y Worksheet.onDeactivated eventos para una hoja denominada Sheet1. El controlador activado hace que aparezca un punto verde en el panel de tareas. El controlador desactivado convierte el punto rojo (que es su estado predeterminado). Supongamos que ese código llama hide() cuando Sheet1 no está activado y el punto es rojo. Mientras el panel de tareas está oculto, Sheet1 se activa. Llamadas de código posteriores showAsTaskpane() en respuesta a algún evento. Cuando se abre el panel de tareas, el punto es verde porque los agentes de escucha y controladores de eventos se ejecutaron aunque el panel de tareas estuviera oculto.

Controlar el evento de cambio de visibilidad

Cuando el código cambia la visibilidad del panel de tareas con showAsTaskpane() o hide(), Office desencadena el VisibilityModeChanged evento. Puede ser útil controlar este evento. Por ejemplo, supongamos que el panel de tareas muestra una lista de todas las hojas de un libro. Si se agrega una nueva hoja de cálculo mientras el panel de tareas está oculto, hacer visible el panel de tareas no agregaría en sí mismo el nuevo nombre de hoja de cálculo a la lista. Pero el código puede responder al evento para volver a VisibilityModeChanged cargar la propiedad Worksheet.name de todas las hojas de cálculo de la colección Workbook.worksheets , como se muestra en el código de ejemplo siguiente.

Para registrar un controlador para el evento, no se usa un método "add handler" como lo haría en la mayoría de los contextos de JavaScript de Office. En su lugar, hay una función especial a la que se pasa el controlador: Office.addin.onVisibilityModeChanged. A continuación se muestra un ejemplo. Tenga en cuenta que la propiedad es de args.visibilityMode tipo VisibilityMode.

Office.addin.onVisibilityModeChanged(function(args) {
    if (args.visibilityMode == "Taskpane") {
        // Code that runs whenever the task pane is made visible.
        // For example, an Excel.run() that loads the names of
        // all worksheets and passes them to the task pane UI.
    }
});

La función devuelve otra función que anula el registro del controlador. Este es un ejemplo sencillo, pero no sólido.

const removeVisibilityModeHandler =
    Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });


// In some later code path, deregister with:
removeVisibilityModeHandler();

El onVisibilityModeChanged método es asincrónico y devuelve una promesa, lo que significa que el código debe esperar el cumplimiento de la promesa antes de que pueda llamar al controlador de anulación del registro .

// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
    await Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });

La función de anulación del registro también es asincrónica y devuelve una promesa. Por lo tanto, si tiene código que no debe ejecutarse hasta que se complete la cancelación de registro, debe esperar la promesa devuelta por la función de anulación del registro.

// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here

Vea también