Iniciar el complemento de Office

  • Artículo

Los complementos de Office suelen incluir lógica de inicio para realizar acciones como:

  • Compruebe que la versión del usuario de Office admite todas las API de Office a las que llama el código.

  • Asegúrese de la existencia de determinados artefactos, como una hoja de cálculo con un nombre específico.

  • Pida al usuario que seleccione algunas celdas en Excel e inserte un gráfico inicializado con esos valores seleccionados.

  • Establecer enlaces.

  • Use la API de cuadro de diálogo de Office para solicitar al usuario valores de configuración de complemento predeterminados.

Sin embargo, un complemento de Office no puede llamar correctamente a ninguna API de JavaScript de Office hasta que se haya cargado la biblioteca. En este artículo se describen las dos maneras en que el código puede asegurarse de que se ha cargado la biblioteca.

  • Inicialice con Office.onReady().
  • Inicialice con Office.initialize.

Sugerencia

Le recomendamos que use Office.onReady() en lugar de Office.initialize. Aunque Office.initialize todavía se admite, Office.onReady() proporciona más flexibilidad. Solo puede asignar un controlador a Office.initialize y la infraestructura de Office lo llama solo una vez. Puede llamar a Office.onReady() en diferentes lugares del código y usar devoluciones de llamada diferentes.

Para obtener información sobre las diferencias entre estas técnicas, vea Principales diferencias entre Office.initialize y Office.onReady().

Para información más detallada sobre la secuencia de eventos cuando se inicializa un complemento, consulte Cargar el DOM y el entorno de tiempo de ejecución.

Inicializar con Office.onReady()

Office.onReady() es una función asincrónica que devuelve un objeto Promise mientras comprueba si se carga la biblioteca de Office.js. Cuando se carga la biblioteca, resuelve promise como un objeto que especifica la aplicación cliente de Office con un valor de enumeración Office.HostType (Excel, Word, , etc.) y la plataforma con un valor de enumeración Office.PlatformType (PC, Mac, OfficeOnline, etc.). El objeto Promise se resuelve inmediatamente si la biblioteca ya se ha cargado al llamar a Office.onReady().

Una manera de llamar Office.onReady() a es pasarla una función de devolución de llamada. Por ejemplo:

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

Como alternativa, puede encadenar un método then() a la llamada de Office.onReady(), en lugar de pasar una devolución de llamada. Por ejemplo, el siguiente código comprueba que la versión del usuario de Excel es compatible con todas las API que el complemento puede llamar.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

Este es el mismo ejemplo con las async palabras clave y await en TypeScript.

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

Si usa marcos de JavaScript adicionales que incluyen su propio controlador de inicialización o pruebas, normalmente deben colocarse dentro de la respuesta a Office.onReady(). Por ejemplo, se haría referencia al método de$(document).ready() JQuery de la siguiente manera:

Office.onReady(function() {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
});

Sin embargo, hay excepciones para este procedimiento. Por ejemplo, supongamos que desea abrir el complemento en un explorador (en lugar de transferirlo de forma local en una aplicación de Office) para depurar la interfaz de usuario con herramientas del explorador. En este escenario, una vez que Office.js determina que se ejecuta fuera de una aplicación host de Office, llamará a la devolución de llamada y resolverá la promesa con null para el host y la plataforma.

Otra excepción sería si desea que aparezca un indicador de progreso en el panel de tareas mientras se carga el complemento. En este escenario, el código debe llamar a jQuery ready y usar su devolución de llamada para representar el indicador de progreso. A continuación, la devolución de Office.onReady llamada puede reemplazar el indicador de progreso por la interfaz de usuario final.

Inicializar con Office.initialize

Cuando la biblioteca Office.js está cargada y lista para la interacción del usuario, se desencadena un evento de inicialización. Puede asignar un controlador a Office.initialize que implementa la lógica de inicialización. El siguiente código es un ejemplo que comprueba que la versión del usuario de Excel es compatible con todas las API que el complemento puede llamar.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

Si usa marcos de JavaScript adicionales que incluyen su propio controlador de inicialización o pruebas, normalmente se deben colocar dentro del Office.initialize evento (las excepciones descritas en la sección Inicializar con Office.onReady() también se aplican anteriormente en este caso). Por ejemplo, se haría referencia al método de$(document).ready() JQuery de la siguiente manera:

Office.initialize = function () {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
  };

Para los complementos de contenido y del panel de tareas, Office.initialize proporciona un parámetro reason adicional. Este parámetro determina cómo se agregó un complemento al documento actual. Puede usar esto para proporcionar una lógica distinta para los casos en que un complemento se inserta primero en comparación a cuando ya existe en el documento.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

Para obtener más información, vea Evento Office.initialize y Enumeración InitializationReason.

Principales diferencias entre Office.initialize y Office.onReady

  • Puede asignar solo un controlador a Office.initialize y la infraestructura de Office lo llama una sola vez. Pero puede llamar a Office.onReady() en lugares diferentes del código y usar diferentes devoluciones de llamada. Por ejemplo, el código puede llamar a Office.onReady() en cuanto se carga el script personalizado con una devolución de llamada que ejecuta la lógica de inicialización, y el código también podría tener un botón en el panel de tareas, cuya script llame a Office.onReady() con una devolución de llamada diferente. Si es así, se ejecuta la segunda llamada al hacer clic en el botón.

  • El evento Office.initialize se activa al final del proceso interno en el que Office.js se inicializa. Y se activa inmediatamente tras la finalización del proceso interno. Si el código en el que asigna un controlador al evento se ejecuta demasiado tiempo después de que se desencadene el evento, el controlador no se ejecuta. Por ejemplo, si usa el administrador de tareas WebPack, puede configurar la página principal del complemento para cargar archivos polyfill cuando se cargue Office.js, pero antes de que se cargue el JavaScript personalizado. Cuando el script termina de cargarse y asignar el controlador, ya ha ocurrido el evento de inicialización. Pero nunca es "demasiado tarde" para llamar Office.onReady()a . Si ya ha ocurrido el evento de inicialización, la devolución de llamada se ejecuta inmediatamente.

Nota:

Aunque no tenga ninguna lógica de inicio, debe llamar a Office.onReady() o asignar una función vacía a Office.initialize cuando se cargue el JavaScript del complemento. Algunas combinaciones de aplicaciones y plataformas de Office no cargarán el panel de tareas hasta que se produzca una de ellas. Los siguientes ejemplos muestran estos dos métodos.

Office.onReady();

Office.initialize = function () {};

Inicialización de depuración

Para obtener información sobre la depuración de las Office.initialize funciones y Office.onReady() , vea Depurar las funciones initialize y onReady.

Vea también